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

Eresus Security · eresussec.com

Name		Name	Last commit message	Last commit date
Latest commit History 140 Commits
.agents/skills		.agents/skills
.github		.github
action		action
ci		ci
config		config
demos		demos
docs		docs
examples		examples
frontend		frontend
notebooks		notebooks
packaging		packaging
payloads		payloads
playbooks		playbooks
python/sentinel		python/sentinel
rules		rules
rust		rust
scripts		scripts
tests		tests
tools/sntl		tools/sntl
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.pre-commit-hooks.yaml		.pre-commit-hooks.yaml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
Dockerfile.cuda		Dockerfile.cuda
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
THIRD_PARTY_NOTICES.md		THIRD_PARTY_NOTICES.md
action.yml		action.yml
alembic.ini		alembic.ini
demo.gif		demo.gif
docker-compose.yml		docker-compose.yml
mkdocs.yml		mkdocs.yml
pyproject.toml		pyproject.toml
sentinel.toml		sentinel.toml
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Eresus Sentinel

What It Detects

Supported Formats

Security Domains

Domain Maturity

Quick Start

Architecture

Key Design Principles

CLI Commands

Python SDK

Config-Driven Eval

MCP Live Scanner

Runtime Gateway

REST API

MCP Proxy

Configuration

Docker

CI/CD Integration

GitHub Actions

Documentation

Authentication & Security

Requirements

Alpha Disclaimer

Community

License

About

Uh oh!

Releases 1

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Eresus Sentinel

What It Detects

Supported Formats

Security Domains

Domain Maturity

Quick Start

Architecture

Key Design Principles

CLI Commands

Python SDK

Config-Driven Eval

MCP Live Scanner

Runtime Gateway

REST API

MCP Proxy

Configuration

Docker

CI/CD Integration

GitHub Actions

Documentation

Authentication & Security

Requirements

Alpha Disclaimer

Community

License

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages