CLI reference
Moved out of the README on 2026-09-12 so the front page stays scannable. Nothing here was cut; it is the same content with a home of its own.
Commands
| Command | Description |
|---|---|
agent-audit-kit scan . |
Full security scan |
agent-audit-kit scan . --ci |
CI mode: SARIF + --fail-on high |
agent-audit-kit discover |
Find the AI agent configs in your home directory |
agent-audit-kit discover . |
Same, plus the project's own per-platform configs (.mcp.json, .cursor/mcp.json, ...) |
agent-audit-kit pin . |
Pin tool definitions (SHA-256 hashes) |
agent-audit-kit verify . |
Check tools against pins (detect rug pulls) |
agent-audit-kit fix . --dry-run |
Auto-fix common misconfigurations |
agent-audit-kit suggest run.sarif --pr |
Markdown remediation body for gh pr create --body-file - |
agent-audit-kit suggest run.sarif --auto-pr |
Apply allow-listed mechanical fixes on a branch and open a draft PR |
agent-audit-kit score . |
Security grade (A-F) + SVG badge |
agent-audit-kit update |
Update the vulnerability database, rebuild the malicious-release feed from OSV (--github-malware adds GitHub's malware advisories; needs a token), and rebuild the advisory feed from OSV's PyPI, npm, Go and crates.io exports and NVD's CNA records (--nvd-days) |
agent-audit-kit proxy --port 8765 --target URL |
Start MCP interception proxy |
agent-audit-kit kill |
Terminate running proxy |
agent-audit-kit export-rules --out rules.json |
Write deterministic rule bundle + SHA-256 (Sigstore-signable) |
agent-audit-kit verify-bundle rules.json [--signature rules.json.sigstore.json] [--tag vX.Y.Z] |
Verify the bundle's digest, or its Sigstore signature and that release.yml signed it (needs [verify]) |
agent-audit-kit sbom . --format {cyclonedx,spdx} |
Emit CycloneDX 1.5 / SPDX 2.3 SBOM for MCP deps |
agent-audit-kit vex . |
Emit an OpenVEX 0.2.0 exploitability document, joined to the SBOM on purl |
agent-audit-kit report . --framework FRAMEWORK --format pdf |
Auditor-ready compliance report (EU AI Act / SOC 2 / ISO 27001 / HIPAA / NIST AI RMF) |
agent-audit-kit install-precommit |
Add the hook to .pre-commit-config.yaml |
Scan Flags
| Flag | Default | Description |
|---|---|---|
--format |
console |
Output: console, json, sarif |
--severity |
low |
Minimum severity to report |
--fail-on |
none |
Exit 1 at this severity: critical, high, medium, low, none |
--output / -o |
stdout | Write output to file |
--ci |
Shorthand: --format sarif --fail-on high -o agent-audit-results.sarif |
|
--config |
Path to .agent-audit-kit.yml |
|
--rules |
all | Comma-separated rule IDs to include |
--exclude-rules |
Comma-separated rule IDs to skip | |
--ignore-paths |
Comma-separated paths to exclude | |
--include-user-config |
Also read this user's state outside the project: ~/.claude.json, ~/.claude/settings.json, config.toml (AAK-TRUST-009), AGENTS.md and AGENTS.override.md (the AAK-AGENT rules) under $CODEX_HOME, by default ~/.codex, the npx and uv launcher caches (AAK-MALICIOUS-RELEASE-001, AAK-KNOWN-VULN-001), and the editor extension folders such as ~/.cursor/extensions (AAK-MALICIOUS-EXTENSION-001) |
|
--score |
Show security score and grade | |
--owasp-report |
Generate OWASP coverage matrix | |
--compliance FRAMEWORK |
Compliance report: eu-ai-act, soc2, iso27001, hipaa, nist-ai-rmf, mcp-2026-roadmap |
|
--verify-secrets |
Ask Anthropic, OpenAI, GitHub and GitLab whether leaked keys are live (opt-in, network; AWS and GCP keys are reported but not checked) | |
--diff BASE_REF |
Only report findings in files changed since BASE_REF | |
--llm-scan |
Ask a model whether each tool's metadata tries to manipulate the agent (opt-in; sends that text to the provider). See LLM scan | |
--llm MODEL |
ollama/gemma2:2b |
Model for --llm-scan: claude-* (ANTHROPIC_API_KEY), gpt-* (OPENAI_API_KEY), gemini-* (GEMINI_API_KEY) or ollama/<model> (local) |
--allow-scanner-failure |
Exit 0 even when a scanner crashed or --llm-scan left a tool unanalyzed |
|
--sessions PATH |
Run the session-scoped rules over agent transcripts — OpenAI Agents SDK traces, LangGraph checkpoints, JSONL. See Session transcripts | |
--strict-loading |
Fail loudly if any optional scanner module can't be imported (default: silently skip) | |
--verbose / -v |
Detailed scan progress |
Directories a scan skips
Most scanners do not read inside these directories below the scanned path: node_modules, .git, dist, build, __pycache__, .next, .nuxt, vendor, .venv, venv, env, .tox, .mypy_cache, .pytest_cache, .ruff_cache, target, out and .terraform. A few rules look inside some of them on purpose: the rules that read installed packages enter .venv/, venv/, env/, .tox/ and vendor/ to find site-packages, and AAK-MCP-INSPECTOR-CVE-2026-23744-001 reads the copies vendored in node_modules/ and vendor/.
A scan also skips .claude/worktrees/, where Claude Code keeps each worktree as a full checkout of the project, so a project with worktrees is not reported once per worktree. The rest of .claude/ is read, and so is a worktrees/ directory anywhere else.
Only directories below the scanned path count: a checkout that itself sits under build/ (Travis, Bitbucket Pipelines), or aak scan . run inside a Claude Code worktree, is read in full. Use --ignore-paths to leave out anything else.
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Scan passed — no findings exceed --fail-on threshold |
| 1 | Scan failed — findings meet or exceed --fail-on severity |
| 2 | Error — invalid path, malformed config, etc. |
AAK-AGENT-001, AAK-AGENT-003 and AAK-AGENT-006 read instruction files
(CLAUDE.md, AGENTS.md and the like). They report at their severities, but
they don't count toward --fail-on (or --ci, aak diff --fail-on-new and the
GitHub Action) until their precision is published in
benchmarks/false_positive/RESULTS.md.
The scan lists them under "Reported, not gating", so a passing build says why.
Configuration
Create .agent-audit-kit.yml in your project root:
severity: medium
fail-on: high
ignore-paths:
- vendor/
- third_party/
exclude-rules:
- AAK-SUPPLY-001 # We intentionally don't pin npx versions
- AAK-MCP-007 # (reports the same launches once AAK-SUPPLY-001 is excluded)
include-user-config: false
CLI flags always take precedence over config file values.
Security Scoring
agent-audit-kit score .
# Security Score: 85/100 Grade: B
| Grade | Score | Meaning |
|---|---|---|
| A | 90-100 | Excellent — minimal risk |
| B | 75-89 | Good — minor issues |
| C | 60-74 | Fair — needs attention |
| D | 40-59 | Poor — significant risk |
| F | 0-39 | Critical — immediate action required |
Generate an SVG badge for your README: agent-audit-kit score . --badge
SARIF Integration
This action emits SARIF (the sarif-file output); it does not upload to
Code Scanning itself. Add the canonical github/codeql-action/upload-sarif step
so findings appear in the Security tab and as inline PR annotations:
permissions:
security-events: write # required for the upload
contents: read
steps:
- uses: actions/checkout@v4
- uses: sattyamjjain/agent-audit-kit@v0.6.36
id: scan
with:
fail-on: high
- uses: github/codeql-action/upload-sarif@v3
if: always() # upload even when the scan step failed the build
with:
sarif_file: ${{ steps.scan.outputs.sarif-file }}
SARIF output conforms to SARIF 2.1.0
with fingerprints, partialFingerprints, security-severity scores, and
%SRCROOT% relative paths. Each finding carries OWASP references and CVE
links via the rule-level help; per-finding remediation is in result
properties. (No SARIF fixes[] — those require machine-applicable
artifactChanges, so emitting prose there would make Code Scanning reject the
upload.)
Each finding quotes what its rule matched as evidence, and every format repeats
it: the console, JSON, SARIF, the PR summary and aak notify. A credential in
that quote is masked before any formatter sees it, keeping the shape so the
finding still reads: ?token=***, https://***@host, --api-key ***,
GITHUB_TOKEN=***, Authorization: Bearer ***, sk-proj-***. Placeholders
such as ${GITHUB_TOKEN} are shown as written, because several rules exist to
tell a placeholder from a literal. Releases through 0.6.20 quoted credentials
as written, so SARIF uploaded by those versions can hold them.
Tool Pinning & Rug Pull Detection
MCP servers can silently change tool definitions after you approve them. AgentAuditKit detects this:
# Create initial pins (commit tool-pins.json to git)
agent-audit-kit pin .
# In CI, verify nothing changed
agent-audit-kit verify .
Detects: tool definitions changed (AAK-RUGPULL-001), new tools added (AAK-RUGPULL-002), tools removed (AAK-RUGPULL-003). verify exits 1 when it finds any of them and 0 when every tool matches its pin, so the CI line above fails the job on drift. watch --once exits the same way (through 0.6.22 it exited 0 after printing a drift); the long-running watch reports each drift and keeps watching.
A pin file that exists but cannot be read (not valid JSON, not UTF-8, not a map of pins) is never a pass: verify and watch --once exit 2, watch prints "not verified", and scan files AAK-INTERNAL-SCANNER-FAIL against the pin file and exits 1 as incomplete. Restore the file from git rather than re-pinning blind: pin accepts whatever the config declares now. verify and watch --once also exit 2 when the check itself fails, as on an MCP config they cannot decode.