Metadata-Version: 2.4
Name: model-integrity-cli
Version: 0.1.0
Summary: AI Model Runtime Integrity Checker — pre/post system state checksums
Project-URL: Homepage, https://github.com/model-integrity-cli/sentinel
Project-URL: Repository, https://github.com/model-integrity-cli/sentinel
Project-URL: Documentation, https://github.com/model-integrity-cli/sentinel#readme
Author: Sentinel Contributors
License: MIT
Keywords: ai,audit,gpg,integrity,monitoring,security
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT 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 :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Sentinel — AI Model Runtime Integrity Checker

**Pre/post system state checksums around AI model execution.**

Did the AI model on your device change anything it shouldn't have? Sentinel snapshots your system state before and after running a model, diffs it, and reports every change with severity classification.

```
sentinel run --model-dir ./models './run-llama.sh'
```

```
======================================================================
  SENTINEL — AI Model Runtime Integrity Report
======================================================================

  Baseline:  run_pre (2026-07-27T12:00:00+00:00)
  Check:     run_post (2026-07-27T12:05:00+00:00)
  Model:     /home/user/models/llama-3

  ✓ PASS — no changes detected

  Severity breakdown:
      0  Critical
      0  Suspicious
      0  Info
      0  Clear

  File summary:
      0 added     0 removed     0 modified     1357 unchanged
  Processes:      1 new         0 ended
  Services:       0 changed
  Cron:           0 changes
======================================================================
```

## Why

On-device AI is everywhere — Apple Intelligence, Windows Copilot, Galaxy AI, local LLMs. But nobody has a tool to answer: *"Did the AI I just ran modify system settings, start new services, install cron jobs, or change firewall rules?"*

Sentinel answers that question by wrapping model execution with cryptographic system state snapshots.

## Installation

```bash
pip install model-integrity-cli
```

Or from source:

```bash
cd sentinel
pip install -e .
```

## Usage

### Wrap a model execution

```bash
sentinel run --model-dir ./models/llama './run-llama.sh'
```

- Takes a pre-execution snapshot
- Runs your command
- Takes a post-execution snapshot
- Diffs them and reports findings

### Take a standalone snapshot

```bash
sentinel snapshot --label "clean_state"
```

### Compare two existing snapshots

```bash
sentinel diff pre.json post.json
```

### List saved snapshots

```bash
sentinel list
```

### Quick system status

```bash
sentinel status
```

### Manage allowlist (paths you've verified as safe)

```bash
sentinel allow --add /etc/some/legitimate/path
sentinel allow --remove /etc/some/path
sentinel allow  # list all
```

## What it monitors

| Category | What | Severity if changed |
|----------|------|-------------------|
| **Critical paths** | `/etc`, `/etc/ssh`, `/etc/systemd`, `/etc/cron*`, `/etc/sudoers.d`, `/etc/iptables`, kernel modules | 🔴 Critical |
| **Suspicious paths** | `/etc/hosts`, `/etc/resolv.conf`, `/etc/environment`, `/etc/profile.d` | 🟡 Suspicious |
| **User config** | `~/.bashrc`, `~/.ssh/authorized_keys`, `~/.config/autostart`, user systemd | 🟡 Suspicious |
| **Model working dir** | Paths declared via `--model-dir` | 🔵 Info |
| **Services** | systemd service state changes | 🟡 Suspicious |
| **Cron** | System cron files, user crontabs | 🔴 Critical / 🟡 Suspicious |
| **Network** | Interfaces, routing, DNS, listening ports, firewall rules | 🔴 Critical |
| **Kernel** | Loaded modules, sysctl values | 🔴 Critical |
| **Processes** | New or ended processes (excluding kernel threads) | 🔵 Info |

## Severity Levels

| Verdict | Meaning | Exit Code |
|---------|---------|-----------|
| **PASS** | No changes, or only allowlisted paths changed | 0 |
| **WARNING** | Suspicious changes detected — review recommended | 1 |
| **FAIL** | Critical changes detected — investigate immediately | 2 |

## Output Formats

- `--format terminal` — colored terminal output (default)
- `--format json` — structured JSON for programmatic use

## JSON Report Example

```json
{
  "report_type": "sentinel_integrity_report",
  "diff": { ... },
  "evaluation": {
    "verdict": "PASS — no changes detected",
    "severity_counts": { "critical": 0, "suspicious": 0, "info": 0, "clear": 0 },
    "findings": []
  }
}
```

## How It Works

1. **Snapshot engine** walks critical system paths, computes SHA-256 hashes, captures process lists, service states, cron jobs, network config, and kernel state
2. **Manifest** serializes the snapshot to JSON and computes a top-level rolling hash for quick integrity checks
3. **Diff engine** compares two manifests at every level — files, processes, services, cron, network, kernel
4. **Policy engine** classifies each change by severity, respecting model working directories and a user-managed allowlist
5. **Report** formats the verdict for terminal or JSON output

## Additional Commands

### Signed Manifests (GPG)

```bash
# Sign a snapshot manifest
sentinel sign manifest.json

# Sign with a specific GPG key
sentinel sign --key ABCDEF1234567890 manifest.json

# Verify a signed manifest
sentinel verify manifest.json
```

Sentinel uses detached GPG armor signatures (`.sig` files alongside manifests). The signature info is also embedded in the manifest metadata.

### Incident Log (Audit Trail)

Every `sentinel run` is automatically logged to the incident audit trail:

```bash
# List recent incidents
sentinel incidents list

# Show summary statistics
sentinel incidents stats

# Export full log
sentinel incidents export --format json
```

The incident log is stored at `~/.sentinel/incidents.jsonl` (JSON Lines format, one record per line).

### Daemon Mode (Background Monitoring)

Run Sentinel as a background daemon for periodic drift detection:

```bash
# Initialize baseline and configure
sentinel daemon init --interval 3600

# Start monitoring
sentinel daemon start

# Check status
sentinel daemon status

# Stop the daemon
sentinel daemon stop
```

The daemon takes snapshots at regular intervals, compares them to the baseline, and logs any drift as incidents. It can also run an external notification command on alert.

### GUI Dashboard (Web UI)

Launch a local web dashboard to visualize all Sentinel data:

```bash
sentinel dashboard
# Opens at http://127.0.0.1:8099
```

The dashboard provides:
- **Overview** — incident counts, snapshot totals, daemon status
- **Incidents** — full incident history with severity breakdowns
- **Snapshots** — snapshot browser with file counts and manifest hashes

Zero dependencies — built on Python's built-in HTTP server.

## Integration Ideas

- **CI/CD pipeline** — wrap model deployments in Sentinel to detect supply-chain attacks
- **Pre/post hook** — integrate with llama.cpp, Ollama, vLLM, or any local model runner
- **GPG signing** — pair with model publisher signatures for supply-chain verification
- **Slack/Discord alerts** — point `daemon init --notify` at a webhook script

## Project Structure

```
sentinel/
├── src/sentinel/
│   ├── __init__.py
│   ├── __main__.py
│   ├── cli.py           # CLI (11 subcommands)
│   ├── snapshot.py      # System state snapshot engine
│   ├── manifest.py      # Manifest serialization
│   ├── diff.py          # Snapshot comparison engine
│   ├── policy.py        # Policy evaluation & allowlist
│   ├── report.py        # Terminal & JSON output
│   ├── signing.py       # GPG signature sign/verify
│   ├── incident.py      # Incident audit trail (JSONL)
│   ├── daemon.py        # Background monitoring daemon
│   ├── dashboard.py     # Web-based GUI dashboard
│   ├── dashboard_static/ # Dashboard CSS & JS
│   │   ├── styles.css
│   │   └── app.js
│   └── defaults.py      # Default paths & config
├── tests/
│   ├── test_snapshot.py
│   ├── test_diff.py
│   ├── test_policy.py
│   ├── test_cli.py
│   ├── test_incident.py
│   └── test_signing.py
├── pyproject.toml
└── README.md
```

## License

MIT
