Metadata-Version: 2.4
Name: ai-agentbom
Version: 0.7.0
Summary: Offline AI agent bill of materials and attack surface scanner
Author: AgentBOM contributors
License: MIT
Project-URL: Homepage, https://github.com/vlcak27/agentbom
Project-URL: Issues, https://github.com/vlcak27/agentbom/issues
Project-URL: Repository, https://github.com/vlcak27/agentbom
Keywords: ai,agents,security,bom,sast,mcp,sarif
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: pre-commit>=4; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# AgentBOM

![CI](https://github.com/vlcak27/agentbom/actions/workflows/ci.yml/badge.svg)
![PyPI](https://img.shields.io/pypi/v/ai-agentbom)
![Python](https://img.shields.io/pypi/pyversions/ai-agentbom)
![License](https://img.shields.io/badge/license-MIT-blue)

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.

![AgentBOM HTML report preview](docs/assets/html-report-preview.svg)

## Quickstart

```bash
pip install ai-agentbom
agentbom scan . --pretty
```

Generate review artifacts:

```bash
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:

```bash
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](docs/report-guide.md) 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.

```yaml
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:

```yaml
permissions:
  contents: read
  security-events: write
```

More details: [GitHub Action docs](docs/github-action.md).

## 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

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

Or run the project check:

```bash
make check
```

Useful docs:

- [CHANGELOG.md](CHANGELOG.md)
- [CONTRIBUTING.md](CONTRIBUTING.md)
- [SECURITY.md](SECURITY.md)
- [ARCHITECTURE.md](ARCHITECTURE.md)
