Metadata-Version: 2.4
Name: ai-scrm
Version: 1.0.0
Summary: AI Supply Chain Risk Management - Auto-discovery, signing, and continuous validation for AI systems
Author: Shawn Kahalewai Reilly
Maintainer: Shawn Kahalewai Reilly
License: Apache-2.0
Project-URL: Homepage, https://github.com/kahalewai/ai-scrm
Project-URL: Documentation, https://github.com/kahalewai/ai-scrm/python
Project-URL: Repository, https://github.com/kahalewai/ai-scrm
Project-URL: Issues, https://github.com/kahalewai/ai-scrm/issues
Keywords: ai,security,supply-chain,sbom,abom,cyclonedx,machine-learning,llm,provenance,integrity,ai-scs
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: crypto
Requires-Dist: cryptography>=41.0.0; extra == "crypto"
Provides-Extra: schema
Requires-Dist: jsonschema>=4.0.0; extra == "schema"
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == "yaml"
Provides-Extra: all
Requires-Dist: cryptography>=41.0.0; extra == "all"
Requires-Dist: jsonschema>=4.0.0; extra == "all"
Requires-Dist: pyyaml>=6.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

<div align="center">

# AI-SCRM

**AI Supply Chain Risk Management for Secure AI Infrastructure**

![ai-scrm](https://img.shields.io/badge/AI--SCS-v0.1-blue) ![python](https://img.shields.io/badge/python-3.9+-green) ![license](https://img.shields.io/badge/license-Apache%202.0-orange) ![tests](https://img.shields.io/badge/tests-146%20passing-brightgreen)

Version 1.0.0

</div>

<br>

## Intro

AI-SCRM is the reference implementation of the AI-SCS (AI Supply Chain Security) standard for securing AI infrastructure. It provides production-ready tools to document, sign, and validate AI system components—protecting against model backdooring, dataset poisoning, unauthorized tool activation, and supply chain attacks.

AI-SCRM is intended to:
* **Auto-discover** models, MCP servers, libraries, and prompts with one command
* **Infer metadata** for 100+ common model families automatically
* **Sign and verify** AI artifacts with Ed25519/RSA/ECDSA
* **Continuously monitor** for drift with configurable intervals
* **Integrate easily** with LangChain, FastAPI, and CI/CD pipelines
* Provide clear, actionable error messages
* Support production deployments with SIEM integration

<br>

## Quick Start: One Command Setup

```bash
# Install with all features
pip install ai-scrm[all]

# Initialize everything (scan + template + keys + sign)
ai-scrm init

# View status
ai-scrm status

# Start continuous monitoring
ai-scrm monitor
```

That's it. In under 2 minutes, AI-SCRM will:

1. 🔍 **Scan** for models, MCP servers, libraries, and prompts
2. 🧠 **Infer** suppliers for known models (Llama, Mistral, GPT, etc.)
3. 📋 **Generate** a metadata template for items needing review
4. 🔑 **Create** signing keys and sign your ABOM
5. 📊 **Start** monitoring for drift

<br>

## How AI-SCRM Works

Implementing AI supply chain security requires that your AI system becomes inventory-aware AND your runtime environment validates against the declared inventory. AI-SCRM automates both. Each Control Domain enforces the same core requirement:

<br>

> An AI system may only execute components that are declared in its ABOM, cryptographically verified, and continuously validated at runtime.

<br>

**The AI-SCRM Workflow**

```
┌─────────────────────────────────────────────────────────────────┐
│                    AI-SCRM Workflow                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [1] SCAN (Automatic)                                           │
│      └── Discovers models, MCP, libraries, prompts              │
│                                                                 │
│  [2] ENRICH (Review ~5 min)                                     │
│      └── Fill in TODOs for unknown suppliers                    │
│                                                                 │
│  [3] SIGN (Automatic)                                           │
│      └── Cryptographically sign the ABOM                        │
│                                                                 │
│  [4] MONITOR (Continuous)                                       │
│      ├── Hash checks (every 60s)                                │
│      ├── MCP heartbeat (every 5 min)                            │
│      ├── Full re-scan (every 30 min)                            │
│      └── On drift → RADE event → SIEM                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

Access is permitted only when artifacts are declared, signed, and verified.

<br>

**Key Characteristics**

| Aspect              | Scope                                    |
| ------------------- | ---------------------------------------- |
| Asset coverage      | Models, data, tools, MCP, agents, infra  |
| Inventory format    | CycloneDX 1.6 + AI-SCS extensions        |
| Integrity           | SHA-256 cryptographic hashes             |
| Authenticity        | Ed25519, RSA-PSS, ECDSA-P256 signatures  |
| Validation          | Continuous runtime drift detection       |
| Integration         | SIEM, SOAR, policy engines               |

<br>

## Installation

```bash
# Basic installation
pip install ai-scrm

# With all features (signing, CLI, YAML support)
pip install ai-scrm[all]
```

<br>

## Auto-Discovery

AI-SCRM automatically finds your AI components:

| Component | How It's Discovered |
|-----------|---------------------|
| **Models** | Scans directories for `.safetensors`, `.gguf`, `.pt`, `.onnx` files |
| **MCP Servers** | Parses Claude Desktop config, `mcp.json`, environment variables |
| **Libraries** | Reads `pip list`, `requirements.txt`, `pyproject.toml` |
| **Prompts** | Finds `*.prompt`, `system_prompt*`, `*.jinja2` files |

<br>

**Smart Metadata Inference**

AI-SCRM recognizes 100+ model families and automatically fills in:

```python
# Automatically inferred from filename:
"llama-3-8b-instruct.safetensors" → supplier: Meta, type: fine-tuned, params: 8B
"mistral-7b-v0.1.gguf" → supplier: Mistral AI, architecture: mistral
"text-embedding-ada-002.onnx" → supplier: OpenAI, type: embedding
"claude-3-sonnet.bin" → supplier: Anthropic, family: Claude 3
```

<br>

**Trust Boundary Classification**

MCP servers are automatically classified based on endpoint:

| Pattern | Trust Boundary |
|---------|----------------|
| `localhost:*` | internal |
| `127.0.0.1:*` | internal |
| `192.168.*`, `10.*` | internal |
| `stdio://` | internal |
| Everything else | external |

Override with patterns in `ai-scrm-metadata.yaml`:
```yaml
trust_boundaries:
  "*.internal.mycompany.com": internal
  "*": external
```

<br>

## Continuous Monitoring

AI-SCRM monitors with three tiers:

| Tier | Default Interval | What It Checks |
|------|------------------|----------------|
| **Hash Check** | 60 seconds | File integrity of known components |
| **MCP Heartbeat** | 5 minutes | MCP server availability |
| **Full Scan** | 30 minutes | Discover new/removed components |

```python
from ai_scrm import Monitor

monitor = Monitor(
    abom_path="abom-signed.json",
    hash_check_interval=30,      # Faster checks
    mcp_heartbeat_interval=120,
    on_drift=lambda e: alert(e)  # Custom handler
)
monitor.start()
```

<br>

## Basic Usage

```python
from ai_scrm import ABOMBuilder, ABOM, Signer, Verifier, DriftDetector

# 1. Build ABOM with your AI components
builder = ABOMBuilder()
builder.add_model(
    name="llama-3-8b",
    version="1.0.0",
    hash_value="a1b2c3d4e5f6...",
    format="safetensors",
    supplier="Meta"
)
builder.add_mcp_server(
    name="filesystem-mcp",
    version="1.0.0",
    endpoint="http://localhost:3000",
    trust_boundary="internal",
    capabilities=["read_file", "write_file"]
)
abom = builder.finalize(system_name="my-ai-assistant")

# 2. Sign the ABOM
signer = Signer.generate("ed25519")
signer.sign(abom)
abom.to_file("abom-signed.json")

# 3. Verify at runtime
abom = ABOM.from_file("abom-signed.json")
verifier = Verifier(reject_unsigned=True)
verifier.verify(abom)

# 4. Detect drift
detector = DriftDetector(abom)
event = detector.check_tool_authorized("filesystem-mcp")
if event.is_compliant():
    print("✓ Tool authorized")
```

For complete setup instructions, see the [Implementation Guide](./AI-SCRM-Implementation-Guide.md).

<br>

## Framework Integrations

**Decorator Guard**

```python
from ai_scrm import guard

@guard(tool="web-search")
def search_web(query):
    return search_api.search(query)  # Only runs if authorized
```

**LangChain**

```python
from ai_scrm import langchain_guard

agent = create_react_agent(llm, tools, prompt)
secure_agent = langchain_guard(agent, abom_path="abom.json")
```

**FastAPI Middleware**

```python
from ai_scrm import FastAPIMiddleware

app.add_middleware(FastAPIMiddleware, abom_path="abom.json")
```

**Emergency Bypass**

```python
from ai_scrm import emergency_bypass

with emergency_bypass(reason="Production incident #1234"):
    # All checks disabled, but fully logged
    do_emergency_fix()
```

<br>

## Package Structure

```
ai_scrm/
├── __init__.py              # Main exports
├── abom/                    # Control Domain 1: ABOM
│   ├── models.py            # ABOM, Component, Hash, Property
│   ├── builder.py           # Fluent builder for all asset types
│   └── exceptions.py        # ABOM-specific exceptions
├── trust/                   # Control Domain 2: Trust
│   ├── signing.py           # Ed25519, RSA, ECDSA signers
│   ├── verification.py      # Signature verification
│   └── assertion.py         # Trust assertions (AI-SCS 6.3)
├── validation/              # Control Domain 3: Validation
│   ├── detector.py          # Drift detection
│   ├── events.py            # RADE events (attestation, drift, violation)
│   └── emitter.py           # SIEM/SOAR integration
├── scanner/                 # Auto-Discovery
│   ├── scanner.py           # Main scanner
│   ├── inference.py         # Model metadata inference (100+ models)
│   ├── mcp_discovery.py     # MCP server discovery
│   └── metadata.py          # YAML metadata handling
├── monitor/                 # Continuous Validation
│   └── monitor.py           # Tiered monitoring (hash/heartbeat/scan)
├── integrations/            # Framework Shortcuts
│   └── integrations.py      # guard, langchain_guard, FastAPI
└── cli/                     # Command-Line Interface
    └── __init__.py          # init, scan, status, monitor, etc.
```

<br>

## Three Control Domains

AI-SCRM implements all three AI-SCS Control Domains:

| Domain | Purpose | Key Features |
|--------|---------|--------------|
| **CD1: ABOM** | Inventory & Provenance | All 7 asset categories, mandatory fields, CycloneDX 1.6 |
| **CD2: Trust** | Integrity & Authenticity | Signing, verification, trust assertions |
| **CD3: Validation** | Continuous Assurance | Drift detection, events, enforcement |

```python
# Control Domain 1: ABOM
from ai_scrm import ABOMBuilder
builder = ABOMBuilder()
builder.add_model(...)
builder.add_mcp_server(...)
abom = builder.finalize()

# Control Domain 2: Trust
from ai_scrm import Signer, Verifier
signer = Signer.generate("ed25519")
signer.sign(abom)

# Control Domain 3: Validation
from ai_scrm import DriftDetector, RADEEmitter
detector = DriftDetector(abom)
emitter = RADEEmitter()
emitter.add_file_handler("events.jsonl")
```

<br>

## Supported Asset Categories (AI-SCS 4.1)

AI-SCRM supports all seven AI-SCS asset categories:

| Category | Examples | Builder Methods |
|----------|----------|-----------------|
| **Models** | Base models, fine-tuned, adapters | `add_model()`, `add_fine_tuned_model()`, `add_adapter()` |
| **Data** | Training, evaluation datasets | `add_dataset()`, `add_training_data()` |
| **Embeddings** | Embedding models, vector stores | `add_embedding_model()`, `add_vector_store()` |
| **Dependencies** | Frameworks, tokenizers, libraries | `add_library()`, `add_framework()`, `add_tokenizer()` |
| **Agents** | Orchestrators, planners | `add_agent()`, `add_planner()`, `add_orchestrator()` |
| **Tools** | Plugins, MCP servers, APIs | `add_tool()`, `add_mcp_server()`, `add_external_api()` |
| **Infrastructure** | TEEs, accelerators | `add_infrastructure()`, `add_tee()`, `add_accelerator()` |

Plus behavioral artifacts: `add_prompt_template()`, `add_policy()`, `add_guardrail()`

<br>

## MCP Server Security

AI-SCRM provides specific support for Model Context Protocol (MCP) servers:

```python
# MCP servers have mandatory fields per AI-SCS 5.3.5
builder.add_mcp_server(
    name="filesystem-mcp",
    version="1.0.0",
    endpoint="http://localhost:3000",      # REQUIRED
    trust_boundary="internal",              # REQUIRED: internal, external, hybrid
    capabilities=["read", "write", "list"]  # REQUIRED
)

# Runtime validation before connecting
detector = DriftDetector(abom)
event = detector.check_mcp_authorized("filesystem-mcp", endpoint="http://localhost:3000")
if not event.is_compliant():
    raise SecurityError(f"Unauthorized MCP: {event.observation.details}")
```

<br>

| MCP Authorized | Endpoint Matches | Result |
| -------------- | ---------------- | ------ |
| ✅             | ✅               | ALLOW  |
| ❌             | ✅               | DENY   |
| ✅             | ❌               | DENY   |
| ❌             | ❌               | DENY   |

<br>

## Clear Error Messages

AI-SCRM provides actionable errors:

```
Signature validation failed for abom.json

The ABOM file has been modified since it was signed.
This could mean:
  • Someone tampered with the file (security incident)
  • You made legitimate changes and forgot to re-sign

To fix:
  • If changes were intentional: ai-scrm sign abom.json
  • If unexpected: Investigate first - this may be a security incident
```

<br>

## Diff-Based Approval

When drift is detected:

```bash
$ ai-scrm status

⚠️  2 changes detected:

[NEW] MCP Server: slack-notifications-mcp
      Endpoint: http://localhost:3005
      Action: ai-scrm approve slack-notifications-mcp

[CHANGED] Model: llama-3-8b.safetensors
      Hash: a1b2c3... → x7y8z9...
      Action: ai-scrm approve model:llama-3-8b
```

<br>

## SIEM/SOAR Integration

AI-SCRM emits structured RADE (Runtime Attestation & Drift Events) for security integration:

```python
from ai_scrm import RADEEmitter, DriftDetector

# Create emitter with handlers
emitter = RADEEmitter(system_name="my-ai-assistant")
emitter.add_file_handler("./logs/rade-events.jsonl")
emitter.add_webhook_handler("https://siem.company.com/api/events")

# Emit events from validation
detector = DriftDetector(abom)
events = detector.check("./deployed-system")
emitter.emit_all(events)

# Events are SIEM-compatible JSON
# {
#   "eventType": "drift",
#   "severity": "critical",
#   "observation": {"type": "model-substitution", ...},
#   "abomBinding": {"serialNumber": "urn:uuid:..."}
# }
```

<br>

## Conformance Levels (AI-SCS Section 8)

AI-SCRM supports all three AI-SCS conformance levels:

| Level | Name | Requirements | AI-SCRM Support |
|-------|------|--------------|-----------------|
| **Level 1** | Visibility | ABOM generation, static provenance | ✅ `Scanner`, `ABOMBuilder` |
| **Level 2** | Integrity | Artifact signing, verification | ✅ `Signer`, `Verifier` |
| **Level 3** | Continuous Assurance | Runtime validation, automated detection | ✅ `Monitor`, `DriftDetector`, `RADEEmitter` |

<br>

## CLI Reference

```bash
# First-time setup (does everything)
ai-scrm init
ai-scrm init --dir ./my-project --no-sign

# Scanning
ai-scrm scan
ai-scrm scan --dir ./models --output results.json

# Status (with live updates)
ai-scrm status
ai-scrm status --watch

# ABOM management
ai-scrm abom validate abom.json --strict
ai-scrm abom info abom.json

# Trust operations
ai-scrm trust keygen --algorithm ed25519
ai-scrm trust sign abom.json --key ./keys/private.pem
ai-scrm trust verify abom-signed.json

# Validation
ai-scrm validation check --abom abom.json
ai-scrm monitor --hash-interval 30

# Change management
ai-scrm approve mcp:new-server --trust internal
ai-scrm reject mcp:suspicious-server
```

<br>

## Works with Your Existing Security Infrastructure

AI-SCRM was designed to work with your existing security tools:

* Uses CycloneDX 1.6, a standard SBOM format
* Emits SIEM-compatible structured events
* Integrates with policy engines via callbacks
* Supports existing key management (HSM, cloud KMS)
* Works with CI/CD pipelines (GitHub Actions, GitLab)
* Compatible with Kubernetes admission controllers

<br>

| Component Declared | Signature Valid | Hash Matches | Result |
| ------------------ | --------------- | ------------ | ------ |
| ✅                 | ✅              | ✅           | ALLOW  |
| ❌                 | ✅              | ✅           | DENY   |
| ✅                 | ❌              | ✅           | DENY   |
| ✅                 | ✅              | ❌           | DENY   |

<br>

## Runtime Validation Scenarios

AI-SCRM supports various validation scenarios:

* **Startup Validation**: Verify all components before system initialization
* **Continuous Monitoring**: Periodic checks for drift with configurable intervals
* **On-Demand Checks**: Validate specific components before use
* **Tool Authorization**: Check tool/MCP permissions before invocation

```python
# Startup validation
events = detector.check("./deployed-system")
if any(e.event_type == "drift" for e in events):
    raise SecurityError("System integrity compromised")

# Tool authorization before use
if detector.check_tool_authorized("web-search").is_compliant():
    result = web_search_tool.execute(query)
```

See the [Implementation Guide](./AI-SCRM-Implementation-Guide.md#7-control-domain-3-runtime-validation) for complete validation setup.

<br>

## Documentation

* **[Implementation Guide](./ImplementationGuide.md)** - Complete setup with all Control Domains
* **CI/CD Integration** - GitHub Actions, GitLab CI examples in guide
* **Kubernetes** - Admission controller example in guide

<br>

## Version History

| Version | Changes |
|---------|---------|
| 1.0.0 | Full release: Auto-discovery, smart inference, continuous monitoring, framework integrations, Ed25519/RSA/ECDSA signing, RADE events |

<br>

## License

Apache License 2.0

<br>
<br>
