Skip to content

Commit 33968cf

Browse files
authored
feat: grade shell commands by what they run, add self-update command (#4)
* feat: grade shell commands by what they run instead of flagging every call Every Executor call was High, so every terminal plugin needed review even when it only ran `uname -m` or `apk add git`. - Split each command like a shell (`;`, `&&`, `||`, pipes, subshells, `$(…)`) and grade each part: read-only commands are Low, visible commands with side effects are Medium, and only commands the scanner cannot see (runtime command name, `sh -c $x`, `eval`, `node -e`, text piped into a shell) are High. Runtime values keep a command at Medium. - Follow command helpers (`const sh = c => Executor.execute(c)`, `this.run(cmd)`), so each call is graded with its own command; closed helpers add no finding of their own. - Resolve getters (`getExecutor()`), which hid all shell use, plus shell-quoting helpers, `JSON.stringify`, template-building functions, `$VAR` names assigned in the same script, proot/chroot wrappers, and every branch of `a ? "x" : "y"`. - `Executor.write` to a program the plugin started is input (Low), not a command. Unknown text typed into a terminal tab is Medium; a runtime command followed by Enter is High. Requiring the terminal module is Medium. - Stop dangerous-command look-alikes: `rm -rf ~/.cache/x` is not wiping home, reading `/etc/profile` is not persistence, Acode's own data folder is not another app's, `crontab -l` is not scheduling. - `diff` treats a new Medium shell command as a reason to review and ignores new read-only ones. - Bump rules version to 2026.11.1. * feat: add `update` command to replace the installed binary in place Updating meant finding the right release asset by hand and copying it over the old binary. `plugin_scanner update` (alias `self-update`) reads the latest release from the GitHub API, downloads the build for this platform with curl (or wget), checks it against the published .sha256 and GitHub's own digest, runs it once with --version, and only then renames it over the running executable. A failed step leaves the current binary untouched. - `--check` only reports whether a newer release exists. - `--version <x>` installs a specific release, including a downgrade. - `--force` reinstalls the current version. - A permission error suggests sudo; platforms without a prebuilt build point to `cargo install --git`.
1 parent 1918743 commit 33968cf

10 files changed

Lines changed: 2629 additions & 70 deletions

File tree

‎README.md‎

Lines changed: 44 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -22,12 +22,16 @@ plugin_scanner scan plugin.zip --json --fail-on review
2222

2323
# Compare the published version with an uploaded update
2424
plugin_scanner diff published.zip update.zip --format json --fail-on review
25+
26+
# Update an installed binary in place to the latest release
27+
plugin_scanner update
2528
```
2629

2730
| Command / flag | What it does |
2831
| --- | --- |
2932
| `scan <zip>` | Full scan. Formats: `--format terminal` (default), `json`, `md` (reviewer report), `summary` (short user-facing disclosure). Shorthands: `--json`, `--markdown`, `--summary`. |
3033
| `diff <old> <new>` | What changed between two versions: new or escalated findings, new hosts, modules, permissions, changed files. `--format terminal\|json\|md`. |
34+
| `update` | Replace the running binary with the latest GitHub release (Linux x86_64/arm64, macOS arm64). `--check` only reports, `--version 0.3.0` installs a specific release (also downgrades), `--force` reinstalls. Needs `curl` or `wget`. The download is checked against the published `.sha256` and GitHub's digest, and run once before it replaces anything; use `sudo` if the binary is in a system folder. |
3135
| `--fail-on <level>` | Exit 1 when reached. For `scan`: `info`…`critical` (highest severity) or `review` / `block` (recommendation). For `diff`: `review` / `block`. |
3236
| `--entry-only` | Only analyse the script Acode loads. By default every JS/HTML file is analysed, because the entry script can load the rest at runtime. |
3337
| `--max-entry-bytes`, `--max-total-bytes`, `--max-entries` | Zip-bomb limits (defaults: 32 MiB per entry, 256 MiB total, 5000 entries). |
@@ -39,16 +43,17 @@ threshold reached, `2` unreadable archive or other error.
3943

4044
| Recommendation | Meaning | Typical cause |
4145
| --- | --- | --- |
42-
| `pass` | Nothing above Medium. Safe to publish without a human look. | Normal editor plugins: fs, fetch, commands, storage, settings. |
43-
| `review` | Something powerful enough that a person should look. | Shell/terminal access, all-files permission, Play billing, obfuscation, tampering with other plugins, decoded code execution, scan incomplete. |
46+
| `pass` | Nothing above Medium. Safe to publish without a human look. | Normal editor plugins: fs, fetch, commands, storage, settings. Terminal plugins whose shell commands are all visible (`apk add`, `npm install`, `uname -m`). |
47+
| `review` | Something powerful enough that a person should look. | Shell commands the scanner cannot see (built at runtime, `sh -c $x`, piped into a shell), all-files permission, Play billing, obfuscation, tampering with other plugins, decoded code execution, scan incomplete. |
4448
| `block` | A Critical finding: no legitimate plugin needs it, or the zip is built to confuse the installer. | Remote code or shell commands, core-module hijack, download-and-run shell commands, plugin-context bridge calls, planting an acode.app session, rewriting its own entry script, exfiltration to webhooks, install-path collisions, a `main` the loader resolves outside the plugin, no `plugin.json`. |
4549

46-
For **updates**, use `diff`. A terminal plugin always comes out as `review`
47-
on a full scan, but if nothing new appears in the diff, the update is `pass`.
48-
Updates that add a High/Critical capability, a new declared permission, or a
49-
new flagged host are `review` (or `block`). So are updates that keep a
50-
capability but use it with new arguments: a terminal plugin that starts
51-
running a different shell command, a new native `Service.action`, or a new
50+
For **updates**, use `diff`. If nothing new appears in the diff, the update is
51+
`pass`, even for a plugin that needed a review on its full scan. Updates that
52+
add a High/Critical capability, a new declared permission, or a new flagged
53+
host are `review` (or `block`). So are updates that keep a capability but use
54+
it with new arguments: a terminal plugin that starts running a different
55+
shell command (any command with side effects, even a Medium one; new
56+
read-only commands don't count), a new native `Service.action`, or a new
5257
remote script URL.
5358

5459
Severity guide:
@@ -76,6 +81,35 @@ plugin as critical (`e.read()`, `n.copy()`, `window.cordova`, webpack's
7681
`fromCharCode`...) and Critical when it comes from a network response.
7782
Bundler idioms (`Function("return this")`, `<script>` chunk loaders with
7883
relative URLs) are ignored.
84+
- **Shell commands are graded by what they run.** Each command is split like
85+
a shell would (`;`, `&&`, `||`, pipes, subshells, `$(…)`), and each part is
86+
graded:
87+
- **Low**: only read-only commands (`uname -m`, `command -v x`, `cat`,
88+
`ls`, `test -f`, `tool --version`, `npm root -g`).
89+
- **Medium**: visible commands with side effects (installing packages,
90+
moving files, starting a local server, running a proot container), and
91+
any command with a value the scanner can't work out (`cat "${path}"`).
92+
- **High**: the scanner can't see what runs: the command name is built at
93+
runtime or is an unset `$VAR`, `sh -c` / `eval` / `node -e` get a runtime
94+
string, or text is piped into a shell or interpreter.
95+
- Known-bad patterns (download-and-run, reverse shells, wiping
96+
storage...) are still matched on top of this. They only match the
97+
dangerous form: `rm -rf ~/` is Critical, `rm -rf ~/.cache/x` is not;
98+
reading `/etc/profile` is not persistence; Acode's own
99+
`/data/data/com.foxdebug.acode…` folder is not another app's.
100+
- **Shell helpers are followed.** In `const sh = c => Executor.execute(c)`,
101+
each `sh("…")` call is graded with its own command. When every use of the
102+
helper is a direct call, the helper's body adds no finding of its own. The
103+
scanner also follows `this.run(cmd)` methods, getters such as
104+
`getExecutor()`, quoting helpers (`'${s.replace(/'/g, …)}'`,
105+
`JSON.stringify`), functions that build a script from a template, `$VAR`
106+
names assigned earlier in the same script, and every branch of
107+
`a ? "x" : "y"`.
108+
- **Process input is not a command.** Text written with `Executor.write` to a
109+
program the plugin started (a language server, a kernel driver) is input
110+
(Low). It is graded as a command only when the started process is a shell
111+
or can't be seen. Unknown text typed into a terminal tab is Medium (it is
112+
usually log output); a runtime command followed by Enter is High.
79113
- **Aggregation.** One finding per rule, stable key, and file, with an
80114
occurrence count and up to 8 locations.
81115
- **Endpoints are inventory.** URLs go into an `endpoints` list. Only known
@@ -128,7 +162,7 @@ plugin as critical (`e.read()`, `n.copy()`, `window.cordova`, webpack's
128162
| --- | --- |
129163
| Archive | `install_path_collision` (C), `path_traversal`, `duplicate_entry`, `encrypted_entry`, `unsupported_compression`, `oversized_entry`, `total_size_limit`, `too_many_entries`, `native_binary` (H), `absolute_path`, `nested_archive`, `metadata_path_content` (M) |
130164
| Manifest | `missing`, `invalid_json`, `no_entrypoint`, `main_escapes_plugin_dir` (C), `missing_id/name/version`, `readme_password_form` (readme or changelog renders a password form; DOMPurify keeps forms) (H), `invalid_id`, `invalid_version`, `invalid_price`, `invalid_min_version_code`, `missing_icon`, `missing_readme`, `non_js_entry`, `main_loader_mismatch`, `readme_form` (M), `dependencies`, `icon_too_large` (L), `main_fallback` (I) |
131-
| Shell | `remote_command` (C), `decoded_command` (H), `dangerous_command` (C/H/M: download-and-run, decode-and-run, reverse shell, miner, wiping `/sdcard`/`$HOME`, other apps' data, `su`, download-then-chmod, SSH keys / stored credentials, curl file uploads, piping env or files to the network, untrusted package sources, cron/boot persistence, shell-profile persistence), `load_library` (C), `exec`, `terminal_module` (H), `terminal_environment`, `process_control` (M/H), `script_file` (L; shipped `.sh` / `#!` scripts get the same command checks) |
165+
| Shell | `remote_command` (C), `decoded_command` (H), `dangerous_command` (C/H/M: download-and-run, decode-and-run, reverse shell, miner, wiping `/sdcard`/`$HOME`, other apps' data, `su`, download-then-chmod, SSH keys / stored credentials, curl file uploads, piping env or files to the network, untrusted package sources, cron/boot persistence, shell-profile persistence), `load_library` (C), `exec` (H/M/L by what the command runs; keys end in `:program`, `:inspect`, or `write:input`), `terminal_module`, `terminal_environment`, `process_control` (M/H), `script_file` (L; shipped `.sh` / `#!` scripts get the same command checks) |
132166
| Native | `plugin_context_bridge` (`cordova.exec` to `Tee`), `cordova_exec_dynamic` (C), `account_bridge` (`Authenticator`; C for `saveToken`, else H), `cordova_exec`, `manage_all_files`, `in_app_purchase` (H), `permission_request`, `launch_app`, `intent_access`, `purchase_read`, `cordova_require`, `cordova_plugin` (M), `file_intent`, `device_setting`, `os_integration` (L) |
133167
| Tampering | `core_module_override` (`acode.define("fs")` etc.) (C), `self_modify` (writes scripts or `plugin.json` where code is loaded from; C when the content is downloaded or it rewrites the entry/manifest, else H), `acode_api`, `cordova_bridge`, `network_hook`, `native_api` (hooks `system`, `Executor`, `sdcard`…), `dom_hook` (wraps `addEventListener`, `appendChild`, input `value`…), `ads`, `plugin_settings` (edits `pluginsDisabled`), `other_plugin`, `plugin_files` (writes into another plugin's folder), `rewards` (H), `editor_manager`, `define_dynamic`, `unmount_dynamic` (M) |
134168
| Dynamic code | `remote_code`, `remote_import` (C), `remote_script`, `remote_worker`, `decoded_exec`, `indirect_function_constructor` (H), `eval`, `function_constructor`, `inline_script`, `script_blob`, `html_script`, `remote_html`, `decoded_html` (M: `innerHTML`, `insertAdjacentHTML`, `createContextualFragment`, `srcdoc`, `on*` attributes), `string_timer`, `script_element`, `import_expression`, `inline_handler` (L) |
@@ -147,7 +181,7 @@ Prefixes are omitted in the table; full IDs look like `shell.exec`.
147181
{
148182
"schema_version": 2,
149183
"scanner_version": "0.3.0",
150-
"rules_version": "2026.10.3", // rescan stored plugins when this changes
184+
"rules_version": "2026.11.1", // rescan stored plugins when this changes
151185
"plugin": { "id", "name", "version", "main", "entry", "permissions", "dependencies", ... },
152186
"verdict": { "risk": "high", "recommendation": "review", "complete": true, "reasons": ["..."] },
153187
"summary": { "total_findings", "by_severity", "by_category" },

‎src/analysis.rs‎

Lines changed: 24 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -459,17 +459,30 @@ mod tests {
459459
}
460460

461461
#[test]
462-
fn terminal_plugin_needs_review_but_not_block() {
463-
let report = scan(&[
464-
MANIFEST,
465-
ICON,
466-
README,
467-
(
468-
"main.js",
469-
b"Executor.execute('apk add python3'); acode.require('terminal');",
470-
),
471-
]);
472-
assert_eq!(report.verdict.recommendation, Recommendation::Review);
462+
fn terminal_plugin_is_graded_by_its_commands() {
463+
let verdict = |source: &[u8]| {
464+
scan(&[MANIFEST, ICON, README, ("main.js", source)])
465+
.verdict
466+
.recommendation
467+
};
468+
// Visible commands: disclosed, but no review needed.
469+
assert_eq!(
470+
verdict(b"Executor.execute('apk add python3'); acode.require('terminal');"),
471+
Recommendation::Pass
472+
);
473+
assert_eq!(
474+
verdict(b"(() => { const sh = c => Executor.execute(c); sh('uname -m'); sh('npm i -g x'); })()"),
475+
Recommendation::Pass
476+
);
477+
// A command the scanner cannot see needs a person, but is not blocked.
478+
assert_eq!(
479+
verdict(b"Executor.execute(localStorage.getItem('cmd'))"),
480+
Recommendation::Review
481+
);
482+
assert_eq!(
483+
verdict(b"Executor.execute(`sh -c ${JSON.stringify(input.value)}`)"),
484+
Recommendation::Review
485+
);
473486
}
474487

475488
#[test]

‎src/cli.rs‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,19 @@ pub enum Command {
6868
#[command(flatten)]
6969
limits: LimitArgs,
7070
},
71+
/// Update this binary to the latest GitHub release, in place.
72+
#[command(alias = "self-update")]
73+
Update {
74+
/// Only check whether a newer release exists.
75+
#[arg(long)]
76+
check: bool,
77+
/// Install this release (e.g. 0.3.0 or v0.3.0) instead of the latest.
78+
#[arg(long, value_name = "VERSION")]
79+
version: Option<String>,
80+
/// Reinstall even if this version is already installed.
81+
#[arg(long)]
82+
force: bool,
83+
},
7184
}
7285

7386
#[derive(Debug, Args)]

‎src/diff.rs‎

Lines changed: 57 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -53,11 +53,11 @@ const ARGUMENT_RULES: &[&str] = &[
5353
/// Every evidence string per stable key, across files.
5454
fn arguments_by_key(report: &Report) -> BTreeMap<&str, BTreeSet<&str>> {
5555
let mut map: BTreeMap<&str, BTreeSet<&str>> = BTreeMap::new();
56-
for finding in report
57-
.findings
58-
.iter()
59-
.filter(|finding| ARGUMENT_RULES.contains(&finding.id.as_str()))
60-
{
56+
// Low argument findings (read-only shell commands, process input) change
57+
// nothing worth a look.
58+
for finding in report.findings.iter().filter(|finding| {
59+
ARGUMENT_RULES.contains(&finding.id.as_str()) && finding.severity >= Severity::Medium
60+
}) {
6161
let entry = map.entry(finding.key.as_str()).or_default();
6262
entry.insert(finding.evidence.as_str());
6363
entry.extend(finding.all_evidence.iter().map(String::as_str));
@@ -246,10 +246,14 @@ pub fn diff(old: &Report, new: &Report) -> DiffReport {
246246
new_info.id.as_deref().unwrap_or("")
247247
));
248248
}
249-
for finding in new_findings
250-
.iter()
251-
.filter(|finding| finding.severity >= Severity::High)
252-
{
249+
// A capability whose arguments matter (a shell command, a native action)
250+
// is worth a look as soon as it is Medium: a terminal plugin that starts
251+
// installing a new package is a new action even though it is not High.
252+
for finding in new_findings.iter().filter(|finding| {
253+
finding.severity >= Severity::High
254+
|| (finding.severity >= Severity::Medium
255+
&& ARGUMENT_RULES.contains(&finding.id.as_str()))
256+
}) {
253257
reasons.push(format!(
254258
"New {}: {} [{}]",
255259
finding.severity.label(),
@@ -492,6 +496,50 @@ mod tests {
492496
assert_eq!(diff.recommendation, Recommendation::Pass);
493497
}
494498

499+
#[test]
500+
fn graded_shell_commands_gate_updates_by_tier() {
501+
let graded = |command: &str, severity: Severity, tier: &str| {
502+
Finding::new(
503+
"shell.exec",
504+
severity,
505+
Category::Shell,
506+
"Runs shell",
507+
command,
508+
)
509+
.keyed(format!("execute:{tier}"))
510+
};
511+
let old = report(
512+
vec![graded("uname -m", Severity::Low, "inspect")],
513+
Recommendation::Pass,
514+
);
515+
// Another read-only command: nothing to look at.
516+
let new = report(
517+
vec![
518+
graded("uname -m", Severity::Low, "inspect"),
519+
graded("cat /tmp/log", Severity::Low, "inspect"),
520+
],
521+
Recommendation::Pass,
522+
);
523+
assert_eq!(diff(&old, &new).recommendation, Recommendation::Pass);
524+
// A first command with side effects is new even though it is Medium.
525+
let new = report(
526+
vec![
527+
graded("uname -m", Severity::Low, "inspect"),
528+
graded("npm i -g x", Severity::Medium, "program"),
529+
],
530+
Recommendation::Pass,
531+
);
532+
assert_eq!(diff(&old, &new).recommendation, Recommendation::Review);
533+
// So is another one under the same key.
534+
let old = new;
535+
let mut new = report(old.findings.clone(), Recommendation::Pass);
536+
new.findings
537+
.push(graded("rm -rf /tmp/x", Severity::Medium, "program"));
538+
let diff = diff(&old, &new);
539+
assert_eq!(diff.recommendation, Recommendation::Review);
540+
assert_eq!(diff.new_arguments[0].added, vec!["rm -rf /tmp/x"]);
541+
}
542+
495543
#[test]
496544
fn new_high_capability_needs_review() {
497545
let old = report(vec![], Recommendation::Pass);

0 commit comments

Comments
 (0)