brox 0.1.0

Repo scanner that turns agent/tool/model changes into a PR capability diff and blocks unsafe power upgrades

AI-BOM Generator and Capability Diff Tool for MCP and Agents

brox scans a repo, produces an AI-BOM, and generates a capability diff (the "power change" in a PR): new MCP tools, widened filesystem scopes, new model egress, system prompt edits, new agent frameworks, etc. Then it gates merges with policy-as-code.

Don't just track code changes. Track Power changes.

Quick Start

Installation

pip install brox

Or install from source:

git clone https://github.com/yourusername/brox.git
cd brox
pip install -e .

Usage

1. Scan a repository

brox scan --repo . --out head.aibom.json

This generates an AI-BOM (Bill of Materials) in CycloneDX format, containing:

• MCP servers and their capabilities
• Prompts (file-based and inline)
• LLM provider endpoints
• Agent frameworks
• Network egress domains

2. Compare two AI-BOMs

brox diff --base base.aibom.json --head head.aibom.json --out capdiff.json --md capdiff.md

This generates:

• capdiff.json: Structured capability diff
• capdiff.md: Human-readable markdown report for PRs

3. Gate with policy

brox gate --diff capdiff.json --policy policy.yaml

Exit codes:

• 0: Pass
• 2: Policy blocked (fail CI)
• 3: Internal error

What brox Detects

MCP Servers

• Configuration files: mcp.json, mcp.yaml, servers.json
• Extracted capabilities:
  • filesystem.read / filesystem.write with scopes
  • exec.shell for shell execution
  • db.read / db.write for database access
  • network.egress for network tools

Prompts

• File-based: .prompt, .jinja, .jinja2, .md files in prompts/, agents/, system/ directories
• Inline: Multiline strings (≥200 chars) near LLM client calls
• Risk signals: "ignore previous", "bypass safety", "exfiltrate", "reveal secrets"

LLM Providers & Egress

• OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Cohere
• Generic HTTP egress to external domains
• Maps to network.egress capabilities

Agent Frameworks

• LangChain, LlamaIndex, Autogen, CrewAI, Semantic Kernel, Haystack

Policy Configuration

Create a policy.yaml file to define rules:

version: 1
rules:
  - id: block-shell-exec
    when:
      capability_added: "exec.shell"
    action: block
    message: "Shell execution introduced. Requires security approval."

  - id: block-broad-fs-write
    when:
      capability_added: "filesystem.write"
      scope_matches_any:
        - "/**"
        - "/etc/**"
        - "~/.ssh/**"
        - "**/*.pem"
    action: block
    message: "Broad filesystem write introduced."

  - id: warn-system-prompt-change
    when:
      asset_changed_kind: "prompt"
      prompt_type: "system"
    action: warn
    message: "System prompt changed. Review for jailbreak/injection patterns."

Policy Actions

• block: Fail CI (exit code 2)
• warn: Pass CI but annotate
• require_approval: Fail CI unless approval signal present (e.g., PR label)

Condition Syntax

• capability_added: Match new capabilities
• capability_widened: Match expanded scopes
• asset_added_kind: Match new assets by kind
• asset_changed_kind: Match changed assets by kind
• scope_matches_any: Glob patterns for scope matching

GitHub Action Integration

Add .github/workflows/brox.yml:

name: brox — Capability Diff

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  brox:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - name: Checkout head
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install brox
        run: pip install brox

      - name: Scan HEAD
        run: brox scan --repo . --out head.aibom.json

      - name: Checkout base
        run: git checkout origin/${{ github.base_ref }}

      - name: Scan BASE
        run: brox scan --repo . --out base.aibom.json

      - name: Diff + Gate
        run: |
          git checkout ${{ github.sha }}
          brox diff --base base.aibom.json --head head.aibom.json --out capdiff.json --md capdiff.md
          brox gate --diff capdiff.json --policy policy.yaml

      - name: Upload artifacts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: brox
          path: |
            base.aibom.json
            head.aibom.json
            capdiff.json
            capdiff.md

AI-BOM Format

brox generates CycloneDX-compatible AI-BOMs with custom properties:

{
  "$schema": "https://cyclonedx.org/schema/bom-1.5.schema.json",
  "bomFormat": "CycloneDX",
  "specVersion": "1.5",
  "version": 1,
  "metadata": {
    "timestamp": "2026-02-11T00:00:00Z",
    "tools": [{"vendor": "brox", "name": "brox", "version": "0.1.0"}]
  },
  "components": [
    {
      "type": "service",
      "name": "mcp-server:filesystem-server",
      "bom-ref": "mcp_server:filesystem-server",
      "properties": [
        {"name": "brox.ai.asset.kind", "value": "mcp_server"},
        {"name": "brox.location.file", "value": "mcp.json"}
      ]
    }
  ],
  "services": [
    {
      "name": "brox.ai.capabilities",
      "properties": [
        {
          "name": "brox.capability.record",
          "value": "cap=filesystem.write;scope=./data/**;evidence=mcp.json:12;asset=mcp_server:filesystem-server"
        }
      ]
    }
  ]
}

Risk Scoring

brox automatically assesses risk levels:

• Low: No significant changes
• Medium: New egress domain, agent framework, or system prompt change
• High: Shell execution, sensitive filesystem access, database writes
• Critical: Shell exec + broad filesystem write, or sensitive paths + egress

Development

Setup

git clone https://github.com/yourusername/brox.git
cd brox
pip install -e ".[dev]"

Run Tests

pytest

Code Formatting

black brox/
ruff check brox/

License

Apache 2.0

Contributing

Contributions welcome! Please open an issue or PR.

Roadmap

• TypeScript/JavaScript language support
• Capability provenance tracking
• CODEOWNERS-based approval workflows
• AI-BOM registry for org dashboards
• Secret/PII flow analysis
• Plugin system for custom detectors

---

Capabilities + diff + gate + evidence. Not "security theater," not "SBOM spam," just power deltas in PRs.