AICerberus 🐺

AI supply chain security scanner — one command to scan all AI/ML dependencies and model files for CVEs, pickle exploits, and license risks.

🌐 中文文档

---

What is AICerberus?

AICerberus is the "Trivy for AI supply chains" — a CLI tool that scans your project for security risks that existing SCA tools (Snyk, Trivy, Grype) completely miss:

Risk Category	Traditional SCA	AICerberus
PyPI CVE scanning	✅	✅
Pickle deserialization attacks	❌	✅
PyTorch model file analysis	❌	✅
AI-specific licenses (OpenRAIL, Llama)	❌	✅
HuggingFace model card risks	❌	✅
CycloneDX AI SBOM generation	❌	✅

---

Quick Start

pip install git+https://github.com/hidearmoon/aicerberus.git
cerberus scan .

That's it. AICerberus will scan your current directory and report all findings.

PyPI package coming soon. Once published, pip install aicerberus will work directly.

---

Features

• 🔍 Dependency CVE Scanning — Queries the OSV database for known vulnerabilities in 50+ AI/ML packages (PyTorch, TensorFlow, LangChain, Transformers, etc.)
• ☣️ Model File Analysis — Safely disassembles pickle opcodes (without executing them) to detect malicious payloads like os.system, subprocess.Popen, eval/exec
• 📜 License Compliance — Detects restrictive AI licenses: OpenRAIL variants, Llama 2/3, Gemma (commercial prohibitions), CC-BY-NC (non-commercial), AGPL/GPL (copyleft)
• 📦 AI SBOM Generation — Outputs a CycloneDX v1.5 SBOM with all AI components, CVE cross-references, and model file hashes
• 🚀 Fast & Local — No data leaves your machine (except OSV/HuggingFace API queries for vulnerability lookups)

---

Installation

# Install directly from GitHub (recommended until PyPI release)
pip install git+https://github.com/hidearmoon/aicerberus.git

# From source (for development)
git clone https://github.com/hidearmoon/aicerberus
cd aicerberus
pip install -e .

---

Usage

Basic scan

cerberus scan /path/to/your/project

Filter by severity

cerberus scan . --severity high

Show remediation recommendations

cerberus scan . --fix

Export as JSON

cerberus scan . --format json --output report.json

Generate AI SBOM (CycloneDX)

cerberus scan . --format sbom --output sbom.json

Skip specific scanners

cerberus scan . --skip-deps --skip-licenses   # model files only

With HuggingFace token (for private model cards)

cerberus scan . --hf-token $HF_TOKEN
# or set env var: export HF_TOKEN=hf_...

Air-gapped / offline environments

cerberus scan . --no-hf-api   # skip all HuggingFace API calls

---

Output Example

╭─────────────────────────────────────────╮
│  AICerberus v0.1.0  AI Supply Chain...  │
╰─────────────────────────────────────────╯

  AI/ML Dependency Vulnerabilities
  ┌─────────────┬─────────┬──────────────┬──────────┬──────┬─────────────────────┐
  │ Package     │ Version │ CVE          │ Severity │ CVSS │ Summary             │
  ├─────────────┼─────────┼──────────────┼──────────┼──────┼─────────────────────┤
  │ torch       │ 1.9.0   │ CVE-2022-... │ 🔴 HIGH  │ 7.8  │ Arbitrary code ...  │
  └─────────────┴─────────┴──────────────┴──────────┴──────┴─────────────────────┘

  Model File Risks
  ┌─────────────┬────────┬──────────────────┬─────────────────────┐
  │ File        │ Format │ Severity         │ Risk                │
  ├─────────────┼────────┼──────────────────┼─────────────────────┤
  │ model.pkl   │ pickle │ 🔴 CRITICAL      │ MALICIOUS_PAYLOAD   │
  │             │        │ ⚠ Dangerous:     │ GLOBAL:os system    │
  └─────────────┴────────┴──────────────────┴─────────────────────┘

╭─ AICerberus v0.1.0 — Scan Summary ──────────╮
│  🔴 Overall severity: CRITICAL               │
│  CVEs found:           2                     │
│  Model file risks:     1                     │
│  License issues:       1                     │
╰──────────────────────────────────────────────╯

---

Supported File Formats

Format	Extension	Analysis
Pickle	.pkl, .pickle	Full opcode disassembly
PyTorch	.pt, .pth, .bin	ZIP extraction + pickle analysis
Joblib	.joblib	Unsafe serialization flag
SafeTensors	.safetensors	Safe format (low risk)
ONNX	.onnx	Safe format (low risk)
HDF5	.h5, .hdf5	Structural risk flag
TensorFlow SavedModel	.pb	Structural risk flag

---

Supported Dependency Files

• requirements.txt / requirements-*.txt
• pyproject.toml (PEP 621 + Poetry)
• Pipfile
• setup.py, setup.cfg

---

Exit Codes

Code	Meaning
0	No risks found
1	One or more risks found
2	Scan error

---

CI Integration

# .github/workflows/ai-security.yml
- name: AI Supply Chain Scan
  run: |
    pip install aicerberus
    cerberus scan . --severity high

---

Why Not Just Use Trivy / Snyk?

Existing SCA tools were designed before the AI/ML era. They:

1. Don't analyze model files — a malicious .pkl file can execute arbitrary code on pickle.load(), but Trivy/Snyk don't scan these
2. Don't understand AI licenses — OpenRAIL, Llama 2 Community License, Gemma Terms all have use restrictions that standard SPDX checks miss
3. Don't cover AI-specific CVEs well — many ML framework CVEs are underreported in NVD/GHSA but present in OSV

AICerberus fills this gap.

---

Contributing

git clone https://github.com/hidearmoon/aicerberus
cd aicerberus
pip install -e ".[dev]"
pytest tests/

PRs welcome! See CONTRIBUTING.md for guidelines.

---

License

Apache 2.0 — see LICENSE

---

Built by OpenForge AI — focused on AI security, observability, and toolchain.