Metadata-Version: 2.4
Name: aibom-scanner
Version: 1.2.0
Summary: Scan codebases for AI SDK usage and map compliance risks to NIST AI RMF, ISO 42001, and EU AI Act
Project-URL: Homepage, https://github.com/saasvista/aibom-scanner
Project-URL: Documentation, https://github.com/saasvista/aibom-scanner#readme
Project-URL: Issues, https://github.com/saasvista/aibom-scanner/issues
Author-email: Mike Carroll <mike@saasvista.io>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai,aibom,compliance,eu-ai-act,governance,iso42001,nist,risk,sbom,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/banner.png" alt="aibom-scanner" width="100%">
</p>

<p align="center">
  <strong>Scan codebases for AI SDK usage. Map compliance risks to NIST AI RMF, ISO 42001, and EU AI Act.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/aibom-scanner/"><img src="https://img.shields.io/pypi/v/aibom-scanner?color=blue&label=PyPI" alt="PyPI"></a>
  <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python"></a>
  <a href="https://github.com/saasvista/aibom-scanner/actions/workflows/ci.yml"><img src="https://github.com/saasvista/aibom-scanner/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/saasvista/aibom-scanner"><img src="https://img.shields.io/badge/dependencies-0-brightgreen.svg" alt="Zero Dependencies"></a>
</p>

---

## Quick Start

```bash
pip install aibom-scanner

aibom-scanner scan --path /path/to/your/repo
```

<p align="center">
  <img src="docs/screenshot.png" alt="aibom-scanner output" width="700">
</p>

## What It Finds

`aibom-scanner` detects AI SDKs in your codebase and generates an **AI Bill of Materials (AIBOM)** with compliance risk findings mapped to three frameworks.

| | |
|---|---|
| **70 detection patterns** | OpenAI, Anthropic, Google AI, AWS Bedrock, Cohere, Mistral, Groq, HuggingFace, and 21 more |
| **Languages** | Python, JS/TS, Go, Java, Rust, Ruby, Swift, C#/.NET — imports, API calls, and dependency manifests |
| **10 Chinese AI providers** | 3 BIS Entity-Listed (Zhipu, iFlytek, SenseTime = CRITICAL), 7 data sovereignty flagged |
| **Agentic AI detection** | CrewAI, AutoGen, LangGraph, Semantic Kernel, MCP |
| **34 risk rules** | 8 categories with evidence-qualified severity adjustment |
| **48 compliance controls** | NIST AI RMF (23), ISO 42001 (15), EU AI Act (10) |
| **Secrets detection** | Hardcoded API keys, Vault, AWS Secrets Manager, dotenv |
| **Dev tool detection** | Cursor, GitHub Copilot, Claude Code, Aider, TabNine |
| **Coverage accounting** | Every scan reports what it read — and what it could not |
| **Zero dependencies** | Pure Python stdlib. Nothing to install but Python. |

## Coverage: what the scan actually read

An AI Bill of Materials that silently omits what it could not parse is not
incomplete, it is wrong. Every scan reports its own denominator:

```
Scanned 86 of 173 source files (49.7%) — 86 test/fixture files excluded, 98.9% of source attempted
```

Two ratios, because either one alone misleads:

| Field | Meaning |
|---|---|
| `coverage_pct` | `files_scanned / source_files_seen` — the honest headline. Every source file in the tree is in the denominator. |
| `readable_coverage_pct` | `files_scanned / (source_files_seen - skipped_by_path)` — isolates scanner capability from the tests and fixtures deliberately excluded. |

Quoting only the second would report ~99% for a scan that read half a repo.

Every unread source file is attributed to exactly one reason:

- **`skipped_by_path`** — intentional exclusion (tests, fixtures, examples, vendor).
- **`unscanned_by_extension`** — this scanner version cannot parse the language.

**Languages the scanner cannot read are reported, never treated as clean.** When any
turn up, a warning is printed to stderr, the table output shows an `INCOMPLETE
COVERAGE` block, and SARIF carries a `toolExecutionNotification` so the run reads as
partial rather than silently green. Currently unreadable: `.php`, `.scala`, `.clj`,
`.ex`, `.exs`, `.dart`, `.cpp`, `.c`, `.h`, `.hpp`, `.m`, `.mm`, `.pl`, `.lua`, `.r`,
`.jl`, `.ps1`, `.kts`.

## Observed vs inferred findings

Every finding carries an `evidence_basis`:

- **`observed`** — backed by something in the scanned source (a detection, a provider).
- **`inferred`** — a governance checklist item. Nothing in the source backs it.

Inferred findings reflect *absence of evidence, not evidence of absence*. Table output
separates them into their own section, `--severity-threshold` ignores them, and SARIF
does not emit them as code-scanning alerts — a governance checklist item is not a
defect at a code location.

## Output Formats

```bash
# Table output (default in terminal)
aibom-scanner scan --path . --format table

# JSON (default when piped) — includes coverage and evidence_basis
aibom-scanner scan --path . --format json > aibom.json

# SARIF for GitHub Code Scanning — observed findings only, coverage in run properties
aibom-scanner scan --path . --format sarif > results.sarif

# Fail CI on high/critical OBSERVED findings (exit 1)
aibom-scanner scan --path . --severity-threshold high

# Fail CI when the scanner could not read some languages (exit 3)
aibom-scanner scan --path . --fail-on-incomplete-coverage
```

| Exit code | Meaning |
|:---:|---|
| `0` | Scan completed, no gate tripped |
| `1` | Observed findings at or above `--severity-threshold` |
| `2` | Bad arguments, unreadable path, or interrupted |
| `3` | `--fail-on-incomplete-coverage` set and languages were unreadable |

If both gates trip, `1` wins — an observed finding is more actionable than a coverage gap.

The coverage warning always goes to **stderr**, so piping `--format json` or
`--format sarif` to a file yields clean, valid output.

## GitHub Action

Add AI compliance scanning to every PR:

```yaml
# .github/workflows/aibom-scan.yml
name: AIBOM Scan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: saasvista/aibom-scanner@v1
        with:
          severity-threshold: high
```

## AI Providers Detected

| Category | Providers |
|----------|-----------|
| **Major** | OpenAI, Anthropic, Google AI, AWS Bedrock, Azure OpenAI, Cohere, Mistral, Groq |
| **Open Source** | HuggingFace, Together AI, Fireworks, Replicate |
| **Chinese (BIS Entity List)** | Zhipu AI, iFlytek, SenseTime |
| **Chinese (Data Sovereignty)** | DeepSeek, Alibaba Qwen, Baidu ERNIE, Moonshot, MiniMax, Baichuan, Yi |
| **Agentic** | CrewAI, AutoGen, LangGraph, Semantic Kernel |
| **Protocol** | MCP (Model Context Protocol) |
| **Orchestration** | LangChain, LlamaIndex |

## Risk Categories

| Category | Rules | Examples |
|----------|:-----:|---------|
| Data Privacy | 4 | Missing DPA, data classification, prompt retention |
| Model Governance | 8 | No inventory, no versioning, supply chain risk |
| Security | 4 | Hardcoded keys, no input/output validation |
| Transparency | 3 | No AI disclosure, no decision logging |
| Accountability | 3 | No risk owner, no incident response plan |
| Bias & Fairness | 2 | No bias testing, no fairness evaluation |
| Export Compliance | 4 | BIS Entity List, data sovereignty, EU AI Act |
| Agentic AI | 5 | No HITL, no access controls, no observability |

## Compliance Frameworks

| Framework | Controls | Coverage |
|-----------|:--------:|----------|
| **NIST AI RMF** | 23 | GOVERN, MAP, MEASURE, MANAGE functions |
| **ISO 42001** | 15 | AI management system requirements |
| **EU AI Act** | 10 | Articles 5-52, high-risk classification |

## How It Works

```
Your Codebase
     │
     ▼
┌─────────────┐     ┌──────────────┐     ┌─────────────┐     ┌────────────────┐
│ File Walker  │────▶│  AI SDK      │────▶│ Risk Engine │────▶│ Control Mapper │
│ git ls-files │     │  Detector    │     │ 34 rules    │     │ 48 controls    │
│ os.walk      │     │  70 patterns │     │ 8 categories│     │ 3 frameworks   │
└─────────────┘     └──────────────┘     └─────────────┘     └────────────────┘
                           │                    │                     │
                    Detections +          Risk findings         Gap analysis
                    model names +         with severity         NIST / ISO /
                    dependencies          qualification         EU AI Act
                                                                     │
                                                                     ▼
                                                              Table / JSON / SARIF
```

## Why This Exists

We scanned 5 popular open-source AI repos (470K combined GitHub stars):

- **389** AI SDK detections
- **116** compliance findings
- **0** governance controls fully mapped

One enterprise security company had a **BIS Entity-Listed Chinese AI provider** inherited silently through an acquisition.

EU AI Act enforcement starts **August 2026**. If you don't know what AI SDKs are in your codebase, you can't govern them.

## Contributing

Contributions welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

- **Add detection patterns** — new AI providers, SDKs, or frameworks
- **Improve risk rules** — better severity calibration, new categories
- **New output formats** — CycloneDX, SPDX, HTML reports
- **Language support** — Go, Rust, Java detection improvements

## License

Apache-2.0. See [LICENSE](LICENSE).

---

<p align="center">
  Built by <a href="https://saasvista.io">SaaSVista</a> — AI Risk & Compliance Copilot
</p>
