model-integrity-cli 0.1.0

AI Model Runtime Integrity Checker — pre/post system state checksums

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

pip install model-integrity-cli

Or from source:

cd sentinel
pip install -e .

Usage

Wrap a model execution

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

sentinel snapshot --label "clean_state"

Compare two existing snapshots

sentinel diff pre.json post.json

List saved snapshots

sentinel list

Quick system status

sentinel status

Manage allowlist (paths you've verified as safe)

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

{
  "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)

# 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:

# 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:

# 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:

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