-
-
Notifications
You must be signed in to change notification settings - Fork 2
Glossary and FAQ
Archetype — the kind of software a target is (web/API, CMS, plugin, library/SDK, CLI, agent/LLM, mobile, data/ML, firmware, …). Recon classifies it first, and everything downstream (entry-point reconstruction, sink mapping, the prompt split, the injected vuln-class index) inherits from it.
Focus — one of the complementary custom audit prompts recon generates (typically ~3, always including one architecture-led whole-system prompt). Each focus is a bounded surface a separate audit session reasons about.
Ground truth — the structured pack recon extracts by reading the code (ground_truth.json):
invariants, baseline-correct references, variant families, and carve-outs. Baking it into the prompts
turns the audit from open-ended hunting into closed-ended verification.
Invariant — a location → expected → how-to-check triple (e.g. "this API-key compare MUST be
constant-time"). The audit checks it as PASS/FAIL rather than hunting freely.
Baseline-correct reference — the one place a systemic pattern is implemented correctly; every sibling is diffed against it. The most precise way to find variant bugs.
Variant family — a repeated code shape (controller-per-operation, converter-per-type, every
free() site, every panic point…) with a concrete enumerated member list, so the audit verifies
each member, not just the first.
False-positive carve-out — a target-specific "do not flag" rule with justification, extracted by recon and also handed to the validator so it doesn't re-derive it and wrongly refute a real finding.
VARIANT_HUNT_LOG — a mandatory audit deliverable: one row per variant-family member with a
🟢/🟡/🔴 verdict. A coverage forcing-function.
Completeness-critic — a re-audit pass (--critic-passes, default 1) that re-checks each focus
for what was missed, looping until a pass adds nothing new.
dedup_key — sha1(normalize(primary_file + primary_line + cwe)). Findings sharing a key
collapse to one; see Architecture.
Downgrade-don't-delete — the validation philosophy: refuted is reserved for findings provably
contradicted by code (or matching a carve-out); anything merely uncertain is kept as
needs_runtime_verification. See the finding lifecycle.
needs_runtime_verification — a first-class verdict for a finding the model couldn't confirm or
rule out statically, kept with a concrete follow-up question rather than dropped.
design_accepted / fixed_upstream — corroboration
outcomes: a finding the docs describe as intended (kept, flagged) / one already patched in a newer
commit (moved to a report appendix, never silently deleted).
SCA — software-composition analysis: the opt-out stage that reads dependency manifests and flags
pinned versions with known advisories as a dependencies focus (CWE-1104).
Runner / backend — the swappable engine behind the AgentRunner interface: headless (Claude
Code), codex (Codex CLI / OpenAI / local-OSS), or mock (free fixtures). See
Multi-Backend.
Session policy — the per-stage capability contract (no network except the two OSINT stages; repo never writable) each backend enforces in its own dialect. See the capability map.
Accepted risks (--accepted-risks) — a file listing the vendor's intended/accepted-by-design
behaviors, injected downstream so they're not re-reported as bugs. See
Design-Aware Impact Discipline.
Impact discipline — the anti-over-claim rule: report proven impact, not reflexive escalation (no asserting IMDS/cloud-metadata reachability for an SSRF without evidence).
Severity symmetry — a finding that defeats a security mechanism the project itself ships (auth, MAC, crypto, RNG, replay, access control) is rated by the property it breaks, not downgraded to "informational hardening".
Ledger — the SQLite store (llm_calls + findings_ledger) powering cost control, the hard
--budget guard, cross-run resubmission detection, and the real-world triager accept-rate.
Run / run_id — one invocation of the pipeline; all artifacts live under runs/<run_id>/.
scope.json — the schema-validated scope (assets, out-of-scope, prohibited techniques, reference
links) that is authoritative input to every stage and the final findings filter.
Submission draft — the per-finding DRAFT - NOT SUBMITTED bundle Stage 5 produces; submission is
always a manual human action (there is no submit command).
Calibration — --calibration forces the audit stage onto Opus (effectively all-Opus). Use it
for the first few programs against a target class and for high-value targets.
Does Argo submit findings anywhere?
No. The pipeline stops at drafts; there is no submission code path and no submit command. See
Guardrails & Safety.
Will it touch the program's live hosts? Not by default — every default-pipeline stage is offline against the program's hosts. The only exception is the opt-in, authorized-only live stage, which is scope-locked, read-only-by-default, capped, and audit-logged.
Does it modify my repository?
No. The repo is mounted read-only to every session; mutation tools are always disallowed; there is
no code path that writes into repo/. Even remediation works on an
isolated copy and only emits proposed diffs.
Does it send my code to a third party?
Depends on the backend. A cloud backend (Claude / Codex-OpenAI) sends the source to that
provider's API to analyze it. A local / OSS model (--codex-oss) keeps everything on-device. The
repo is never pushed to a git remote either way. See Multi-Backend.
Why did it find nothing, or miss a bug I know is there?
Recall is bounded by the audit model — validation can only remove false positives, never recover
a bug the audit never surfaced. Run with --calibration (audit on Opus), then use the
interrogation chat to ask "why didn't you find X?" — a specific,
localized hypothesis gets independently re-validated.
How do I keep costs down while trying it?
Three free/cheap modes: --runner mock (zero tokens, full glue), --dry-run (real ingest+recon,
then stop — inspect the prompts before paying), and --smoke (~$1 real end-to-end). Add --budget
for a hard per-run ceiling. See Getting Started.
A run hit a session/rate limit partway through — is the work lost?
No. Chain accounts/backends with --claude-accounts a,b --fallback codex so a 429 transparently
self-heals onto the next. A validate/corroborate session that couldn't run leaves its findings
survivors (never dropped); just re-run argo validate <run_id> / argo corroborate <run_id> once
the limit resets. See Multi-Backend.
Runtime verification did nothing — why?
It's opt-in (--runtime) and best-effort: it needs Docker plus a launcher recipe (explicit image,
an argo-runtime.json, or the repo's own Dockerfile). With none of those it gracefully skips and
findings keep their static verdict. See Runtime Verification.
Codex runs show $0 cost — is that real?
Codex reports tokens, not dollars, so Argo estimates USD from a price table (unknown/OSS/local models
estimate to $0; tokens are still logged). The mid-session hard budget kill is therefore unavailable
on Codex — only the between-stages budget abort applies. See Multi-Backend.
Can I run fully offline?
Yes: --no-research (skip the web OSINT) + a local/OSS model + a brief-less local audit keeps a run
100% offline and on-device. --smoke and brief-less reviews force research/corroborate off anyway.
Is this a taint-flow / CodeQL-style tool? No — deliberately. Argo has no taint engine, CPG, or AST/data-flow graph; the LLM reads source semantically instead. This is a core design choice (and the thing that keeps the study's variable isolated) — see Design Decisions.
- Getting Started — install and first run.
- Guardrails & Safety — the constraints behind several answers above.
- Vulnerability Class Index — the archetype-keyed reference.