Agent Audit
Static security linting that finds prompt injection, MCP misconfiguration, and taint bugs in AI agent code before production.
- Source repo
- HeadyZhang/agent-audit
- Stars
- ★ 244
- Last updated
- 1mo ago
- License
- MIT
- Primary language
- Python
- FA score
- 50/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platform
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- An agent developer using LangChain, CrewAI, AutoGen or AgentScope self-checks for prompt injection and command injection before merging.
- Not a fit if
- Teams needing cross-function or cross-module taint tracking
- Teams working mainly in non-Python codebases
- Teams wanting runtime detection instead of static scanning
- Source review
- 50/100 · Major gaps
What does this agent do, and when should you use it?
Agent Audit is a static security scanner for LLM agent applications, installed from PyPI and run as the agent-audit CLI. Its analysis core combines several passes: PythonScanner for AST and dangerous-pattern detection, TaintTracker for tool-boundary data flow from @tool parameters to sinks such as eval, subprocess.run and cursor.execute, SecretScanner with a three-stage SemanticAnalyzer for credential detection, MCPConfigScanner for server provenance, path permissions and authentication, and PrivilegeScanner for daemons, sudoers and sandbox settings. A RuleEngine maps findings across 66 rules to the OWASP Agentic Top 10 and emits terminal, JSON, Markdown or SARIF reports, with --fail-on turning findings into a CI gate. The scanner never executes the code under review, and its documented limits are intra-procedural taint tracking and Python-first coverage. It is meant for agent developers and security engineers who want a structured, repeatable check before every merge.
Running agent-audit scan <path> reads the target tree's .py, .json, .yaml and .env files. PythonScanner parses Python ASTs for dangerous patterns and @tool metadata; TaintTracker follows whether tool-entry parameters reach eval, subprocess.run or cursor.execute without sanitization; DangerousOperationAnalyzer locates tool boundaries. SecretScanner collects regex candidates, then SemanticAnalyzer filters them through known-format matching, entropy and placeholder/UUID exclusion, and context adjustment by file type and test patterns. MCPConfigScanner parses claude_desktop_config.json and MCP gateway configs for unverified server sources, overly broad filesystem permissions, missing auth, unpinned versions, tool-description poisoning, cross-server tool shadowing and baseline drift. PrivilegeScanner checks daemon, sudoers, sandbox and credential-store exposure. The RuleEngine produces severity-tiered findings (BLOCK/WARN/INFO) rendered to terminal, JSON, Markdown or SARIF. agent-audit inspect stdio performs a read-only probe of a live MCP server, --save-baseline/--baseline reports only new findings, --severity sets reporting thresholds and --fail-on sets the exit-code threshold.
- An agent developer using LangChain, CrewAI, AutoGen or AgentScope self-checks for prompt injection and command injection before merging.
- A security engineer reviews a third-party agent codebase and uploads SARIF output to the GitHub Security tab for tracking.
- A team maintaining an MCP server or claude_desktop_config.json checks for leaked keys, missing auth and over-broad filesystem grants.
- A platform team adds --fail-on high to CI and uses a baseline file so only newly introduced findings break the build.
- An OpenClaw user installs the agent-audit-scanner skill and asks their agent to audit installed skills and config.
- A trainer validating vulnerable-agent exercises checks whether deliberately bad code is caught by the static rules.
How do you install or deploy this agent?
A working Python environment with pip is required; install from PyPI:
pip install agent-auditFor the OpenClaw skill variant, Node.js and npx are needed:
npx clawhub@latest install agent-audit-scannerFor source development the README uses Poetry:
git clone https://github.com/HeadyZhang/agent-audit
cd agent-audit/packages/audit
poetry installHow do you use this agent?
Scan a project directory:
agent-audit scan ./your-agent-projectReport high and above, and fail CI at that level:
agent-audit scan . --severity high
agent-audit scan . --fail-on highEmit JSON or SARIF:
agent-audit scan ./my-agent --format json
agent-audit scan . --format sarif --output results.sarifTrack only new findings with a baseline:
agent-audit scan . --save-baseline baseline.json
agent-audit scan . --baseline baseline.json --fail-on-newProbe a live MCP server read-only (tools are never called):
agent-audit inspect stdio -- npx -y @modelcontextprotocol/server-filesystem /tmpRun it from GitHub Actions:
name: Agent Security Scan
on: [push, pull_request]
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: HeadyZhang/agent-audit@v1
with:
path: '.'
fail-on: 'high'
upload-sarif: 'true'Configure project-level behavior in .agent-audit.yaml:
# .agent-audit.yaml
scan:
exclude: ["tests/**", "venv/**"]
min_severity: low
fail_on: high
ignore:
- rule_id: AGENT-003
paths: ["auth/**"]
reason: "Auth module legitimately communicates externally"
allowed_hosts:
- "api.openai.com"What are this agent's strengths and limitations?
- Tool-boundary-aware taint analysis fires only when a confirmed @tool entry parameter reaches a dangerous sink, with dedicated framework rules for LangChain, CrewAI, AutoGen and AgentScope.
- MCP config auditing covers tool-description poisoning, cross-server tool shadowing and baseline drift (rug pull) — categories the README reports Bandit and Semgrep cannot parse at all.
- 66 rules span all 10 OWASP Agentic Top 10 categories, with SARIF/JSON/Markdown output and a --fail-on CI gate for GitHub Actions.
- Publishes a reproducible raw benchmark on an 81-sample, 238-label ground truth (precision 68.86%, recall 84.32%, F1 0.7581) and a retraction note explaining the metric shift.
- Taint tracking is intra-procedural only; no cross-function or cross-module flow, so chained calls can be missed.
- Python and MCP JSON configs are the primary targets; other languages get only limited pattern matching.
- Purely static: code is never executed, so runtime-only logic vulnerabilities stay out of scope.
- Raw precision of 68.86% means real triage work; CI adoption realistically needs ignore rules and baseline files to stay usable.
How does this agent compare with similar options?
The README benchmarks against Bandit 1.8 and Semgrep 1.x on an equivalent injection/RCE/credential subset: agent-audit reaches 84.32% recall versus 29.7% for Bandit and 27.0% for Semgrep, and both alternatives score 0% recall on MCP configuration issues. It positions itself as complementary — general Python security checks remain better served by Bandit or Semgrep.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Agent Audit This agent | 50 · Major gaps | CLIFree | ★ 244 | 1mo ago | Python | — |
| Repo Forensics | 44 · Major gaps | CLIPaid | ★ 204 | 13d ago | Python | Codex · Claude Code |
| Semia — Security Audit for AI Agent Skills | 59 · Major gaps | CLIFree + model costs | ★ 615 | 5mo ago | Python | Codex · Claude Code · OpenAI API · Claude API |
| SkillSpector Security Scanner | 62 · Some gaps | CLIFree + model costs | ★ 25k | today | Python | Codex · Claude Code · OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
SECURITY.md explicitly states pure static analysis, no execution of scanned code, no telemetry, no network requests, and no privileged execution requiring only read access, which supports least_privilege and external_effects at 2. However, the inspect subcommand launches MCP server processes (e.g. npx -y ...), an external side effect documented only as 'read-only, never calls tools' with no discussion of the risk of spawning third-party processes, so external_effects is not full marks. user_confirmation: CLI offers --fail-on/--baseline gating but no interactive confirmation, and inspect spawns external processes without a prompt, so 1. sensitive_data_handling: semantic secret detection and masked output (sk-a***) exist, but findings may embed secret fragments and no explicit output-redaction guarantee is shown, so 2. dependency_security: only a verbal 'minimal dependencies' claim, no lockfile or dependency-audit evidence, and CI installs bandit/semgrep best-effort, so 1. rollback: only a baseline mechanism for incremental comparison; no rollback story for scanned targets or config changes, so 1. source_attribution: OWASP/CWE references and a citation exist, but publisher identity is unverified and reports mix the names Argus and agent-audit, muddying attribution, so 1.
self_consistency is contradicted by the evidence: README says 66 rules, the description says 51, the spec is v0.14.1, SECURITY.md supports only 0.15.x while README is at v0.20.0; test counts appear as both 1924 and 1873; the checked-in result file is layer1_v0.19.0.json yet paired with v0.20.0 numbers, so 1. dependency_availability: PyPI badge and poetry install instructions exist, but no lockfile evidence and CI relies on third-party actions and optional tools, so 1. failure_messages: CI comments document an exit-code contract (0/1/2), empty-SARIF detection, and an import-path regression guard, showing attention to diagnosable failure, so 2.
audience_and_scenarios: clearly targets agent developers, security engineers, and MCP teams with CI integration scenarios, so 2. capability_boundaries: 'Current Scope' and spec section 6 clearly list static-only analysis, intra-procedural taint, and Python focus, so 2. trigger_precision: relies on heuristics and confidence tiers, but the OpenClaw report self-reports 615 of 680 (90.4%) likely false positives and README admits FP 90 with unlabeled cases, so 1. environment_fit: Python 3.9-3.12 matrix, offline operation, and SARIF/JSON/markdown outputs fit common CI environments, so 2.
information_architecture: layered docs (README, spec, rules, architecture, CI integration, benchmarks) are well structured, so 2. install_notes: pip install, poetry dev setup, and a GitHub Action input table are provided, so 2. naming_stability: dual naming (Argus vs agent-audit), rule renames (AGENT-040 to 050), and cross-document version drift, so 1. examples_and_faq: quick start, sample report, collapsible Action example, and an intentionally vulnerable sample file, so 2. known_limitations: dedicated sections in both README and spec, so 2. license: full MIT text, so 3. versioning_changelog: no CHANGELOG file, only scattered in-document version notes, so 1. maintenance_responsibility: SECURITY.md response timelines and a CONTRIBUTING reference exist, but the publisher is unverified and there is no maintainer roster or release process, so 1.
output_usability: terminal report, JSON, SARIF, markdown, baseline, and exit-code gating make output directly CI-usable, so 2. marginal_value: MCP config auditing and tool-boundary taint target categories general SAST misses, a genuine differentiator, so 2. cost_benefit: lightweight install, but the high false-positive rate (90.4% likely FP on OpenClaw) implies heavy manual triage, and benchmark figures include a self-admitted non-reproducible adjusted value, so 1.
claim_traceability: some claims point to scripts and result files (precision_recall.py, results/layer1_v0.19.0.json), but version mismatch breaks the chain and 'first and only' style assertions lack independent support, so 1. cross_source_corroboration: numbers conflict across documents (rule counts 51/63/66, test counts, versions), so 1. fact_inference_separation: reports interleave inference about the Claude Code leak and OpenClaw trust model with measured findings, and admit scanning a 'Python port/reconstruction' rather than original source, blurring fact and inference, so 1.
- Versions and rule counts conflict badly across documents (51/63/66 rules; v0.14.1/v0.15.x/v0.19.0/v0.20.0); trust the installed version, not README numbers.
- Self-reported high false-positive rate (90.4% likely FP on OpenClaw; FP 90 in the benchmark) means CI gating may be noisy; converge first with baseline and --severity.
- The inspect subcommand spawns third-party MCP server processes (e.g. npx -y), a supply-chain and execution risk; run it in isolation and review the command.
- Benchmark F1 0.7581 coexists with a self-admitted non-reproducible 'adjusted 0.84'; do not use the latter for tool selection.
- Reports mix the names Argus and agent-audit, and the Claude Code analysis is based on a 'Python port/reconstruction' rather than original source; extrapolate conclusions cautiously.
- Publisher identity is unverified and maintenance responsibility/update path are unclear; assess long-term maintenance risk before production adoption.