Documentation

Everything you need to install, configure, and run Sentinel — the unified AI agent security platform.

Installation

Sentinel installs with three commands. The installer handles everything automatically.

$ git clone https://github.com/ParthaMehtaOrg/sentinel-site-packages.git
$ cd log-prompt-agent && git checkout feature/unified-sentinel
$ ./install.sh

The installer does the following:

1. Sets up OpenClaw gateway and LLM provider
2. Installs the 8-hook security plugin + observation hook
3. Installs the sentinel Python package with all dependencies
4. Seeds default block rules (passwords, API keys, SSNs, credit cards)
5. Generates breach-intel credentials (~/.breach-intel/.env)
6. Adds BREACH_INTEL_URL + BREACH_INTEL_TOKEN to your shell profile
7. Installs a sitecustomize.py hook so every Python process is auto-monitored
8. Configures the LLM proxy (routes OpenClaw LLM traffic through Sentinel for inspection)
9. Starts three background services that auto-start on login/boot
10. Restarts the gateway

Prerequisites

• Python 3.10+
• Node.js 22+ (for OpenClaw)

Services & Ports

All services auto-start on boot via macOS LaunchAgent. Nothing to configure.

Auto-Instrumentation

Sentinel uses Python's sitecustomize.py mechanism to auto-patch AI frameworks at import time. No code changes required.

How it works

1. ./install.sh writes a persistent sitecustomize.py hook to your Python site-packages
2. When any Python process starts, the hook runs first
3. It checks for the BREACH_INTEL_URL environment variable (set in your shell profile by the installer)
4. If set, it calls auto_attach() which monkey-patches all detected AI framework methods
5. The agent auto-registers (agent_id from hostname + PID, detected frameworks as capabilities)
6. Every LLM response is silently sent to the breach-intel policy agent for classification — including trace_id, span_id, latency_ms, and token counts

Supported frameworks

Example (zero code changes)

# This agent has NO sentinel imports — monitoring is automatic
import openai

client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Look up customer SSN"}]
)
# This response is silently emitted to the breach-intel policy agent.
# If it contains PII, a CRITICAL breach is logged automatically.

Diagnostics

Run diagnostics to verify your installation:

$ python -m sentinel.breach_intel.sdk.cli doctor
✓ BREACH_INTEL_URL = http://localhost:8081
✓ Persistent hook installed
✓ Detected frameworks: OpenAI, Anthropic
✓ Server health: OK
✓ Credentials: valid
─────────────────────────────
All checks passed.

Policy Engine

The policy engine provides 3-layer prompt analysis, running on port 8000.

Endpoint Monitors

Five monitors run concurrently, detecting threats at the system level.

Block Rules

The block rule engine supports keyword, regex, recipient, and channel rules. Default rules are seeded during installation.

$ python -m sentinel rules --list
$ python -m sentinel rules --add keyword:password --reason "sensitive"
$ python -m sentinel rules --remove r_abc12345
$ python -m sentinel rules --add "channel:whatsapp" --reason "WhatsApp disabled"
$ python -m sentinel rules --add "recipient:+1234567890" --reason "blocked number"

DLP Scanners

9 scanners run on content, detecting PII, credentials, financial data, and more. Includes LLM classification across 8 threat categories.

• DLP scanner (SSNs, credit cards, emails, phone numbers)
• Credential scanner (API keys, tokens, passwords)
• Prompt Guard (3-layer analysis)
• Content Analyzer (LLM-powered classification)
• Text Extractor
• Financial data scanner
• PII pattern scanner
• Secret file scanner
• Exfiltration command scanner

LLM Proxy

The proxy sits between OpenClaw and upstream LLM APIs (Anthropic, OpenAI) on port 18790. For every request it:

• Measures latency (wall-clock round-trip time)
• Extracts token counts from response JSON/SSE streams
• Computes cost using a built-in pricing table (16 models)
• Checks block rules — replaces blocked responses with [Blocked]
• Reports trace spans to the policy engine (POST /trace)

All data feeds into the dashboard's Overview (cost/latency cards, model heatmaps) and Traces tab (expandable span trees).

8 Security Hooks

The OpenClaw plugin enforces security at 8 hook points. Every hook auto-connects to both the policy engine and breach-intel.

1. message_received → prompt attack detection
2. before_tool_call → tool pre-validation
3. after_tool_call → DLP scan on tool results
4. before_prompt_build → inject block rules into system prompt
5. llm_input → deep prompt analysis, can BLOCK LLM call entirely
6. llm_output → DLP scan + local rules + auto-emit to breach-intel
7. message_sending → hard-block outbound to channels
8. before_message_write → block session transcript persistence

Secure Tools

Two additional tools provide DLP-filtered access:

• secure_read — reads files with content scanning, blocks if PII/credentials detected
• secure_exec — executes commands with output scanning, blocks if sensitive data in output

Channel Security

OpenClaw has native channel adapters. After connecting a channel, all Sentinel hooks enforce automatically.

# Telegram
$ openclaw channels add --channel telegram --token YOUR_BOT_TOKEN

# WhatsApp (QR code pairing)
$ openclaw channels login --channel whatsapp

# Discord
$ openclaw channels add --channel discord --token YOUR_DISCORD_BOT_TOKEN

# Verify
$ openclaw channels status --probe

The message_sending hook blocks outbound messages containing PII/credentials, and before_message_write prevents them from being saved to conversation history.

Breach Intel

Rule-based breach classification — deterministic, <1ms per event, no LLM in the critical path. Runs on port 8081.

Breach Intel SDK (for explicit use)

from sentinel.breach_intel.sdk import PolicyAgentClient

client = PolicyAgentClient("http://localhost:8081", agent_id="my-agent")
result = client.emit_llm_response("Customer SSN is 123-45-6789")
# result.is_breach = True, result.severity = "CRITICAL"

Fintech

12 breach types. Covers: PII_EXPOSURE, CARD_DATA_EXPOSURE, CROSS_TENANT_LEAK, DATA_EXFILTRATION, SUSPICIOUS_TRANSACTION, UNAUTHORIZED_ACCESS, PRIVILEGE_ESCALATION, REGULATORY_VIOLATION, HALLUCINATION_FINANCIAL, AUDIT_TRAIL_MISSING, SCOPE_CREEP, UNAPPROVED_EXTERNAL_CALL.

Regulations: PCI-DSS, SOX, GDPR.

Healthcare

14 breach types. Covers: PHI_EXPOSURE, CLINICAL_NOTE_LEAK, UNAUTHORIZED_PRESCRIPTION_ACTION, DIAGNOSTIC_HALLUCINATION, MINORS_DATA_EXPOSURE, MENTAL_HEALTH_DISCLOSURE, HIV_STATUS_DISCLOSURE, GENOMIC_DATA_EXPOSURE, INSURANCE_DATA_LEAK, CROSS_PATIENT_LEAK, and more.

Regulations: HIPAA, 42 CFR Part 2, GDPR.

Pharma

14 breach types. Covers: TRIAL_DATA_FABRICATION, UNBLINDING_BREACH, AUDIT_TRAIL_VIOLATION_21CFR11, ESIGNATURE_BYPASS, REGULATORY_SUBMISSION_VIOLATION, PHARMACOVIGILANCE_BREACH, GMP_VIOLATION, and more.

Regulations: FDA 21-CFR Part 11, ICH-E6 (GCP), ICH-Q10 (GMP).

Hash Chain

Every breach record is SHA-256 checksummed. Each record includes the hash of the previous record, forming an immutable chain. No UPDATE or DELETE allowed.

{
  "id": "br_00042",
  "breach_type": "PII_EXPOSURE",
  "severity": "CRITICAL",
  "prev_hash": "a3f8c1d9...",
  "record_hash": "7b2e4f8a...",
  "timestamp": "2026-04-15T14:22:01Z"
}

Tamper detection runs automatically. If a single record is modified, the chain breaks and an alert is created.

Unified Dashboard

Access at http://localhost:8000/unified — a React SPA with 6 tabs. Auto-refreshes every 3 seconds.

Traces & Cost Tracking

The LLM proxy reports trace spans for every request. The dashboard's Traces tab shows expandable span trees with:

• Per-span latency (wall-clock round-trip)
• Input/output token counts
• Cost computed from the built-in 16-model pricing table
• Blocked status (if a block rule was triggered)
• Model and provider identification

REST API

Policy Engine (port 8000)

POST /prompt

Submit a prompt for 3-layer analysis. Returns risk score, category, and block decision.

POST /check

Quick check for block rules and pattern matching.

POST /llm-input

Pre-LLM-call analysis. Can block the LLM call entirely.

POST /llm-output

Post-LLM-call DLP scan and breach detection.

POST /trace

Submit a trace span (from LLM proxy or auto-instrumentation).

GET /traces

List trace spans, grouped by trace_id.

GET /events

SSE stream of real-time security events.

GET /unified

Serves the unified dashboard SPA.

Breach Intel (port 8081)

POST /events

Submit an agent event for breach classification.

GET /breaches

List breach records. Supports filtering by agent, severity, type, and date range.

GET /agents

List registered agents with framework info and breach counts.

GET /health

Server health check.

CLI Reference

Environment Variables

These are set automatically by the installer. Manual configuration is only needed for advanced use.

Container Security

Sentinel includes a hardened Docker setup:

• Non-root user, read-only rootfs
• cap_drop: ALL, no-new-privileges
• Custom seccomp profile blocking ptrace, mount, bpf, kexec_load
• 9-point verification script