AI BOM

The AI BOM tool scans codebases and container images to inventory AI framework components (models, agents, tools, prompts, and more). It parses Python source code, resolves fully qualified symbols, and matches them against a DuckDB catalog to produce an AI bill of materials. Optional LLM enrichment extracts model names, and a workflow pass annotates components with call-path context.

View on GitHub | Join Discord

Features

• Static Python analysis -- Uses libcst to capture assignments, decorators, type annotations, context managers, class definitions, and inline annotations
• Container image scanning -- Extracts /app from Docker images when available, otherwise scans site-packages
• DuckDB catalog matching -- Maps fully qualified symbols to curated component categories
• Custom catalog -- Register custom AI components, base-class detection rules, exclude patterns, relationship hints, and custom relationship types via .aibom.yaml
• Inline annotations -- Tag classes and functions directly in source code with # aibom: concept=... comments
• Base class detection -- Automatically categorize classes that inherit from specified base classes
• Workflow context -- Builds a lightweight call graph to show which workflows reach each component
• Derived relationships -- Infers USES_TOOL, USES_LLM, USES_MEMORY, USES_RETRIEVER, USES_EMBEDDING, and user-defined relationship links
• Optional LLM enrichment -- Uses litellm to extract model/embedding names from code snippets
• Multiple outputs -- Plaintext, JSON, or a FastAPI API server

Installation

Prerequisites: Python 3.11+, uv (recommended), Docker (optional), LLM provider API key (optional)

# Install as a CLI tool
uv tool install --python 3.13 cisco-aibom

# Or install from source
uv tool install --python 3.13 --from git+https://github.com/cisco-ai-defense/aibom cisco-aibom

# Verify
cisco-aibom --help

For local development:

git clone https://github.com/cisco-ai-defense/aibom.git
cd aibom/aibom
uv sync
source .venv/bin/activate

Knowledge Base Configuration

The analyzer uses a local DuckDB catalog. Download the catalog artifact from GitHub Releases:

VERSION="<version>"
mkdir -p "${HOME}/.aibom/catalogs"

gh release download "${VERSION}" \
  --repo cisco-ai-defense/aibom \
  --pattern "aibom_catalog-${VERSION}.duckdb" \
  --dir "${HOME}/.aibom/catalogs"

export AIBOM_DB_PATH="${HOME}/.aibom/catalogs/aibom_catalog-${VERSION}.duckdb"

Usage

Analyze Sources

# Local directory (JSON output)
cisco-aibom analyze /path/to/project --output-format json --output-file report.json

# Container image
cisco-aibom analyze langchain-app:latest --output-format json --output-file report.json

# Multiple images from a JSON list
cisco-aibom analyze --images-file images.json --output-format plaintext --output-file report.txt

Render a JSON Report

cisco-aibom report report.json --raw-json

Optional LLM Enrichment

cisco-aibom analyze /path/to/project \
  --output-format json \
  --output-file report.json \
  --llm-model gpt-3.5-turbo \
  --llm-api-base https://api.openai.com/v1 \
  --llm-api-key $OPENAI_API_KEY

Optional Report Submission

cisco-aibom analyze /path/to/project \
  --output-format json \
  --output-file report.json \
  --post-url https://api.security.cisco.com/api/ai-defense/v1/aibom/analysis \
  --ai-defense-api-key $AI_DEFENSE_API_KEY

Regional endpoints:

Custom Catalog

The built-in DuckDB catalog covers popular AI frameworks (LangChain, LangGraph, CrewAI, PyTorch, scikit-learn, etc.), but many teams build custom wrappers. The custom catalog lets you teach the analyzer about these components.

Place a .aibom.yaml in your project root:

components:
  - id: MyLLMWrapper
    concept: model
    label: My Custom LLM
    framework: internal

  - id: myproject.tools.SearchTool
    concept: tool

base_classes:
  - class: BaseTool
    concept: tool
  - class: mylib.BaseAgent
    concept: agent

excludes:
  - langchain.deprecated.OldAgent

relationship_hints:
  tool_arguments:
    - custom_tools
    - plugins
  llm_arguments:
    - language_model

custom_relationships:
  - label: ROUTES_TO
    source_categories: [router]
    target_categories: [agent]
    argument_hints: [routes, destinations]

Inline Annotations

Tag classes or functions directly in source code:

# aibom: concept=guardrail framework=internal
class SafetyFilter:
    """Custom content-safety guardrail."""
    def check(self, text: str) -> bool:
        ...

# aibom: concept=tool label=WebSearch
def search_web(query: str) -> list:
    ...

Precedence

1. Inline annotation (# aibom: concept=...)
2. Base class rule (from .aibom.yaml)
3. Custom component entry (from .aibom.yaml)
4. Supplemental catalog (built-in entries)
5. DuckDB catalog (prebuilt knowledge base)

Exclude patterns override all of the above.

Output Formats

Plaintext

--- AI BOM Analysis Report ---
[+] Found 4 MODEL:
  - Name: langchain_community.llms.openai.OpenAI
    Model: gpt-3.5-turbo-instruct
    Source: /app/comprehensive_langchain_app.py:32
--- End of Report: Found 42 total components across all sources. ---

JSON

Structured output with metadata, sources, components, relationships, workflows, and summary.

API Mode

cisco-aibom analyze /path/to/project --output-format api

Technical Details

• Parsing: libcst extracts fully qualified names for calls, decorators, type annotations, context managers, class definitions, and inline annotations
• Catalog matching: Symbols are matched against the DuckDB component_catalog table using suffix matching
• Workflow analysis: AST-based workflow analyzer associates components with calling functions
• Relationships: Agent arguments inspected to derive USES_TOOL, USES_LLM, USES_MEMORY, USES_RETRIEVER, USES_EMBEDDING links
• LLM enrichment: litellm is used only when --llm-model is supplied

Troubleshooting

• DuckDB catalog errors -- Ensure the catalog file exists at AIBOM_DB_PATH and checksums match
• Docker issues -- Container analysis requires a working Docker CLI and daemon
• LLM configuration errors -- --llm-api-base is required whenever --llm-model is set
• Missing output files -- --output-file is mandatory for plaintext and json formats

License

Apache 2.0 -- See LICENSE for details.