GitHub – HeadyZhang/agent-audit: Security scanner for AI agents and MCP configurations


PyPI version
Python
License: MIT
CI
OWASP Coverage

The first open-source static analyzer purpose-built for AI agent code.
Maps every finding to the OWASP Agentic Top 10 (2026). 40+ detection rules. Native support for LangChain, CrewAI, AutoGen, and MCP.

首个专为 AI Agent 代码设计的开源静态分析器。
每项发现均映射到 OWASP Agentic Top 10 (2026)。40+ 检测规则。原生支持 LangChain、CrewAI、AutoGen 和 MCP。

Agent Audit Demo


✨ Features | 核心能力

Detection Engines | 检测引擎

Engine What it does
Python AST Scanner Deep analysis of agent code: tool decorators, executor instantiation, dangerous sinks (eval, subprocess, cursor.execute)
Taint Tracker Intra-procedural data flow analysis from user input → dangerous operations
Semantic Analyzer 3-stage credential detection: regex patterns → entropy/placeholder analysis → context scoring
MCP Config Scanner Validates claude_desktop_config.json / MCP Gateway configs for filesystem exposure, unpinned packages, missing auth
MCP Runtime Inspector Probes live MCP servers via stdio/SSE without executing tools — “Nmap for AI agents”

Under the Hood | 引擎细节

  • TaintTracker — Tracks data flow from sources (request, user_input, query) to sinks (exec, subprocess.run, cursor.execute)
  • SemanticAnalyzer — Three-stage credential analysis: (1) regex candidate discovery, (2) entropy + placeholder detection, (3) file path / framework context adjustment
  • DangerousOperationAnalyzer — Identifies when @tool function parameters flow to shell execution, SQL queries, or file writes
  • PrivilegeScanner — Detects daemon registration (launchctl, systemctl), sudoers NOPASSWD, unsandboxed browser automation, credential store access
  • Framework-aware rules — Specific detections for AgentExecutor, @tool, SystemMessage, Crew, ConversableAgent
  • Confidence tiering — Every finding scored 0.0–1.0, classified as BLOCK (≥0.9) / WARN (≥0.6) / INFO (≥0.3) / SUPPRESSED

🚀 Quick Start | 快速开始

Basic Usage | 基本使用

# Scan current directory
agent-audit scan .

# Output SARIF for GitHub Code Scanning
agent-audit scan . --format sarif --output results.sarif

# Fail CI only on critical/high findings
agent-audit scan . --fail-on high

# Inspect a live MCP server (without executing tools)
agent-audit inspect stdio -- npx -y @modelcontextprotocol/server-filesystem /tmp

🎯 Detection Coverage | 检测覆盖

40 rules mapped to the complete OWASP Agentic Top 10 (2026):

ASI Category Rules Key Detections
ASI-01 Goal Hijacking AGENT-010 011 027 050 System prompt injection, f-string in SystemMessage, AgentExecutor without safety params
ASI-02 Tool Misuse AGENT-001 026 029 032 034 035 036 040 041 Command injection, SQL injection via f-string, @tool without input validation, overly broad MCP filesystem access
ASI-03 Privilege Abuse AGENT-002 013 014 042 Excessive tool grants, long-lived credentials, daemon privilege escalation, >10 MCP servers
ASI-04 Supply Chain AGENT-004 005 015 016 030 Hardcoded API keys, unpinned npx packages, unverified MCP servers, unvalidated RAG sources
ASI-05 Code Execution AGENT-003 017 031 Unsandboxed eval/exec, data exfiltration chain (sensitive data + network access)
ASI-06 Memory Poisoning AGENT-018 019 Unsanitized input to vector stores, unbounded conversation history
ASI-07 Inter-Agent Comms AGENT-020 Unencrypted/unauthenticated multi-agent channels
ASI-08 Cascading Failures AGENT-021 022 028 Missing max_iterations, no error handling in tools, unbounded agent loops
ASI-09 Trust Exploitation AGENT-023 033 037 038 039 052 Opaque agent output, MCP without auth, missing human approval, agent impersonation prompts, sensitive data logging
ASI-10 Rogue Agents AGENT-024 025 053 No kill switch, no behavioral monitoring, agent self-modification

📖 Full Rule Reference → — Every rule with CWE mapping, fix guidance, and code examples.


Basic Integration | 基础集成

name: Agent Security Scan
on: [push, pull_request]

jobs:
  agent-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Agent Audit
        uses: HeadyZhang/agent-audit@v1
        with:
          path: '.'
          fail-on: 'high'
          upload-sarif: 'true'

PR Comment Integration | PR 评论集成

Automatically post scan results as a PR comment:

name: Agent Audit PR Review
on: pull_request

jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      security-events: write
    steps:
      - uses: actions/checkout@v4

      - name: Run Agent Audit
        id: audit
        uses: HeadyZhang/agent-audit@v1
        with:
          path: '.'
          format: 'sarif'
          fail-on: 'high'
          upload-sarif: 'true'
        continue-on-error: true

      - name: Comment PR with Results
        if: always()
        uses: actions/github-script@v7
        with:
          script: |
            const outcome="${{ steps.audit.outcome }}";
            const status = outcome === 'success' ? '✅ Passed' : '⚠️ Issues Found';
            const body = `## 🛡️ Agent Audit Results\n\n**Status:** ${status}\n\n📄 Full results available in the **Security** tab.`;
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: body
            });

Scheduled Full Scan | 定时全量扫描

Run a comprehensive weekly audit:

name: Weekly Agent Security Audit
on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday 9:00 AM UTC
  workflow_dispatch:     # Allow manual trigger

jobs:
  full-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Full Audit
        uses: HeadyZhang/agent-audit@v1
        with:
          path: '.'
          severity: 'info'        # Report all findings
          fail-on: 'critical'     # Only fail on critical
          upload-sarif: 'true'

Action Inputs | Action 参数

Input Description Default
path Path to scan .
format Output format: terminal, json, sarif, markdown sarif
severity Minimum severity to report: info, low, medium, high, critical low
fail-on Exit non-zero if findings at this severity or above high
baseline Path to baseline file for incremental scanning
upload-sarif Upload SARIF to GitHub Security tab true

For GitLab CI, Jenkins, Azure DevOps → CI/CD Integration Guide


📖 Understanding Results | 理解扫描结果

Field Description
Rule ID Unique identifier (e.g., AGENT-034). See Rule Reference
Severity CRITICAL > HIGH > MEDIUM > LOW > INFO
Confidence BLOCK (≥0.9) / WARN (≥0.6) / INFO (≥0.3) — higher = fewer false positives
Location File path and line number

What to Do | 如何处理

Tier Action
BLOCK Fix immediately — high-confidence exploitable vulnerability
WARN Fix before merge — likely real issue
INFO Review and decide — may be intentional

Suppress known issues with # noaudit comment or .agent-audit.yaml configuration.


⚙️ Configuration | 配置

Create .agent-audit.yaml to customize scanning:

# Allowed network hosts
allowed_hosts:
  - "*.internal.company.com"
  - "api.openai.com"

# Ignore rules
ignore:
  - rule_id: AGENT-003
    paths:
      - "auth/**"
    reason: "Auth module legitimately communicates externally"

# Scan settings
scan:
  exclude:
    - "tests/**"
    - "venv/**"
  min_severity: low
  fail_on: high

📈 Baseline Scanning | 基线扫描

Track new findings incrementally:

# Save current findings as baseline
agent-audit scan . --save-baseline baseline.json

# Only report NEW findings
agent-audit scan . --baseline baseline.json

📖 CLI Reference | 命令行参考

Usage: agent-audit [OPTIONS] COMMAND [ARGS]...

Commands:
  scan     Scan agent code and configurations
  inspect  Inspect an MCP server at runtime
  init     Initialize configuration file

Options:
  --version   Show version
  -v          Enable verbose output
  -q          Only show errors
  --help      Show this message

📚 Documentation | 文档


🛠️ Development | 开发

See CONTRIBUTING.md for full setup instructions.

git clone https://github.com/HeadyZhang/agent-audit
cd agent-audit/packages/audit
poetry install
poetry run pytest ../../tests/ -v

MIT License — see LICENSE for details.


Built for the AI agent security community
Report Bug · Request Feature · Browse Rules



Source link

Leave a Reply

Your email address will not be published. Required fields are marked *