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.

---

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

Proprietary — © 2026 Eresus Security. See LICENSE.

---

Eresus Security · eresussec.com