Skip to content

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.