Reference

CLI reference

Every Rutken command and its flags, grounded in the engine source. The CLI has two invocation shapes — a target-then-verb form for analysing a file, and a keyword form for everything else. Some commands and flags are compiled in only under specific build features (the capabilities your edition ships); those are tagged below. Any command also prints its own flags with --help.

Jump to section

Invocation model

The first argument decides which shape you're in. If it's a path to a target file, Rutken expects a verb next (target-form). If it's a recognised keyword, that keyword parses its own arguments (keyword-form).

rutken <target> <verb> [flags]     # target-form: analyse a file
rutken <keyword> [args]              # keyword-form: devices, update, packs, image ...

Target-form commands accept these global flags:

Flag	Meaning
`<target>`	Required first positional: an APK, ELF, PE, Mach-O, or iOS bundle. Native targets route the same verbs through the native analysis paths.
`-v`, `--verbose`	Repeatable: `-v` info, `-vv` debug, `-vvv` trace. Overridden by `RUST_LOG`.
`--color <auto\|always\|never>`	Terminal colour, default `auto`.

Keyword-form commands parse their own arguments and do not inherit those globals. Native-only flags (such as --lift) reject on an APK target by name, and APK-only flags (such as --pack or the interprocedural flags) reject on a native target — run rutken capabilities to see the capability-by-target-kind matrix.

Inspect a target

Read-only verbs that surface what's in the target. All target-form.

Command	What it does & flags
`info`	Analysis summary / metadata. No flags.
`manifest`	Dump the Android manifest. No flags.
`stats`	Coarse analysis summary. No flags.
`classes`	List classes. No flags.
`strings`	Dump string constants. `--grep <text>` to filter.
`search <query>`	Search the target; `query` is a required positional.
`disasm <query>`	Disassemble matching methods; `query` required.
`dump`	Low-level structure dump. `--json`, `--raw`, `--include strings`.
`callgraph <root>`	Reachable call graph from `root`. `--dot` (Graphviz output), `--virtual-dispatch` (resolve virtual/interface calls via class hierarchy).
`concepts`	Navigate by security concept. `--list`, positional `concept` (required unless `--list`), `--scope <app\|…>` (default `app`), `--min-tier <weak\|…>`, `--limit <n>`, `--callers`, `--format`.
`investigate`	Connected mechanical-investigation pipeline. `--rule` / `--exclude-rule` (repeatable), `--ablate-fact-class`, `--seed-mode <authored\|general>`, `--format`. No `--fail-on` by design.
`verify-signature`	Verify the APK signature. `--expect-signer <SHA256>` (repeatable), `--format`.

Analyse a target

rules partial gating

The primary SAST verb. Runs the rule set over the target and reports findings. Key flags:

Flag	Meaning
`--list-rules`	List rules instead of scanning.
`--platform <android\|linux\|windows\|ios\|all>`	Filter the rule list (requires `--list-rules`), default `all`.
`--rule <id>` / `--exclude-rule <id>`	Run only / skip specific rules (repeatable, mutually exclusive).
`--min-severity <info\|low\|medium\|high\|critical>`	Floor for reported findings, default `low`.
`--interprocedural`, `--interprocedural-params`	Enable return-value / parameter-value interprocedural data-flow.
`--summary-max-methods <n>`, `--summary-max-rounds <n>`	Bound the interprocedural summary build (require an interprocedural flag).
`--format <…>`	`text` (default), `json`, `sarif`, `markdown`, `gitlab-codequality`, `junit`, `ndjson`; `html`/`pdf` on rich-report builds.
`--out <path>`, `--artifact-uri <path>`	Write the report to a file; set the SARIF artifact URI.
`--fail-on <severity>` ci-gate	Exit non-zero if a finding at or above this severity is present.
`--verify-signature`, `--expect-signer <SHA256>`	Also verify the APK signature as part of the scan.
`--chains`	Surface finding chains.
`--baseline <path>`, `--baseline-out`, `--baseline-delta-out`	Compare against a baseline and emit only new/changed findings.
`--pack <path>`, `--no-installed-packs`	Load an external rule pack (repeatable, APK only); skip installed packs.
`--lift`, `--lift-max-functions`, `--lift-timeout`	Machine-code lifting for ELF/PE targets.

rutken app.apk rules --min-severity medium --format sarif --out out.sarif
rutken app.apk rules --fail-on high            # CI gate: nonzero exit on High+
rutken app.apk rules --list-rules --platform android

compliance compliance-report

MASVS / CERT-IN compliance rollup. Shares the rule-selection and interprocedural flags with rules, plus --framework <masvs|certin> (default masvs; ssdf on native targets), --sca, --cache-dir, --max-age-days, --out, --format, and --fail-on (ci-gate).

sca

Software composition analysis against a cached component/CVE dataset.

Flag	Meaning
`--cache-dir <path>`	Dataset cache location.
`--db <path>` / `--url <url>` sca-fetch	Use a local dataset / fetch one (mutually exclusive).
`--auto-update`, `--max-age-days <n>`, `--timeout <s>`	Refresh the dataset if stale.
`--format`, `--out`, `--artifact-uri`	Report output.
`--sbom <path>`, `--snapshot-out <path>`	Emit an SBOM / a snapshot for later re-matching with `monitor`.
`--fail-on <severity>` ci-gate	CI gate on component severity.

fix

List suggested fixes (read-only by default) and optionally apply them. --format; --apply (requires --out); --out <path>; --overwrite; --include-behaviour-changing; plus the shared signing arguments.

Modify & re-sign

These verbs rebuild or re-sign a target. Most require the local-apply build feature. All that output an APK take the shared signing arguments.

patch local-apply

Apply a single manifest/native remediation and rebuild the APK. --disable-debuggable, --disable-allow-backup, --disable-cleartext-traffic, --disable-exported <component>, --disable-grant-uri <provider>; -o/--output (required); shared signing args; plus the native-patch arguments for ELF/PE targets.

sign local-apply

Re-sign an APK. -o/--output (required) and the shared signing args.

embed-gadget

Stage a Frida gadget into an APK. --gadget <ABI=path> (repeatable), --abi <abi>, --config <path>, --library-name, --target-class, -o/--output (required), shared signing args.

edit-code local-apply

Width-preserving instruction edit. --class, --method (required), --method-index, --dex, --offset (required), --count (default 1), --replace <text> (required), --dry-run, -o/--output (required unless dry-run), shared signing args.

remediate local-apply

Produce a source-fix PR plan. --format; --publish publish (requires --repo and --ack); --repo; --ack; --only-safe. See Remediation & reporting.

Device & dynamic

run

Install, launch, and observe the target on a device or emulator. Core flags: --device <serial>, --duration <s>, --session-out <path>, --no-install, -g/--grant-permissions, --uninstall-after, --verify, --correlate, --component <pkg/.Class>, --format, plus the rule-selection / interprocedural flags.

Instrumentation engine: --frida or --frida-attach drive the bundled Frida gadget (Community). On bespoke-agent builds, --bespoke runs Rutken's own in-house agent instead, with a large family of --bespoke-* flags: hook selection (--bespoke-hooks, --bespoke-pack, --bespoke-derived), derived bypass toggles (--bespoke-force-void-trust, --bespoke-force-true-hostname, --bespoke-force-void-cert-pinner, --bespoke-return-capture), raw bytes (--bespoke-raw-bytes), and the authorization phrases (--i-am-authorized-bespoke, --i-am-authorized-bespoke-active, --bespoke-authorize <SHA256>). ELF/PE targets take the shared native-run arguments.

verify

Offline runtime verification over a recorded session. --session <path> (required), --rule/--exclude-rule, --format, and the interprocedural flags.

correlate

Join static findings with dynamic evidence offline. --session <path> (repeatable) and/or --capture <bundle> (repeatable, at least one required), --correlation-out, --format, --fail-on and --fail-on-status <any|corroborated> ci-gate, plus the interprocedural flags.

capture intercept

Device traffic capture (target-form). --device (required); either --repack-trust or --embed-trust bespoke-agent; --owned-allowlist <path> (required); --i-am-authorized-repack; signing args. Under --embed-trust: --library-name, --agent-so, --split (repeatable), --embed-derived and the --embed-force-* toggles, --i-am-authorized-bespoke[-active]. Output: --duration/--forever, --ca-out, --format. See Dynamic & network capture.

unpin unpinned-capture

Composed unpinned interception to an .rcap bundle. --authorize (required), --i-am-authorized, --i-am-authorized-subvert, --serial, one of --spawn / --attach / --gadget, --gadget-port, --duration, --record <path> (required), --ca-store <user|system|none>, --port, --bodies, --json. On bespoke-agent builds: --bespoke, --bespoke-agent-so, --bespoke-root-inject.

intervene offense

Active-instrumentation bypass pack. --pack <root-detection|ssl-pinning>, --authorize (required), --i-am-authorized-subvert, --serial, one of --spawn/--attach, --duration, --json, --dry-run.

Authorization is enforced, not advisory. The behaviour-changing dynamic commands require verbatim authorization phrases and fail closed without them. Only run them against a device or app you own or are explicitly authorized to test.

Keyword commands

Commands that don't take a target file. Keyword-form.

Command	What it does & flags
`devices`	List attached devices. `--adb <path>`, `--format <text\|json>`.
`pull`	Pull an installed APK off a device. `--serial`, `--package`, `--out-dir`, `--include-system`, `--list`, `--overwrite`, `--non-interactive`, `--adb`, `--format`.
`emulator <list\|boot>`	`boot` takes `--avd` (required), `--snapshot`, `--port`, `--window`, `--no-snapshot`, `--read-only`, `--wipe-data`, `--boot-timeout`, `--duration`.
`batch`	Aggregated multi-target scan. `--apk`/`--target` (repeatable), `--apk-dir`/`--target-dir`, `--image`, `--pipeline-dir`, `--max-depth`, `--max-files`, rule + interprocedural flags, `--format` (incl. `ndjson`), `--out-dir`, `--fail-on`, `--metrics-out`, its own `-v`.
`capture <teardown\|info\|export\|record>` intercept	`teardown` (`--recover`, `--list`, `--force`); `info <bundle>`; `export <bundle> --format <har\|pcapng>`; `record <apk> --out` (headless record).
`sca update`	Refresh the SCA dataset. `--db` / `--url` sca-fetch, `--cache-dir`, `--force`, `--timeout`.
`monitor`	Re-match a saved SCA snapshot against a fresh dataset. `--snapshot` (required), one of `--dataset`/`--cache`/`--url`, `--snapshot-out`, `--fail-on`.
`capabilities`	Print the capability-by-target-kind matrix. `--format <text\|json\|markdown>`.
`update`	Update Rutken via the launcher. No flags.
`assess <keygen\|authorize\|verify>`	Authorization-token tooling: generate a signing key, mint a capability token (`--capability`, `--principal`, `--target`/`--target-hash`, validity window), and verify one.
`pr comment` / `issue comment`	Post a scan delta to a GitHub PR / issue. `--delta` (required), `--repo`, `--pr`/`--issue`, `--token-env` (default `GITHUB_TOKEN`), `--dry-run`.
`host-offense <plan\|execute\|recover\|chain\|posture>` offense-host	Authorized host-offense operations with a required time-boxed authorization token and acknowledgement phrase.
`vcs github <install\|status>` publish	Configure the GitHub App integration.

Images & CI/CD

image <scan|serve|mcp|remediate>

Container-image analysis. image scan <path>: --dockerfile, --format, --framework <none|cis-docker>, --out, --artifact-uri, --fail-on, dataset flags (--cache-dir, --db/--url sca-fetch, --auto-update), content toggles (--no-packages, --no-secrets, --no-binaries), --only/--skip, --list-rules, --fix, and image-signature verification flags. serve/mcp require the REST-API feature; remediate requires local-apply. See Platforms & operations.

cicd <scan|serve|mcp|remediate> cicd-scan

CI/CD pipeline analysis. cicd scan <path>: --format, --out, --artifact-uri, --fail-on, --only/--skip, --list-rules, --framework <none|slsa>, --fix.

Plugin packs

Manage detection rule packs. See Writing a Rutken plugin for the pack format.

Command	What it does & flags
`packs validate <path>`	Validate a pack manifest (parse + semantic checks + build).
`packs update`	Refresh the signed registry index. `--url` plugin-registry or `--dir`, `--cache-dir`, `--timeout`.
`packs list`	List available packs. `--cache-dir`.
`packs install <publisher/id>`	Install a signed pack (hash + signature re-verified). `--url`/`--dir`, `--cache-dir`, `--timeout`.
`packs sign` / `keygen` / `publish`	Maintainer-only. Signing is done in CI with a vault-held key; contributors never hold one.

To use a pack locally while authoring, you don't need the registry at all — load it into a scan with rutken app.apk rules --pack ./mypack.json.

Shared argument groups

Signing arguments

Flattened into fix, patch, sign, embed-gadget, edit-code, and target-form capture:

Flag	Meaning
`--keystore <path>`	PKCS#12 keystore.
`--keystore-pass-env <var>`	Env var holding the keystore password, default `RUTKEN_KEYSTORE_PASS`.
`--keystore-pass-file <path>`	File holding the password (takes precedence).
`--key-alias <alias>`	Key alias within the keystore.
`--signing-scheme <auto\|v1\|v2\|v1+v2>`	APK signing scheme, default `auto`.

There is no plain --keystore-password flag; pass the password via env or file.

Native-run arguments

Flattened into run for ELF/PE targets: --attach-pid, --arg (repeatable), --authorize <SHA256>, --authorize-process, --i-am-authorized, --hooks (default all), --capture, --capture-out, --no-proxy.

Native-patch arguments

Flattened into patch for ELF/PE. ELF: --clear-exec-stack, --set-bind-now, --neutralize-rpath, --neutralize-runpath. PE: --set-dynamic-base, --set-nx-compat, --set-high-entropy-va, --set-no-seh, --accept-signature-invalidation. Both gated by --authorize <SHA256> and --i-am-authorized-modify.

Formats & exit codes

Report formats vary by command. The static-analysis verbs (rules, correlate, batch) offer the widest set: text (default), json, sarif, markdown, gitlab-codequality, junit, ndjson, and — on rich-report builds — html and pdf. Device and meta commands generally offer text / json.

Exit codes:

Code	Meaning
`0`	Success (and, for a gated run, the gate passed).
`2`	A CI gate fired (`--fail-on` / `--fail-on-status`), or an entitlement check for a paid capability was denied.
other non-zero	Usage or runtime error.

Feature & tier gating

There are two independent layers of gating.

Compile-time build features

Whole commands and individual flags are compiled in only under their build feature — what your edition ships determines what's present. Notable ones: ci-gate (--fail-on), local-apply (patch, sign, edit-code, remediate, fix --apply), rest-api (serve and the image/cicd serve/mcp paths), intercept (capture), unpinned-capture (unpin), bespoke-agent (the --bespoke-* / --embed-* flags), offense (intervene), offense-host (host-offense), cicd-scan (cicd), compliance-report (compliance), sca-fetch (dataset --url), plugin-registry (pack --url), and report-rich (html/pdf). A few keyword commands (host-offense, vcs, cicd) are entirely invisible in a default build.

Runtime entitlement

Paid capabilities additionally check your entitlement at runtime. Resolution is offline-first (it reads an installed token and falls back to Community); on a miss it asks the launcher to refresh once, then re-checks. A denial exits with code 2, the same as a CI gate. Free Community verbs never run this check. The three editions are Community, Pro, and Enterprise.