Metadata-Version: 2.4
Name: aisbom-cli
Version: 0.1.8
Summary: An AI Supply Chain security tool that that detects Pickle bombs and generates CycloneDX SBOMs for Machine Learning models.
Author: Ajoy L
Author-email: lab700xdev@gmail.com
Requires-Python: >=3.11,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: click (<8.2.0)
Requires-Dist: cyclonedx-python-lib (>=8.5.0,<9.0.0)
Requires-Dist: pip-requirements-parser (>=32.0.1,<33.0.0)
Requires-Dist: rich (>=13.7.1,<14.0.0)
Requires-Dist: typer[all] (>=0.12.5,<0.13.0)
Project-URL: Homepage, https://www.aisbom.io/
Project-URL: Repository, https://github.com/Lab700xOrg/aisbom
Description-Content-Type: text/markdown

# AIsbom: The Supply Chain for Artificial Intelligence
[![PyPI version](https://badge.fury.io/py/aisbom-cli.svg)](https://badge.fury.io/py/aisbom-cli)
![License](https://img.shields.io/badge/license-Apache%202.0-blue)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![Compliance](https://img.shields.io/badge/standard-CycloneDX-green)

**AIsbom** is a specialized security and compliance scanner for Machine Learning artifacts. 

Unlike generic SBOM tools that only parse `requirements.txt`, AIsbom performs **Deep Binary Introspection** on model files (`.pt`, `.pkl`, `.safetensors`) to detect malware risks and legal license violations hidden inside the serialized weights.

---

## ⚡ Quick Start

### 1. Installation
Install directly from PyPI. No cloning required.

```bash
pip install aisbom-cli
```

_Note: The package name is aisbom-cli, but the command you run is aisbom._

### 2. Run a Scan
Point it at any directory containing your ML project. It will find requirements files AND binary model artifacts.

```bash
aisbom scan ./my-project-folder
```

### 3. Output
You will see a combined Security & Legal risk assessment in your terminal:

🧠 AI Model Artifacts Found                           

| Filename | Framework | Security Risk | Legal Risk |
| :--- | :--- | :--- | :--- |
| `bert_finetune.pt` | PyTorch | 🔴 **CRITICAL** (RCE Detected: posix.system) | UNKNOWN |
| `safe_model.safetensors` | SafeTensors | 🟢 **LOW** (Binary Safe) | UNKNOWN |
| `restricted_model.safetensors` | SafeTensors | 🟢 **LOW** | LEGAL RISK (cc-by-nc-4.0)  |

A compliant `sbom.json` (CycloneDX v1.6) including SHA256 hashes and license data will be generated in your current directory.

---

### 4. Visualize the Report (New!)
Don't like reading JSON? You can visualize your security posture using our **offline** viewer.

1.  Run the scan.
2.  Go to [aisbom.io/viewer.html](https://aisbom.io/viewer.html).
3.  Drag and drop your `sbom.json`.
4.  Get an instant dashboard of risks, license issues, and compliance stats.

*Note: The viewer is client-side only. Your SBOM data never leaves your browser.*

---

## 🚀 Why AIsbom?
AI models are not just text files; they are executable programs and IP assets.
*   **The Security Risk:** PyTorch (`.pt`) files are Zip archives containing Pickle bytecode. A malicious model can execute arbitrary code (RCE) instantly when loaded.
*   **The Legal Risk:** A developer might download a "Non-Commercial" model (CC-BY-NC) and deploy it to production. Since the license is hidden inside the binary header, standard tools miss it.
*   **Pickle** files can execute arbitrary code (RCE) instantly upon loading.
*   **The Solution:** Legacy scanners look at requirements.txt manifest files but ignore binary model weights. **We look inside.** We decompile the bytecode headers without loading the heavy weights into RAM.

## ✨ Key Features
*   **🧠 Deep Introspection:** Peeks inside PyTorch Zip structures and Safetensors headers without loading weights into RAM.
*   **💣 Pickle Bomb Detector:** Disassembles bytecode to detect `os.system`, `subprocess`, and `eval` calls before they run.
*   **⚖️ License Radar:** Extracts metadata from .safetensors to flag restrictive licenses (e.g., CC-BY-NC, AGPL) that threaten commercial use.
*   **🛡️ Compliance Ready:** Generates standard [CycloneDX v1.6](https://cyclonedx.org/) JSON for enterprise integration (Dependency-Track, ServiceNow).
*   **⚡ Blazing Fast:** Scans GB-sized models in milliseconds by reading headers only and using streaming hash calculation.

---

## 🧪 How to Verify (The "Trust Factor")

Security tools require trust. To maintain a safe repository, we do not distribute malicious binaries. However, you can verify our detection engine works by generating test artifacts locally using our provided scripts.

**Prerequisites:** You will need to clone the repository to access the generator scripts.

**1. Clone the repo:**
```bash
git clone https://github.com/Lab700xOrg/aisbom.git
cd aisbom
```
**2. Generate Test Artifacts:**
We provide a transparent Python script that uses standard libraries to create "fake" threats for testing.
```bash
# Generate a Pickle Bomb (Security Risk)
python demo_data/generate_malware.py

# Generate a Non-Commercial Model (Legal Risk)
python demo_data/generate_restricted_model.py
```
__Result: A file named malicious_model.pt is created.__

**3. Scan it:**
```bash
# You can use your globally installed aisbom, or poetry run aisbom
aisbom scan demo_data
```
_You will see the scanner flag malicious_model.pt as **CRITICAL** and restricted_model.safetensors as a **LEGAL RISK**._

---

## 🔒 Security Logic
AIsbom uses a static analysis engine to disassemble Python Pickle opcodes. It looks for specific `GLOBAL` and `STACK_GLOBAL` instructions that reference dangerous modules:

* os / posix (System calls)
* subprocess (Shell execution)
* builtins.eval / exec (Dynamic code execution)
* socket (Network reverse shells)

---

## 🤖 GitHub Actions Integration
Add AIsbom to your CI/CD pipeline to block unsafe models before they merge.

```Yaml
name: AI Security Scan
on: [pull_request]

jobs:
  aisbom-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Scan AI Models
        uses: Lab700xOrg/aisbom@v0
        with:
          directory: '.'
