ai-agentbom 0.7.0

Offline AI agent bill of materials and attack surface scanner

AgentBOM

AgentBOM is a static security scanner for AI-agent repositories. It detects AI providers, model identifiers, agent frameworks, prompts, MCP servers, secret references, and risky capabilities that appear reachable from an agent.

AgentBOM does not run code. It does not import scanned modules, execute MCP servers, contact networks, or store secret values.

It is different from SAST and SBOM tools because it focuses on AI-agent attack surface: which models, prompts, frameworks, MCP servers, and capabilities appear connected in the repository. Use SAST for language-specific vulnerability patterns and SBOM tools for package inventory. Use AgentBOM to review agent context and statically inferred reachability.

Quickstart

pip install ai-agentbom
agentbom scan . --pretty

Generate review artifacts:

agentbom scan . --output-dir agentbom-report --html --mermaid --sarif --pretty

AgentBOM always writes:

• agentbom.json: machine-readable findings
• agentbom.md: human-readable review report

Optional outputs:

Flag	Output	Use
--html	agentbom.html	self-contained offline report
--mermaid	agentbom.mmd	capability graph
--sarif	agentbom.sarif	GitHub code scanning and SARIF consumers
--cyclonedx	agentbom.cdx.json	package ecosystem inventory workflows

What It Finds

Area	Examples
Providers	OpenAI, Anthropic, Gemini, Ollama, DeepSeek, OpenRouter
Models	gpt-5.1, gpt-4o-mini, o3-mini, claude-sonnet-4.6, gemini-3.1-pro, deepseek-r1, llama-3.3-70b-instruct, qwen2.5-coder, grok-4, command-r-plus, sonar-pro, OpenRouter and LiteLLM-prefixed model strings
Frameworks	LangChain, LangGraph, LlamaIndex, CrewAI, AutoGen/AG2, Semantic Kernel, Pydantic AI, OpenAI Agents SDK, Claude Agent SDK, Mastra, Google ADK, Vercel AI SDK, LiteLLM, Instructor, Haystack, DSPy, LangServe
Prompts	AGENTS.md, CLAUDE.md, prompts/*.md, prompt YAML
MCP	mcp.json, .mcp.json, claude_desktop_config.json, nested Cursor/Claude MCP config paths
MCP server risk	filesystem, shell/process, browser/network, database, cloud, secrets/env, unknown/custom servers
Capabilities	shell, code execution, network, database, cloud, MCP tool invocation
Secret references	credential names such as OPENAI_API_KEY, never values
Dependencies	deterministic AI-relevant dependency extraction from Python, JavaScript, Rust, and Go manifests
Policy gaps	prompt files, MCP config, shell/cloud access without policy documentation

Findings include source paths, confidence, reviewer-facing rationale, and mitigation signals where static evidence is available.

Reports

Start with repository risk, review priorities, reachable capabilities, MCP security analysis, policy findings, and Changes since baseline.

Diff-aware scans compare the current report with a baseline JSON report:

agentbom scan . --baseline agentbom-baseline.json --fail-on-new high --sarif --html --pretty

--fail-on-new accepts low, medium, high, or critical. It evaluates new providers, capabilities, MCP servers, secret references, and policy findings introduced since the baseline.

See the report guide for field definitions and reviewer workflow.

GitHub Action

Use the action in pull requests to publish reports and a workflow job summary. When GITHUB_STEP_SUMMARY is available, AgentBOM summarizes repository risk, detected AI surface, reachable capabilities, and generated report files directly in the GitHub Actions run.

name: AgentBOM

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

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

      - name: Run AgentBOM
        uses: vlcak27/agentbom@v0.7.0
        with:
          path: .
          fail-on: none
          sarif-upload: false
          html: true
          output-dir: agentbom-report

      - name: Upload AgentBOM reports
        uses: actions/upload-artifact@v4
        with:
          name: agentbom-report
          path: agentbom-report/

Enable SARIF upload only when you want GitHub code scanning alerts:

permissions:
  contents: read
  security-events: write

More details: GitHub Action docs.

Security Model

AgentBOM is designed for safe repository review:

• static analysis only
• does not execute scanned code
• does not import scanned modules
• does not execute MCP servers
• does not contact networks during scanning
• skips files larger than 1 MB
• skips binary-looking files
• does not follow symlink loops
• records secret names only, never secret values
• works offline and emits deterministic output for the same input repository

Limitations

• Findings are review signals, not exploit verification.
• Reachability is inferred from nearby static evidence, not runtime traces.
• False positives and missed detections are possible.
• Detector coverage is intentionally AI-agent focused, not general SAST.
• Dependency parsing is deterministic and limited, not a full lockfile solver.
• AgentBOM is not an SBOM, SPDX, or CycloneDX replacement.

Development

pip install -e ".[dev]"
ruff check .
pytest

Or run the project check:

make check

Useful docs:

• CHANGELOG.md
• CONTRIBUTING.md
• SECURITY.md
• ARCHITECTURE.md