Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
239 lines (182 loc) · 11 KB

ARCHITECTURE.md

File metadata and controls

239 lines (182 loc) · 11 KB

Architecture

One agent-bom product, multiple operational surfaces. The package exposes CLI entry points, API/UI, MCP server mode, runtime proxy/gateway, cloud posture, IaC scanning, fleet, graph, reporting, and compliance workflows over the same core evidence model.

0. Hermetic single-language stack

agent-bom is pure Python (3.11+) end to end — CLI, FastAPI surface, MCP server, parsers, OSV/NVD/EPSS/KEV/GHSA enrichment, blast-radius scoring, IaC engine, and CIS benchmarks all live in the same interpreter. There is no Rust/Go/CGo extension on the scan path. Disk-image scans use native dpkg / RPM parsers (src/agent_bom/filesystem.py); the syft Go binary is opt-in only as a tar-archive fallback for VM-style images.

Operational consequences:

  • One language, one dep tree, one pip-audit/SBOM surface to audit and reproduce.
  • Wheels build cleanly on linux/amd64 and linux/arm64 — no per-arch native toolchain.
  • Slower than Rust/Go scanners on huge fanouts; per-package memory is higher. For VM disk-image scanning at scale, install syft alongside agent-bom and let the fallback path take over.

1. System Overview — Product Surfaces

pip install agent-bom    → shared core engine plus focused CLI entry points

Read the architecture in one direction: collect evidence, normalize it into one AI-BOM/security model, then use that same model for local scans, the self-hosted control plane, runtime enforcement, and audit/compliance outputs. This diagram is intentionally a product map, not a full module graph.

flowchart TB
    Sources["1. Evidence sources\nRepos, lockfiles, SBOMs\nAgents, MCP servers, tools\nCloud, IaC, containers, GPUs\nRuntime proxy and gateway events"]
    Model["2. Shared evidence model\nInventory\nFindings + enrichment\nSecurity graph\nAudit + provenance"]
    Surfaces["3. Product surfaces\nLocal scan: CLI, Docker, GitHub Action\nControl plane: REST API, UI, fleet, Helm\nRuntime enforcement: MCP server, proxy, gateway, Shield"]
    Outputs["4. Decisions and artifacts\nDeveloper gates: terminal, SARIF, HTML\nSecurity triage: blast radius, graph paths\nGovernance: compliance evidence, audit trail\nOperations: fleet state, runtime blocks"]

    Sources --> Model --> Surfaces --> Outputs
Loading
Surface First command Primary artifact Production move
Local scan agent-bom agents -p . findings, SBOM, SARIF, HTML, graph export GitHub Action or Docker scan in CI
Control plane agent-bom agents -p . --push-url ... fleet inventory, scan jobs, graph state Helm/EKS with Postgres and tenant auth
Runtime enforcement agent-bom proxy ... or agent-bom mcp server audit JSONL, policy decisions, blocks gateway/proxy sidecars and Shield SDK

2. Scan Pipeline

Sequence of operations from invocation to report.

sequenceDiagram
    participant User
    participant CLI
    participant Discovery
    participant Scanner
    participant Enrichment
    participant BlastRadius
    participant Reporter

    User->>CLI: agent-bom agents [options]
    CLI->>Discovery: Detect MCP configs, images, clouds
    Discovery-->>CLI: Agents, servers, packages, tools

    CLI->>Scanner: Package list
    Scanner->>Scanner: OSV batch query
    Scanner-->>CLI: Raw CVE results

    CLI->>Enrichment: CVE IDs
    Enrichment->>Enrichment: NVD CVSS · EPSS · CISA KEV · GHSA
    Enrichment-->>CLI: Enriched vulnerabilities

    CLI->>BlastRadius: Vulns + topology
    BlastRadius->>BlastRadius: package → finding → server → agent → creds → tools
    BlastRadius->>BlastRadius: Tag 15 frameworks + attach AISVS benchmark
    BlastRadius-->>CLI: Scored + tagged findings

    CLI->>Reporter: Full results
    Reporter-->>User: Console / JSON / SARIF / HTML / SBOM
Loading

3. Blast Radius Propagation

How one CVE propagates through the AI agent stack.

graph LR
    CVE["CVE-2025-XXXX\nCRITICAL · CVSS 9.8"]
    PKG["Vulnerable Package\nnpm / PyPI / Go"]
    SRV["MCP Server\nunverified · root"]

    AGT1["Cursor IDE\n4 servers · 12 tools"]
    AGT2["Claude Desktop\n3 servers · 8 tools"]

    CRED["ANTHROPIC_KEY\nAWS_SECRET · DB_URL"]
    TOOL["query_db · read_file\nwrite_file · run_shell"]

    CVE -->|affects| PKG
    SRV -->|depends_on| PKG
    SRV -->|vulnerable_to| CVE
    AGT1 & AGT2 -->|uses| SRV
    SRV -->|exposes_cred| CRED
    SRV -->|provides_tool| TOOL
    CRED -->|reaches_tool| TOOL

    style CVE fill:#dc2626,color:#fff
    style PKG fill:#ea580c,color:#fff
    style SRV fill:#d97706,color:#fff
    style AGT1 fill:#2563eb,color:#fff
    style AGT2 fill:#2563eb,color:#fff
    style CRED fill:#7c3aed,color:#fff
    style TOOL fill:#059669,color:#fff
Loading

Color key: Red = CVE · Orange = Package · Amber = Server · Blue = Agent · Purple = Credentials · Green = Tools

The full contract for what the graph promises and what it does not — entity types, edge kinds, scaling tiers, re-baseline procedure, and known coverage gaps — is in docs/graph/CONTRACT.md.

4. Compliance Tagging

Every finding is tagged against curated compliance frameworks, grouped into four families. OWASP AISVS is exposed as a separate benchmark result with per-check evidence. The bundled mappings are a curated subset of each framework focused on AI/MCP/agent risk-relevant controls — they are not a complete catalog. See Coverage per framework below for the generated control counts.

graph LR
    F["Finding\nCVE + severity + context"]

    subgraph OWASP["OWASP"]
        O1["LLM Top 10"]
        O2["MCP Top 10"]
        O3["Agentic Top 10"]
        O4["AISVS v1.0"]
    end

    subgraph NIST["NIST / FedRAMP"]
        N1["AI RMF 1.0"]
        N2["CSF 2.0"]
        N3["800-53 Rev 5"]
        N4["FedRAMP"]
    end

    subgraph INTL["Regulatory"]
        I1["EU AI Act"]
        I2["ISO 27001"]
        I3["SOC 2"]
        I4["CIS Controls v8"]
        I5["CMMC 2.0"]
    end

    ATL["MITRE ATLAS"]

    F --> OWASP & NIST & INTL & ATL

    T["Tagged Finding\n14 controls attached"]
    OWASP & NIST & INTL & ATL --> T

    style F fill:#dc2626,color:#fff
    style T fill:#059669,color:#fff
Loading

Coverage per framework

agent-bom ships a curated control set per framework, sized to the AI/MCP/agent threat surface rather than a generic compliance scanner's full catalog. Numbers below count the controls that are bundled and actively mapped by the canonical metadata in src/agent_bom/compliance_coverage.py; AISVS is counted from the benchmark check registry. They are intentionally a subset; consult each framework's source standard for full coverage.

Family Framework Bundled controls Source-standard size (approx.) What's covered
OWASP LLM Top 10 (2025) 10 / 10 10 Full Top-10
OWASP MCP Top 10 (2025) 10 / 10 10 Full Top-10
OWASP Agentic Top 10 (2026) 10 / 10 10 Full Top-10
OWASP AISVS v1.0 9 checks ~50 verification reqs Programmatically verifiable subset (AI-4/5/6/7/8 categories)
NIST / FedRAMP AI RMF 1.0 14 subcategories ~70 Govern / Map / Measure / Manage controls relevant to AI supply chain + MCP
NIST / FedRAMP CSF 2.0 14 categories ~108 Supply-chain, identity, asset, monitoring categories
NIST / FedRAMP 800-53 Rev 5 29 controls ~1,006 Vulnerability-driven mapping (RA-5, SI-2, etc.); not a complete catalog
NIST / FedRAMP FedRAMP Moderate 25 controls ~325 Subset of 800-53 controls in the Moderate baseline
MITRE ATLAS 65 techniques ~90 LLM/AI techniques: prompt injection, jailbreak, supply-chain, exfiltration, agent tool abuse
MITRE ATT&CK Enterprise 0 techniques ~600 Adversary techniques tagged via CWE → CAPEC → ATT&CK on every blast-radius finding
Regulatory EU AI Act 6 articles ~113 Articles 5/6/9/10/15/17 (prohibited practices, high-risk classification, risk mgmt, data governance, accuracy/cybersecurity, QMS)
Regulatory ISO/IEC 27001:2022 9 Annex A controls 93 Supplier, vulnerability, cryptography, secure-dev, evidence collection
Regulatory SOC 2 TSC 9 criteria ~64 Common Criteria 6.x / 7.x / 8.x / 9.x (access, monitoring, change mgmt, vendor risk)
Regulatory CIS Controls v8 10 safeguards 153 Software inventory, vulnerability mgmt, secure-dev (CIS 02 / 07 / 16)
Regulatory CMMC 2.0 Level 2 17 practices 110 RA / SI / SC / CM / AC / IA practices most relevant to vulnerable-package risk
Regulatory PCI DSS v4.0 12 requirements 12 Requirements 2/3/4/5/6/7/8/10/11/12 for vulnerable-package and evidence risk

The bundled list is editable: see src/agent_bom/compliance_coverage.py for the framework metadata and src/agent_bom/compliance_utils.py for the BlastRadius field map. The UI consumes the same API response shape, so product coverage and dashboard controls should stay aligned with these catalogs.

5. Integration

How agent-bom fits into CI/CD, runtime, cloud, and enterprise tooling.

graph TB
    AB["agent-bom\nCore Engine"]

    CI["CI/CD\nGitHub Actions · Policy Gate · SARIF Upload · JS supply-chain guard"]
    RT["Runtime\nMCP Proxy · Docker Sidecar · OpenTelemetry"]
    HOSTS["MCP Hosts\n30 client types"]
    CLOUD["Cloud Providers\nAWS · Azure · GCP · Snowflake"]
    ENT["Enterprise\nSIEM · Slack · Jira · Webhooks · Prometheus"]

    CI -->|scan step| AB
    RT -->|intercept / monitor| AB
    HOSTS -->|config discovery| AB
    CLOUD -->|API discovery| AB
    AB -->|alerts / tickets / metrics| ENT

    style AB fill:#2563eb,color:#fff
Loading

Key modules

Module Path Responsibility
CLI src/agent_bom/cli/ Click entry point, command dispatch
Discovery src/agent_bom/discovery/__init__.py MCP client config discovery (29 first-class client types plus dynamic/project surfaces)
Parsers src/agent_bom/parsers/__init__.py Package extraction + MCP registry lookup
Scanners src/agent_bom/scanners/__init__.py OSV batch scan + CVSS + compliance tagging
Enrichment src/agent_bom/enrichment.py NVD + EPSS + CISA KEV enrichment
Models src/agent_bom/models.py Core data models (Package, Vulnerability, Agent, BlastRadius)
Output src/agent_bom/output/__init__.py JSON, CycloneDX, SARIF, SPDX, console
Policy src/agent_bom/policy.py Policy-as-code engine (17 conditions)
Proxy src/agent_bom/proxy.py Runtime MCP proxy (7 inline detectors)
MCP Server src/agent_bom/mcp_server.py FastMCP server (51 tools)
Cloud src/agent_bom/cloud/ AWS, Azure, GCP, Snowflake, Databricks, ClickHouse
Asset Tracker src/agent_bom/asset_tracker.py Persistent vuln tracking — first_seen, resolved, MTTR
Context Graph src/agent_bom/context_graph.py Lateral movement analysis — see Graph Contract for entity/edge coverage, accuracy guarantees, and scaling boundaries
Guard src/agent_bom/guard.py Pre-install CVE scan for pip/npm packages