airsec
State-of-the-art security review, driven by the coding CLI you already have.
Claude Code · Codex · OpenCode · Command Code
No new API key. No cloud upload. No third-party scanner. airsec drives the agent already installed on
your machine through a structured, multi-pass security audit, then turns the result into a report you
can act on.
Quick start
npx airsec@latest init
That is the whole thing. init walks you through it: pick the folder, pick your coding CLI, pick the
model, choose review-or-fix, and it runs.
Other ways to install
npm install -g airsec # global
pnpm add -g airsec
bun add -g airsec
yarn global add airsec
airsec init # then run it anywhere
No curl | sh installer, deliberately: a tool that audits your code for supply-chain risk should not
ask you to pipe a URL into a shell.
Getting ETARGET · No matching version found?
Your npm is pointed at a mirror that has not synced the release yet. Check with npm config get registry — if it is anything other than https://registry.npmjs.org, either wait for the mirror to
catch up or bypass it:
npx --registry=https://registry.npmjs.org airsec@latest init # one-off
npm config set registry https://registry.npmjs.org # permanently
Requirements
- Node ≥ 20 (the published bundle has zero runtime dependencies)
- At least one supported coding CLI on your
PATH — check with npx airsec harness
60 seconds, end to end
npx airsec harness # 1. what coding CLIs can airsec see?
npx airsec@latest init # 2. guided setup — writes .airsec/config.json, then runs
npx airsec report --format html > report.html # 3. share the result
npx airsec fix --severity high # 4. remediate the worst of it
Why this instead of a scanner
Pattern scanners find what patterns catch. An agent that reads your code can follow a tainted value
through three helpers and a middleware layer and tell you whether the sink is actually reachable.
airsec supplies the missing part: a rigorous process around that agent.
- Reconnaissance first. The attack surface is mapped — entrypoints, trust boundaries, sensitive
assets — before any vulnerability hunting starts, and that map is fed into every later pass.
- Fourteen focused audit modules instead of one "find bugs" prompt, so injection analysis is not
competing for attention with IaC review.
- Multiple search strategies per module. Forward taint analysis, reverse sink analysis,
goal-oriented attack, and invariant enforcement each find things the others miss.
- Adversarial verification. Every finding is handed to independent reviewers whose job is to
refute it. Findings that lose the vote are dropped, and you see how many were.
- Deterministic scoring and merge. Deduplication, severity weighting, and the aggregate risk
score are plain code, not another model call.
Supported coding CLIs
Run airsec harness to see which of these are installed and what models each offers.
| Harness |
id |
Install |
| Claude Code |
claude |
npm i -g @anthropic-ai/claude-code |
| Codex |
codex |
npm i -g @openai/codex |
| OpenCode |
opencode |
npm i -g opencode-ai |
| Command Code |
commandcode |
npm i -g command-code |
| Gemini CLI |
gemini |
npm i -g @google/gemini-cli — experimental adapter |
| Cursor Agent |
cursor |
curl https://cursor.com/install -fsS | bash — experimental adapter |
| Crush |
crush |
npm i -g @charmland/crush — experimental adapter |
The first four are built against headless flags verified against the real CLIs, and each is tested
end to end in both directions — audit (read-only) and fix (write). The ones marked experimental are
best-effort: they are overridable from config without touching the source.
Models are discovered, not hardcoded
Model ids change every few months. airsec never ships a versioned id that can rot into a wrong
default, so airsec harness --models <id> asks your machine instead:
| Harness |
Where the list comes from |
| OpenCode |
opencode models — the live list, hundreds of entries |
| Command Code |
cmd --list-models — the live list with descriptions |
| Claude Code |
your ~/.claude/settings.json model, plus the opus/sonnet/haiku aliases, which resolve to the current model by design |
| Codex |
the model in your ~/.codex/config.toml, including profiles |
A probe command is only ever one verified to list models. Guessing is unsafe: several of these CLIs
treat an unrecognised subcommand as a prompt, so a wrong guess would bill you for a model call
instead of printing a list. Where no list exists, the wizard offers "harness default" plus free-text
entry — always correct, never stale.
Usage
Guided
npx airsec init # asks: which folder, which CLI, which model, review or fix
npx airsec init ../api # start on a specific path
The wizard writes .airsec/config.json, so every later run is a bare airsec scan.
Non-interactive
airsec scan # uses .airsec/config.json, or sensible defaults
airsec scan ../api --depth paranoid
airsec scan --harness codex --model gpt-5.1-codex-max
airsec scan --modules injection,authn-authz,secrets --min-severity medium
airsec scan --quiet --reports sarif --fail-on high --require-complete # CI shape
Exit codes only matter when something automated is watching — a CI pipeline decides pass or fail
from this number. Running airsec yourself, you can ignore them; the wizard does not ask about them
for that reason.
| Exit |
Meaning |
0 |
No finding at or above --fail-on |
1 |
airsec itself failed — bad config, harness missing, unreadable target |
2 |
A finding at or above --fail-on (default high) survived verification |
3 |
An audit pass did not finish, and --require-complete was set |
--fail-on sets the bar: --fail-on critical fails a build only on critical findings,
--fail-on none never fails it. It changes nothing about the scan or the report.
Coverage can be partial, and that is not the same as clean. If a harness invocation times out or
errors, airsec records it, finishes the remaining passes, and reports the run — but the areas that
pass covered were never reviewed. Both the terminal output and report.md lead with a warning when
this happens, summary.incompletePasses carries it in JSON, and --require-complete turns it into
a build failure. Never read a partial run as a clean bill of health.
Parallel sessions of the same coding CLI contend for one rate limit, and a stalled session burns the
full --timeout (default 900s) before giving up. Concurrency 5 against Claude Code lost 5 of 14
passes to timeouts in testing; the default of 3 is deliberately conservative. If you see timeouts,
lower --concurrency before raising --timeout.
Fixing
airsec fix # pick findings from the last review interactively
airsec fix --all --severity high # remediate everything high and above
Fixes are applied to your working tree, one finding at a time — sequentially on purpose, because
parallel agents editing overlapping files produce conflicting writes. Review the diff before you
commit; airsec never commits for you.
Each fix is scoped to one finding, so a change that alters a function's contract can leave a caller
in another file out of step. The remediation prompt tells the agent to follow the change across file
boundaries, but weaker models do not always manage it — run your tests after fix, always.
Reports
Every run is stored under .airsec/runs/<timestamp>-<id>/ with the formats you configured.
airsec report # re-print the last review
airsec report --format html > out.html
airsec report --format sarif > out.sarif
SARIF uploads straight to GitHub code scanning.
Depth
| Depth |
Lenses per module |
Verifiers per finding |
File budget |
quick |
1 |
0 |
600 |
standard |
1 |
1 |
2,000 |
deep (default) |
2 |
2 |
6,000 |
paranoid |
3 |
3 |
20,000 |
Cost scales roughly with modules × lenses, plus one verification call per finding per verifier.
Start at quick on a new codebase to calibrate before committing to paranoid.
Audit modules
airsec modules prints these with their CWE and OWASP mappings.
Core (default): injection · authn-authz · secrets · crypto · input-validation ·
ssrf-network · xss-frontend · path-file · supply-chain · infra-config
Extended (opt in): api-surface · logic-race · llm-agentic · privacy-compliance
Configuration
.airsec/config.json:
{
"version": 1,
"target": "/abs/path/to/repo",
"harness": "claude",
"model": "opus",
"depth": "deep",
"modules": ["injection", "authn-authz", "secrets"],
"concurrency": 3,
"timeoutMs": 900000,
"retries": 1,
"verify": true,
"minSeverity": "low",
"exclude": ["fixtures/", "generated/"],
"reports": ["markdown", "json", "sarif"],
"failOn": "high",
"harnesses": {}
}
exclude entries are case-insensitive substring matches against each path relative to the target —
not globs. "generated/" drops the directory; ".test." drops test files anywhere.
Overriding a harness
When a CLI changes its headless flags, fix it in config rather than waiting for a release. Tokens
{{prompt}}, {{system}}, {{model}} and {{cwd}} are substituted per invocation; an argument
whose token has no value is dropped along with its flag.
{
"harnesses": {
"gemini": {
"bin": "gemini",
"promptVia": "stdin",
"args": {
"read": ["--model", "{{model}}", "--output-format", "text"],
"write": ["--model", "{{model}}", "--yolo"]
}
}
}
}
How a run works
inventory walk the tree, detect stack, rank security-relevant paths (deterministic)
↓
recon one pass: entrypoints, trust boundaries, sensitive assets (1 call)
↓
audit modules × lenses, run concurrently (m × l calls)
↓
merge fingerprint by location, corroborate by title overlap (deterministic)
↓
verify independent reviewers try to refute each finding (f × v calls)
↓
score severity × confidence × verdict × corroboration (deterministic)
↓
report terminal · markdown · json · sarif · html
Development
bun install
bun run dev -- scan ./fixture --depth quick # run from source
bun run check # lint + typecheck + test, what CI runs
bun run format # apply Biome fixes
bun run build # bundle to dist/cli.js, node-compatible
Bun is the toolchain; the published bundle targets Node ≥ 20 so npx airsec works anywhere. Biome
enforces formatting and lint, tsc --strict enforces types, and CI runs all three plus the packaged
binary on every push.
Extending it. A new harness is one file in src/harness/adapters/ plus a line in registry.ts —
or zero code, via a config override. A new audit module is one entry in
src/audit/catalog.ts. A new report format is one entry in src/report/index.ts.
src/
audit/ what to look for — module catalog, search lenses, prompts, output schema
core/ the pipeline — inventory, recon, fan-out, merge, verify, score, trust boundary
harness/ how to talk to each coding CLI — adapters, process exec, JSON extraction
report/ terminal · markdown · json · sarif · html
ui/ wizard prompts, progress, banner
util/ fs, json recovery, hashing, redaction, logging
Security model
airsec is pointed at code you may not trust, so it treats the target directory as hostile input.
Config from the target is not trusted to decide what runs. .airsec/config.json lives inside
the directory under review. Its harnesses block names an executable and its argv, so honouring it
from a repository you just cloned would be remote code execution. That block is ignored by default,
with a warning, and applied only when you pass --trust-config on the command line — somewhere the
repository cannot reach. Everything else in the file only decides what gets read, and is applied
normally.
Audit passes cannot execute commands or reach the network. The repository under review is
attacker-controlled input to a model, so injected instructions in a README or a code comment must
not be able to reach a shell (remote code execution) or the network (exfiltration of the source
being reviewed). Reconnaissance, auditing and verification run with only the tools an audit needs —
open a file, search, list.
For Claude Code that means Bash, WebFetch, WebSearch and Task are denied alongside the
editing tools; Task because a subagent could otherwise be spawned with the tools just removed.
Codex runs under --sandbox read-only, OpenCode under its plan agent, Command Code under
--permission-mode plan. Write access is granted only by airsec fix, and even then network tools
stay denied.
This is verified rather than assumed: a fixture repository carrying prompt-injection text in its
README and source is scanned as part of testing, and the injected command does not run.
Discovered credentials are masked in stored output. A secrets finding would otherwise copy a
live credential into report.md, report.json and report.sarif — files that get committed and
pasted into tickets. High-entropy tokens are masked to sk_l…redacted…4c across every text field of
a finding, not just the code snippet: models routinely spell the same credential out again in the
exploit narrative as a URL parameter. The credential stays identifiable, and the file, line, and
exploit path are untouched. Add .airsec/ to your .gitignore regardless.
These properties are covered by test/security.test.ts.
Caveats
- airsec runs your coding CLI, so it spends that CLI's quota and inherits its permissions. Audit
passes are launched read-only;
fix is the only mode that grants write access.
- Findings are produced by a language model. Verification removes a lot of noise, but treat the
output as a strong prioritised lead list, not a proof.
- A clean report is not a security guarantee. It is one pass by one reviewer.
- Findings are stored under
.airsec/runs/. Keep that directory out of version control.
License
MIT
Airsec 是一个 CLI 工具，驱动你已安装的编程智能体（Claude Code、Codex、OpenCode、Command Code）对代码进行结构化、多遍的安全审计，然后把发现整理成可付诸行动的报告。