Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 44 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,16 @@ plugin_scanner scan plugin.zip --json --fail-on review

# Compare the published version with an uploaded update
plugin_scanner diff published.zip update.zip --format json --fail-on review

# Update an installed binary in place to the latest release
plugin_scanner update
```

| Command / flag | What it does |
| --- | --- |
| `scan <zip>` | Full scan. Formats: `--format terminal` (default), `json`, `md` (reviewer report), `summary` (short user-facing disclosure). Shorthands: `--json`, `--markdown`, `--summary`. |
| `diff <old> <new>` | What changed between two versions: new or escalated findings, new hosts, modules, permissions, changed files. `--format terminal\|json\|md`. |
| `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. |
| `--fail-on <level>` | Exit 1 when reached. For `scan`: `info`…`critical` (highest severity) or `review` / `block` (recommendation). For `diff`: `review` / `block`. |
| `--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. |
| `--max-entry-bytes`, `--max-total-bytes`, `--max-entries` | Zip-bomb limits (defaults: 32 MiB per entry, 256 MiB total, 5000 entries). |
Expand All @@ -39,16 +43,17 @@ threshold reached, `2` unreadable archive or other error.

| Recommendation | Meaning | Typical cause |
| --- | --- | --- |
| `pass` | Nothing above Medium. Safe to publish without a human look. | Normal editor plugins: fs, fetch, commands, storage, settings. |
| `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. |
| `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`). |
| `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. |
| `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`. |

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

Severity guide:
Expand Down Expand Up @@ -76,6 +81,35 @@ plugin as critical (`e.read()`, `n.copy()`, `window.cordova`, webpack's
`fromCharCode`...) and Critical when it comes from a network response.
Bundler idioms (`Function("return this")`, `<script>` chunk loaders with
relative URLs) are ignored.
- **Shell commands are graded by what they run.** Each command is split like
a shell would (`;`, `&&`, `||`, pipes, subshells, `$(…)`), and each part is
graded:
- **Low**: only read-only commands (`uname -m`, `command -v x`, `cat`,
`ls`, `test -f`, `tool --version`, `npm root -g`).
- **Medium**: visible commands with side effects (installing packages,
moving files, starting a local server, running a proot container), and
any command with a value the scanner can't work out (`cat "${path}"`).
- **High**: the scanner can't see what runs: the command name is built at
runtime or is an unset `$VAR`, `sh -c` / `eval` / `node -e` get a runtime
string, or text is piped into a shell or interpreter.
- Known-bad patterns (download-and-run, reverse shells, wiping
storage...) are still matched on top of this. They only match the
dangerous form: `rm -rf ~/` is Critical, `rm -rf ~/.cache/x` is not;
reading `/etc/profile` is not persistence; Acode's own
`/data/data/com.foxdebug.acode…` folder is not another app's.
- **Shell helpers are followed.** In `const sh = c => Executor.execute(c)`,
each `sh("…")` call is graded with its own command. When every use of the
helper is a direct call, the helper's body adds no finding of its own. The
scanner also follows `this.run(cmd)` methods, getters such as
`getExecutor()`, quoting helpers (`'${s.replace(/'/g, …)}'`,
`JSON.stringify`), functions that build a script from a template, `$VAR`
names assigned earlier in the same script, and every branch of
`a ? "x" : "y"`.
- **Process input is not a command.** Text written with `Executor.write` to a
program the plugin started (a language server, a kernel driver) is input
(Low). It is graded as a command only when the started process is a shell
or can't be seen. Unknown text typed into a terminal tab is Medium (it is
usually log output); a runtime command followed by Enter is High.
- **Aggregation.** One finding per rule, stable key, and file, with an
occurrence count and up to 8 locations.
- **Endpoints are inventory.** URLs go into an `endpoints` list. Only known
Expand Down Expand Up @@ -128,7 +162,7 @@ plugin as critical (`e.read()`, `n.copy()`, `window.cordova`, webpack's
| --- | --- |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
| 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) |
Expand All @@ -147,7 +181,7 @@ Prefixes are omitted in the table; full IDs look like `shell.exec`.
{
"schema_version": 2,
"scanner_version": "0.3.0",
"rules_version": "2026.10.3", // rescan stored plugins when this changes
"rules_version": "2026.11.1", // rescan stored plugins when this changes
"plugin": { "id", "name", "version", "main", "entry", "permissions", "dependencies", ... },
"verdict": { "risk": "high", "recommendation": "review", "complete": true, "reasons": ["..."] },
"summary": { "total_findings", "by_severity", "by_category" },
Expand Down
35 changes: 24 additions & 11 deletions src/analysis.rs
Original file line number Diff line number Diff line change
Expand Up @@ -459,17 +459,30 @@ mod tests {
}

#[test]
fn terminal_plugin_needs_review_but_not_block() {
let report = scan(&[
MANIFEST,
ICON,
README,
(
"main.js",
b"Executor.execute('apk add python3'); acode.require('terminal');",
),
]);
assert_eq!(report.verdict.recommendation, Recommendation::Review);
fn terminal_plugin_is_graded_by_its_commands() {
let verdict = |source: &[u8]| {
scan(&[MANIFEST, ICON, README, ("main.js", source)])
.verdict
.recommendation
};
// Visible commands: disclosed, but no review needed.
assert_eq!(
verdict(b"Executor.execute('apk add python3'); acode.require('terminal');"),
Recommendation::Pass
);
assert_eq!(
verdict(b"(() => { const sh = c => Executor.execute(c); sh('uname -m'); sh('npm i -g x'); })()"),
Recommendation::Pass
);
// A command the scanner cannot see needs a person, but is not blocked.
assert_eq!(
verdict(b"Executor.execute(localStorage.getItem('cmd'))"),
Recommendation::Review
);
assert_eq!(
verdict(b"Executor.execute(`sh -c ${JSON.stringify(input.value)}`)"),
Recommendation::Review
);
}

#[test]
Expand Down
13 changes: 13 additions & 0 deletions src/cli.rs
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,19 @@ pub enum Command {
#[command(flatten)]
limits: LimitArgs,
},
/// Update this binary to the latest GitHub release, in place.
#[command(alias = "self-update")]
Update {
/// Only check whether a newer release exists.
#[arg(long)]
check: bool,
/// Install this release (e.g. 0.3.0 or v0.3.0) instead of the latest.
#[arg(long, value_name = "VERSION")]
version: Option<String>,
/// Reinstall even if this version is already installed.
#[arg(long)]
force: bool,
},
}

#[derive(Debug, Args)]
Expand Down
66 changes: 57 additions & 9 deletions src/diff.rs
Original file line number Diff line number Diff line change
Expand Up @@ -53,11 +53,11 @@ const ARGUMENT_RULES: &[&str] = &[
/// Every evidence string per stable key, across files.
fn arguments_by_key(report: &Report) -> BTreeMap<&str, BTreeSet<&str>> {
let mut map: BTreeMap<&str, BTreeSet<&str>> = BTreeMap::new();
for finding in report
.findings
.iter()
.filter(|finding| ARGUMENT_RULES.contains(&finding.id.as_str()))
{
// Low argument findings (read-only shell commands, process input) change
// nothing worth a look.
for finding in report.findings.iter().filter(|finding| {
ARGUMENT_RULES.contains(&finding.id.as_str()) && finding.severity >= Severity::Medium
}) {
let entry = map.entry(finding.key.as_str()).or_default();
entry.insert(finding.evidence.as_str());
entry.extend(finding.all_evidence.iter().map(String::as_str));
Expand Down Expand Up @@ -246,10 +246,14 @@ pub fn diff(old: &Report, new: &Report) -> DiffReport {
new_info.id.as_deref().unwrap_or("")
));
}
for finding in new_findings
.iter()
.filter(|finding| finding.severity >= Severity::High)
{
// A capability whose arguments matter (a shell command, a native action)
// is worth a look as soon as it is Medium: a terminal plugin that starts
// installing a new package is a new action even though it is not High.
for finding in new_findings.iter().filter(|finding| {
finding.severity >= Severity::High
|| (finding.severity >= Severity::Medium
&& ARGUMENT_RULES.contains(&finding.id.as_str()))
}) {
reasons.push(format!(
"New {}: {} [{}]",
finding.severity.label(),
Expand Down Expand Up @@ -492,6 +496,50 @@ mod tests {
assert_eq!(diff.recommendation, Recommendation::Pass);
}

#[test]
fn graded_shell_commands_gate_updates_by_tier() {
let graded = |command: &str, severity: Severity, tier: &str| {
Finding::new(
"shell.exec",
severity,
Category::Shell,
"Runs shell",
command,
)
.keyed(format!("execute:{tier}"))
};
let old = report(
vec![graded("uname -m", Severity::Low, "inspect")],
Recommendation::Pass,
);
// Another read-only command: nothing to look at.
let new = report(
vec![
graded("uname -m", Severity::Low, "inspect"),
graded("cat /tmp/log", Severity::Low, "inspect"),
],
Recommendation::Pass,
);
assert_eq!(diff(&old, &new).recommendation, Recommendation::Pass);
// A first command with side effects is new even though it is Medium.
let new = report(
vec![
graded("uname -m", Severity::Low, "inspect"),
graded("npm i -g x", Severity::Medium, "program"),
],
Recommendation::Pass,
);
assert_eq!(diff(&old, &new).recommendation, Recommendation::Review);
// So is another one under the same key.
let old = new;
let mut new = report(old.findings.clone(), Recommendation::Pass);
new.findings
.push(graded("rm -rf /tmp/x", Severity::Medium, "program"));
let diff = diff(&old, &new);
assert_eq!(diff.recommendation, Recommendation::Review);
assert_eq!(diff.new_arguments[0].added, vec!["rm -rf /tmp/x"]);
}

#[test]
fn new_high_capability_needs_review() {
let old = report(vec![], Recommendation::Pass);
Expand Down
Loading
Loading