SENTINEL PRIME Documentation

Installation

git clone git@github.com:RichardBarron27/red-specter-sentinel-prime.git
cd red-specter-sentinel-prime
pip install -e .
sentinel-prime --help

Prerequisites

Dependency	Version	Purpose
Python	≥ 3.11	Core runtime
Ollama	Latest	LLM_REASONER host
deepseek-r1:7b	Latest	Threat reasoning model
RTX 3090	N/A	GPU inference (recommended)
Red Specter AI Shield	≥ v1.0	Alert source (177 modules)

CLI Reference

sentinel-prime start

sentinel-prime start [--daemon] [--config /path/to/config.json]

Start the SENTINEL PRIME platform. Without --daemon, runs in foreground with live alert stream output. With --daemon, backgrounds the process (use with systemd).

sentinel-prime status

sentinel-prime status [--verbose]

Report current platform status: Ollama connectivity, active module connections, gate configuration, M99 escalation count for current session, last correlation event.

sentinel-prime test

sentinel-prime test --chain <chain_name>
sentinel-prime test --chain rag
sentinel-prime test --chain full_kill_chain
sentinel-prime test --all-chains
sentinel-prime test --chain orchestration_takeover --verbose

Simulate an attack chain by injecting synthetic alerts matching the named chain signature. Exercises the full pipeline: ALERT_INGESTOR → CORRELATION_ENGINE → LLM_REASONER → DECISION_ENGINE. Does not trigger real M99 escalation (test mode enforced).

sentinel-prime inject

sentinel-prime inject --module <M_NUMBER> --severity <1-5> --type <alert_type>
sentinel-prime inject --module M99 --severity 5 --type prompt_injection
sentinel-prime inject --module M149 --severity 4 --type orchestrator_backdoor

Manually inject a synthetic alert from a specific AI Shield module. Use for testing correlation logic and gate behaviour without running full AI Shield modules.

sentinel-prime correlate

sentinel-prime correlate --status
sentinel-prime correlate --window 600
sentinel-prime correlate --dump

Query and control the CORRELATION_ENGINE. --status shows current active correlations and pending chain matches. --window overrides the correlation time window for the current session. --dump outputs full correlation state as JSON.

sentinel-prime feed

sentinel-prime feed --tail 20
sentinel-prime feed --since 1h
sentinel-prime feed --chain orchestration_takeover

View WARLORD intelligence feed output. Shows all escalation events, their gate evaluation results, and WARLORD manifest references.

sentinel-prime report

sentinel-prime report --id SP-4a7f3c2e9b1d
sentinel-prime report --last 5
sentinel-prime report --output report.json

Retrieve and display SP-{hex12} signed reports. Includes full LLM reasoning trace, gate evaluation, correlated module list, and M99 escalation outcome.

sentinel-prime gates

sentinel-prime gates --show
sentinel-prime gates --set confidence 0.90
sentinel-prime gates --set sources 4
sentinel-prime gates --set level 5
sentinel-prime gates --reset

Inspect and adjust gate thresholds at runtime. Changes take effect on the next correlation window. Use --reset to restore defaults.

sentinel-prime engage

sentinel-prime engage --alert-file alerts.json --chain auto
sentinel-prime engage --stream --modules M99,M149,M147

Full engagement mode. Ingests alerts from a file or live stream, runs full pipeline, and produces SP report. --chain auto lets the CORRELATION_ENGINE determine the chain; alternatively specify the expected chain for validation.

Component Deep Dive

ALERT_INGESTOR

Supports three ingestion modes:

Mode	Config Key	Description
file	ingestor.source = "file"	Polls a JSON alert file written by AI Shield modules
socket	ingestor.source = "socket"	Unix domain socket for low-latency local delivery
rest	ingestor.source = "rest"	HTTP POST endpoint at /alerts/ingest

The deduplication window defaults to 60 seconds. Duplicate alerts (same module, same alert_type, same severity within the window) are collapsed into a single CorrelationEvent with an occurrence_count field.

CORRELATION_ENGINE

Each of the 8 attack chains has a minimum required module coverage pattern. Example:

# orchestration_takeover requires alerts from at minimum:
#   - M149 (AI Orchestration Guard)  — orchestrator compromise
#   - M147 (Cloud Identity Sentinel) — IAM escalation
#   - one of: M124 (Apex), M150 (Inference Gateway Sentinel)
# All alerts must fall within SP_CORRELATION_WINDOW_SECS (default 300)

If alerts match a chain pattern but the temporal window has not been met, the correlation is held in a pending state and re-evaluated on each new alert arrival.

LLM_REASONER

The LLM_REASONER sends a structured prompt to deepseek-r1:7b containing the full correlated alert context. The model is instructed to return JSON with the following schema:

{
  "threat_class": "orchestration_takeover",
  "confidence": 0.93,
  "attack_chain": "orchestration_takeover",
  "recommended_action": "escalate_m99",
  "reasoning_trace": "..."
}

If the model returns malformed JSON, confidence is treated as 0.0 and Gate 1 fails. If Ollama is unreachable, the full reasoning step is skipped, confidence is set to 0.0, and the M99 cap (SP_FALLBACK_M99_CAP, default 3) is enforced for the session.

DECISION_ENGINE

Gate evaluation order: CONFIDENCE → SOURCES → ESCALATION_LEVEL. All three must pass. A single gate failure blocks M99 escalation but still triggers a WARLORD_FEED event at reduced priority. Gate evaluation results are always included in the SP report.

WARLORD_FEED

WARLORD_FEED fires on every correlation event regardless of gate outcome. Full M99 escalation events are tagged escalation_type: "m99". Gate-blocked events are tagged escalation_type: "warlord_only". The WARLORD registry can be queried for threat intelligence without M99 having fired.

Attack Chain Signatures

Chain	Description	Min Modules	Typical Escalation Level
rag_attack	RAG poisoning + retrieval manipulation	2	3–4
dag_attack	Evidence DAG manipulation + trust propagation	2	3–4
cloud_takeover	Cloud IAM escalation + credential exfil	3	4–5
rootkit_chain	Kernel/eBPF injection + persistence	2	4–5
orchestration_takeover	Multi-agent orchestrator compromise + lateral movement	3	4–5
data_annihilation	Training data + knowledge infrastructure destruction	3	5
adversarial_escalation	Adversarial input + guardrail bypass + model inversion	2	3–4
full_kill_chain	Complete NIGHTFALL-class operation in progress	5	5

Environment Variables

Variable	Default	Description
SP_CONFIDENCE_THRESHOLD	0.85	Gate 1: minimum LLM confidence for M99 escalation
SP_MIN_SOURCES	3	Gate 2: minimum distinct modules correlated
SP_MIN_ESCALATION_LEVEL	4	Gate 3: minimum escalation level (1–5)
SP_FALLBACK_M99_CAP	3	Max M99 escalations when LLM unavailable
SP_DEDUP_WINDOW_SECS	60	Alert deduplication window (seconds)
SP_CORRELATION_WINDOW_SECS	300	Attack chain temporal correlation window (seconds)
SP_OLLAMA_HOST	http://localhost:11434	Ollama API endpoint
SP_OLLAMA_MODEL	deepseek-r1:7b	LLM model name for reasoning
SP_WARLORD_DB	/var/lib/warlord/warlord.db	WARLORD SQLite registry path
SP_SIGNING_KEY	None	Path to Ed25519 PEM for SP report signing
SP_LOG_LEVEL	INFO	Logging verbosity (DEBUG/INFO/WARNING/ERROR)

WARLORD Integration

# Query SENTINEL PRIME escalation events in WARLORD
SELECT * FROM sentinel_prime_feed
WHERE escalation_type = 'm99'
ORDER BY timestamp DESC
LIMIT 20;

# Query by attack chain
SELECT * FROM sentinel_prime_feed
WHERE attack_chain = 'orchestration_takeover'
  AND confidence >= 0.90;

Report Schema (SP-{hex12})

{
  "report_id": "SP-4a7f3c2e9b1d",
  "signature": "<Ed25519 base64>",
  "timestamp": "2026-06-12T14:32:11Z",
  "version": "1.0.0",
  "attack_chain": "orchestration_takeover",
  "correlated_modules": ["M149", "M124", "M147", "M150"],
  "source_count": 4,
  "confidence": 0.93,
  "escalation_level": 5,
  "gates": {
    "confidence": {"threshold": 0.85, "value": 0.93, "passed": true},
    "sources": {"threshold": 3, "value": 4, "passed": true},
    "escalation_level": {"threshold": 4, "value": 5, "passed": true}
  },
  "m99_triggered": true,
  "warlord_ref": "WARLORD-2026-6147",
  "llm_reasoning": "Correlated alerts indicate CrewAI workflow compromise ...",
  "recommended_action": "escalate_m99"
}

Troubleshooting

Symptom	Likely Cause	Fix
All gates fail immediately	Ollama not running	ollama serve + verify SP_OLLAMA_HOST
No correlations firing	Not enough distinct module alerts	Check SP_MIN_SOURCES; verify AI Shield modules are running
M99 not triggering despite 3 gates passing	Fall-dead cap reached	Restart sentinel-prime or increase SP_FALLBACK_M99_CAP
Low confidence scores	deepseek-r1:7b model not pulled	ollama pull deepseek-r1:7b
SP report not signed	SP_SIGNING_KEY not set	Generate Ed25519 key and set env var