brox 0.1.0
Repo scanner that turns agent/tool/model changes into a PR capability diff and blocks unsafe power upgrades
License: Apache 2.0
Requires Python: >=3.11
Keywords: agent-security, ai-bom, capability-diff, mcp, sbom, security, supply-chain


<div align="center">
    <img src="assets/logo.png" alt="brox - AI-BOM Generator and Capability Diff Tool for MCP and Agents" width="200">
    <h1>AI-BOM Generator and Capability Diff Tool for MCP and Agents</h1>
</div>

![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)
![Security Policy](https://img.shields.io/badge/security-policy-brightgreen)
![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)

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

```bash
pip install brox
```

Or install from source:

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

### Usage

#### 1. Scan a repository

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

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

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

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

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

```json
{
  "$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

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

### Run Tests

```bash
pytest
```

### Code Formatting

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