Eresus Sentinel

Alpha-stage, deterministic-first AI security toolkit for local audits, MCP/agent checks, model artifact scanning, and prompt firewall testing.

Sentinel provides deterministic, YAML-driven security scanning across the AI stack — from model artifacts and prompt firewalls to supply chain auditing and red team automation. Zero AI is required to produce findings; AI/judge adapters are optional enrichment layers.

Eresus Sentinel Demo

What It Detects

Serialization RCE — Pickle/joblib/dill GLOBAL opcodes against 300+ blocklisted module.function pairs
Framework code injection — Keras Lambda bytecode, TorchScript code/ backdoor, PMML/Jinja2 SSTI, auto_map RCE
Archive exploits — Zip Slip, path traversal, symlink attacks in ZIP / TAR / 7z / .mar / .nemo
Embedded secrets — 2000+ API key patterns, connection strings, hardcoded tokens in model metadata
Network callbacks — socket/urllib/requests globals in pickle; C2 URLs in GGUF metadata
Supply chain tampering — missing hash integrity, typosquatting, OSV.dev CVE lookup
Prompt / agent injection — instruction injection in model cards, MCP tool description hijacking
Backdoored weights — statistical anomalies, entropy outliers, suspicious weight distributions (heuristic)

Supported Formats

70+ scanners across model, archive, and configuration formats. No model is ever loaded or executed.

Format	Extensions	Risk
Pickle / Joblib	`.pkl` `.pickle` `.p` `.dill` `.dat` `.data` `.joblib`	CRITICAL
PyTorch	`.pt` `.pth` `.bin` `.ckpt`	CRITICAL
TorchScript	`.torchscript` (ZIP)	HIGH
TorchServe	`.mar`	HIGH
Torch7 (Lua)	`.t7` `.th` `.net`	HIGH
NumPy	`.npy` `.npz`	HIGH
Keras	`.keras` `.h5` `.hdf5`	HIGH
TensorFlow	`.pb` `.meta` `saved_model/`	HIGH
Skops	`.skops`	HIGH
R Serialized	`.rds` `.rda` `.rdata`	HIGH
NeMo	`.nemo`	HIGH
CNTK	`.dnn` `.cmf`	HIGH
ONNX	`.onnx`	MEDIUM
JAX / Orbax / Flax	`.jax` `.checkpoint` `.orbax` `.msgpack`	MEDIUM
TFLite	`.tflite`	MEDIUM
ExecuTorch	`.pte` `.ptl`	MEDIUM
TensorRT	`.engine` `.plan` `.trt`	MEDIUM
CoreML	`.mlmodel` `.mlpackage`	MEDIUM
CatBoost / XGBoost / LightGBM	`.cbm` `.bst` `.lgb`	MEDIUM
PaddlePaddle	`.pdmodel` `.pdiparams`	MEDIUM
MXNet	`-symbol.json` `.params`	MEDIUM
SafeTensors	`.safetensors`	LOW
GGUF / GGML	`.gguf` `.ggml` `.ggmf` `.ggjt` `.ggla` `.ggsa`	LOW
OpenVINO / PMML	`.xml` `.pmml`	LOW
Llamafile	`.llamafile`	LOW
ZIP / TAR / 7z	`.zip` `.tar` `.tar.gz` `.7z`	HIGH (traversal)
RAR	`.rar`	Fail-closed
JSON / YAML manifests	`config.json` `*.yaml`	HIGH
Jinja2 templates	`.j2` `.jinja` `.jinja2`	CRITICAL

→ Full format documentation with detection details

Security Domains

Domain	Module	Coverage
🔬 Artifact	`artifact/`	70+ scanners — Pickle, Torch, Keras, ONNX, GGUF, Safetensors, TFLite, Archives
🛡️ Input Firewall	`firewall/input/`	22 guardrails — Injection, secrets, PII, encoding attacks, invisible text, toxicity
🔒 Output Firewall	`firewall/output/`	24 guardrails — Bias, compliance, copyright, watermark, format enforcement
🔍 SAST	`sast/`	Static analysis + 120+ secret patterns + entropy + git history scanning
🤖 Agent/MCP	`agent/`	Trust maps, permissions, MCP schema validation, live MCP discovery
📦 Supply Chain	`supply_chain/`	Dependency scanning, typosquatting, OSV.dev, provenance
⚔️ Red Team / Eval	`redteam/`	48 probes + 13 detectors + 14 generators + YAML playbook/eval engine
🔗 MCP Proxy	`mcp_proxy.py`	Live intercepting proxy (stdio/HTTP) with OPA policy enforcement
🚦 Runtime Gateway	`runtime_gateway.py`	Provider-neutral LLM gateway contract with monitor/enforce modes
📓 Notebook	`notebook_scanner/`	Jupyter security scanning (14 plugins)
📝 Diff	`diff_scanner/`	Git diff/PR ML anti-pattern detection

Domain Maturity

Domain	Maturity
Pickle/artifact no-load scanning	Beta
Prompt firewall deterministic checks	Beta
SAST/secrets/notebook/diff	Beta
MCP manifest/live scanning	Beta
MCP proxy runtime enforcement	Experimental
Dashboard/API	Experimental
HF/supply-chain live integrations	Experimental
Runtime gateway provider adapters	Experimental
AI/judge enrichment	Optional experimental

Quick Start

# Install
pip install -e ".[dev]"

# Verify installation
sentinel doctor
sentinel doctor --json

# Preview the scanner plan, then scan a project
sentinel scan ./my-project --plan --profile fast
sentinel scan ./my-project/

# Firewall a prompt
sentinel firewall "user input text"

# Scan model artifacts
sentinel artifact ./models/

# Red team assessment
sentinel redteam --target openai/gpt-4o

# Config-driven eval
sentinel evaluate eval.yaml

# Live/manifest MCP scan
sentinel mcp scan ./mcp-manifest.json

# Interactive shell
sentinel shell

Architecture

┌──────────────────────────────────────────────────────────────┐
│                    Eresus Sentinel CLI                        │
│               (Python · Click + Rich terminal)               │
├──────────┬──────────┬──────────┬──────────┬──────────────────┤
│ Artifact │ Firewall │   SAST   │ Agent/   │  Supply Chain    │
│ Scanner  │ (I/O)    │ Analyzer │ MCP      │  Auditor         │
├──────────┴──────────┴──────────┴──────────┴──────────────────┤
│                    YAML Rule Engine                           │
│              (rules/ — zero hardcoded regex)                  │
├──────────────────────────────────────────────────────────────┤
│               Finding Universal Data Model                    │
│          (7 domain factories + dedup fingerprints)            │
├──────────────────────────────────────────────────────────────┤
│  MCP Proxy  │  Eval Runner  │  Runtime Gateway  │ Telemetry │
├──────────────────────────────────────────────────────────────┤
│           AI-Assisted Layer (optional, pluggable)             │
│        OpenAI / Anthropic / Local GGUF / Generic REST        │
└──────────────────────────────────────────────────────────────┘

Key Design Principles

Deterministic-first — All scanning is regex/AST/opcode-based. No AI dependency for findings.
YAML-driven rules — All patterns in rules/*.yaml. Zero hardcoded regex in code.
Plugin auto-discovery — Drop a scanner class, it's automatically registered.
Lazy loading — Modules load on-demand for fast CLI startup.
SARIF v2.1.0 output — Native GitHub Security tab integration.

CLI Commands

The most common commands are:

sentinel scan ./project --profile fast -f json
sentinel artifact ./models -f sarif
sentinel firewall "user input text" -f json
sentinel mcp scan ./mcp-manifest.json
git diff main...HEAD | sentinel diff - -f sarif

See docs/CLI_REFERENCE.md for the full command table and docs/CLI_CONTRACT.md for exit codes and output shape.

Python SDK

from sentinel import Sentinel

s = Sentinel()

# Scan input
result = s.scan_input("user prompt here")
print(result.findings)

# Scan output
result = s.scan_output("prompt", "llm response")

# Full conversation scan
result = s.scan_conversation("prompt", "response")

# Export to SARIF
s.export_sarif(result.findings, "report.sarif")

Config-Driven Eval

# eval.yaml
providers:
  - id: local-echo
    name: echo
prompts:
  - id: greeting
    prompt: "hello {{name}}"
tests:
  - id: alice
    vars: { name: Alice }
    assertions:
      - type: contains
        expected: Alice

sentinel evaluate eval.yaml --fail-on-threshold 0.95
sentinel evaluate eval.yaml -f json -o eval-report.json

MCP Live Scanner

Scan offline manifests or live MCP JSON-RPC endpoints:

sentinel mcp scan ./mcp-manifest.json
sentinel mcp scan --url http://localhost:3000/mcp
sentinel mcp scan --stdio-command npx my-mcp-server

The scanner discovers tools, prompts, resources, server instructions, auth metadata, and readiness signals.

Runtime Gateway

from sentinel.runtime_gateway import SentinelGateway, EchoProviderAdapter

gateway = SentinelGateway(provider=EchoProviderAdapter())
decision = gateway.complete("user prompt")
if decision.blocked:
    print(decision.response.text)

REST API

# Start Web UI dashboard
export SENTINEL_PASSWORD=change-me
sentinel dashboard
# Open http://127.0.0.1:8080

# If running from source and the UI is missing:
# Node.js 20.19+ is required by Vite/React Router.
cd frontend && npm install && npm run build

# Start API server
sentinel serve --host 0.0.0.0 --port 8080

# Scan endpoint
curl -X POST http://localhost:8080/scan/input \
  -H "Content-Type: application/json" \
  -d '{"text": "user prompt"}'

MCP Proxy

Intercept and inspect all MCP protocol traffic in real-time:

# Stdio mode — wrap any MCP server
sentinel proxy --transport stdio --mode enforce --server-cmd npx my-mcp-server

# HTTP mode — reverse proxy
sentinel proxy --transport http --mode enforce --upstream http://localhost:3000 --port 8080

Configuration

Engine is configured via sentinel.toml:

[engine]
mode = "deterministic"    # "ai-assisted" | "full"
min_severity = "MEDIUM"
action_policy = "balanced" # "advisory" | "strict"

[scanners.artifact]
enabled = true

[scanners.firewall.input]
enabled = true

[scanners.firewall.output]
enabled = true

[scanners.sast]
enabled = true

[scanners.redteam]
enabled = false  # Opt-in only

[ai]
enabled = false
backend = "ollama"
model = "llama3.2"

Docker

# Standard
docker build -t eresus-sentinel .
docker run -v ./models:/data eresus-sentinel scan /data

# GPU-accelerated (CUDA)
docker build -f Dockerfile.cuda -t eresus-sentinel:cuda .

# Docker Compose (API + worker)
docker compose up

CI/CD Integration

GitHub Actions

- name: Sentinel Security Scan
  run: |
    pip install eresus-sentinel
    sentinel scan ./src --format sarif --output sentinel.sarif

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: sentinel.sarif

Documentation

Full Documentation | Quick Start | Supported Formats | Security Model

Topic	Link
Getting started	Quick Start · Turkish
Format coverage	Supported Formats
Scanner control	Scanner Selection
Threat model	Security Model
Air-gapped deploy	Offline Usage
Python/OS compat	Compatibility Matrix
CLI flags	CLI Reference · CLI Contract
Write rules	Rule Authoring · YAML Rules
Write scanners	Scanner Authoring
CI / pre-commit	CI and Pre-Commit
Reduce noise	False Positive Handling
Ops	MCP Proxy · Troubleshooting · FAQ

Authentication & Security

For production deployments:

# Enable API authentication
export SENTINEL_AUTH_TYPE=bearer
export SENTINEL_AUTH_TOKEN=your-secret-token

# Restrict CORS
export SENTINEL_CORS_ORIGINS=https://yourdomain.com

# Enable audit logging
export SENTINEL_AUDIT_LOG=/var/log/sentinel/audit.jsonl

# Rate limiting (configured via SENTINEL_RATE_LIMIT)
export SENTINEL_RATE_LIMIT=100/minute

See Security Policy for full hardening guide.

Requirements

Python 3.10+
Core dependencies: pyyaml, rich
API server: pip install eresus-sentinel[api] (adds fastapi, uvicorn)
Web dashboard: pip install eresus-sentinel[web]
ML scanning: pip install eresus-sentinel[ml] (adds torch, transformers)
Rust pickle backend: cd rust/sentinel-pickle && maturin develop --release
All extras: pip install eresus-sentinel[all]

Alpha Disclaimer

This is alpha software. APIs, CLI flags, finding schemas, and rule IDs may change between releases without deprecation notice. Do not depend on output stability in production CI pipelines yet.

Community

Community Notes — contribution guidelines and communication channels
Good First Issues — beginner-friendly tasks

License

Eresus Security · eresussec.com

Eresus-sentinel

Links

README