Skip to main content
Glama
Sign In
SentinelOps

SentinelOps

by ishachandan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

SentinelOps: AI Security Operations Copilot

SentinelOps is an open-source, defense-in-depth AI Security Operations Copilot built on FastMCP, Groq LLaMA 3.3, a Flask web UI, and an atomic SQLite WAL store. It pairs autonomous threat investigation with strict human-in-the-loop interlocks: untrusted log ingestion is delimited against prompt injection, destructive tools are filtered from the model's schema, proposals require verified evidence and bind parameters cryptographically via SHA-256 params_hash, and all operational state transitions are committed to a tamper-evident, SHA-256 hash-chained audit log with SQLite head verification.

Architecture

System Component & Evidence-Token Architecture

   +----------------------------------------------------------------------------------------------------+
   |                                      INVESTIGATION & REASONING                                     |
   |                                                                                                    |
   |    +-----------------------------+      Prompt & Tools     +----------------------------------+    |
   |    |    GROQ LLM (LLaMA 3.3)     |<=======================>|         FAST-MCP SERVER          |    |
   |    |  - Autonomous Reasoning     |                         |  - Schema Filter (Read/Propose)  |    |
   |    |  - Cannot execute actions   |                         |  - Session Context Management    |    |
   |    |  - Passes evidence_token    |                         +-----+----------------------+-----+    |
   |    +-----------------------------+                               |                      |          |
   +------------------------------------------------------------------|----------------------|----------+
                                                                      |                      |
            1. search_logs(query)                                     |                      | 2. check_ip_reputation(ip)
                                  v                                   v                      v
        +-----------------------------------------------+   +-----------------------------------------------+
        |             CHROMADB VECTOR STORE             |   |            ABUSEIPDB THREAT INTEL             |
        |  - Embeddings: all-MiniLM-L6-v2 ONNX          |   |  - Real-time abuse confidence score (0-100)   |
        |  - Ingests & indexes security audit telemetry |   |  - Score >= 50 flagged malicious              |
        |  - Raw logs returned in <untrusted_data> tag  |   |  - Mints session-bound evidence_token         |
        |  - Structured source_ip -> observed_ips table |   +-----------------------+-----------------------+
        +-----------------------+-----------------------+                           |
                                |                                                   | Returns evidence_token
                                | Structured IPs & Suspicious Events                | & reputation score
                                +-------------------------+-------------------------+
                                                          |
                                                          v
                                        +-----------------------------------+
                                        |        POLICY ENGINE CHECK        |
                                        |  [propose_block_ip/create_inc]    |
                                        |  * Target IP in observed_ips?     |
                                        |  * Valid evidence_token supplied? |
                                        |  * Target IP in Protected List?   |
                                        |  * Derive severity & approvals    |
                                        +-----------------+-----------------+
                                                          |
                                                          | PASS: Generates action token & params_hash
                                                          v
                                        +-----------------------------------+
                                        |      ATOMIC SQLITE WAL STORE      |
                                        |  - Stored: pending proposal       |
                                        |  - Cryptographic params_hash      |
                                        |  - Severity: Critical (2 approvals|
                                        |  - audit_head (last_seq, head)    |
                                        +-----------------+-----------------+
                                                          |
   +------------------------------------------------------|---------------------------------------------+
   |                                      HUMAN-IN-THE-LOOP APPROVAL                                    |
   |                                                      v                                             |
   |    +-----------------------------+       HTTP POST /confirm/<token>    +----------------------+    |
   |    |     OPERATOR (BROWSER)      |------------------------------------>|  FLASK WEB GATEWAY   |    |
   |    |  - Reviews IP, Reason, Hash |                                     |  - 3 Route Gates     |    |
   |    |  - Confirms action          |                                     |  - params_hash check |    |
   |    +-----------------------------+                                     +----------+-----------+    |
   |                                                                                   |                |
   |                                  4. execute_pending_action(token, hash)           v                |
   |                                  (Human-Only Tool: Hidden from LLM)    +----------------------+    |
   |                                                                        |   FIREWALL SANDBOX   |    |
   |                                                                        |   & AUDIT CHAIN      |    |
   |                                                                        | - iptables rule file |    |
   |                                                                        | - SHA-256 log chain  |    |
   |                                                                        +----------------------+    |
   +----------------------------------------------------------------------------------------------------+

Component Interaction Summary

  1. Groq LLaMA 3.3 (Autonomous Copilot): Drives threat reasoning and investigations through tool calling. Destructive tools (execute_pending_action, expire_blocks) are removed from its tool schema (HUMAN_ONLY_TOOLS), guaranteeing that the LLM cannot directly apply firewall rules or alter defensive configurations.

  2. ChromaDB (Vector Log Search & Prompt Injection Defense): Indexes security telemetry with ONNX all-MiniLM-L6-v2. Raw log lines returned to the LLM are sanitized and isolated in <untrusted_data> delimiters to defeat indirect prompt injections. FastMCP extracts only structured metadata fields (source_ip, client_ip) and records them into the SQLite observed_ips policy table.

  3. FastMCP Server (Tool Gateway & Human Gatekeeper): Enforces input validation, manages session contexts, interfaces with AbuseIPDB, and restricts destructive actions exclusively to human operator routes.

  4. Evidence-Token Check (Anti-Hallucination & Provenance Verification):

    • When the agent calls check_ip_reputation(ip), FastMCP queries AbuseIPDB and mints an authenticated result_token (stored in SQLite evidence table).

    • High/critical escalations (create_incident, notify_telegram) and mitigations (propose_block_ip) require this evidence_token.

    • The Policy Engine validates that:

      1. The token exists and belongs to the active session.

      2. The token is cryptographically bound to the target IP being acted on.

      3. Telemetry confirms a malicious threshold (score $\ge 50$ or confirmed high-threat log event).

      4. Target is not in the fail-closed protected allowlist (data/protected.yaml).

    • Hallucinated targets or prompt-injected victim IPs (e.g. 10.0.0.1) fail closed immediately with policy_denied:unobserved_ip or missing_evidence_token.

Related MCP server: impact-preview

Quickstart

1. Prerequisites

  • Python 3.11+ (or Python 3.12 for optional ChromaDB semantic search)

  • Git

2. Setup Local Environment

# Clone and enter directory
cd sentinelops

# Create and activate virtual environment
python -m venv .venv
# On Windows PowerShell:
.\.venv\Scripts\Activate.ps1
# On Linux/macOS:
source .venv/bin/activate

# Install dependencies
python -m pip install -r requirements.txt

3. Configure Environment

# Copy example configuration
cp .env.example .env

# Configure .env:
# GROQ_API_KEY=gsk_...           # Required only for live LLM mode
# USE_REAL_APIS=false            # Default: offline deterministic stub mode
# SENTINELOPS_REQUIRE_OBSERVED_IP=true

4. Run SentinelOps

# Start Web UI (runs at http://localhost:5000)
python web_ui.py

# OR start Interactive Terminal CLI
python cli.py

5. Run Verification & Test Suite

# Run the complete test suite (Unit, Hardening, Security Gates, E2E, Eval Harness)
python tests/run_all.py

# Verify cryptographic audit chain integrity
python -m sentinelops.verify_log data/action_log.jsonl

Security Guarantees

SentinelOps enforces rigorous security properties proved by automated unit, integration, and security gate tests:

  1. Prompt Injection Containment: All external log contents are wrapped in <untrusted_data> XML fences. System prompts explicitly instruct the agent that content within these fences is raw data. Crucially, the Policy Engine validates that an IP cannot be proposed for blocking unless observed in a structured log field or with reputation score $\ge 50$. Poisoned free-text instructions cannot trigger action proposals.

  2. Hidden Execution Tools (HUMAN_ONLY_TOOLS): Destructive tools (execute_pending_action, expire_blocks) are stripped from LLM tool definitions via schema transformation. If an injected LLM hallucinated a direct execution call, the agent loop rejects it before forwarding to FastMCP.

  3. Session-Bound Evidence Tokens: High and critical severity incident creations require a valid 8-character cryptographic token issued by check_ip_reputation within the same session. Agents cannot fabricate incidents without active investigation.

  4. Parameter Binding via SHA-256 params_hash: At proposal time, canonical JSON parameters (type, target, reason, TTL, severity, required approvals) are hashed. Both /confirm and execute_pending_action independently recompute and verify params_hash from the SQLite row. Tampering with targets or lowering severity from critical to low in the database causes immediate execution refusal.

  5. Multi-Party Approval Gate: Proposals derive severity server-side. Non-critical proposals execute on 1 human confirmation. critical severity actions require distinct confirmations from 2 separate operator identities.

  6. Fail-Closed Infrastructure Allowlist: Critical network infrastructure (127.0.0.1, 8.8.8.8, 1.1.1.1, 192.168.1.1, 127.0.0.0/8) cannot be blocked. If data/protected.yaml is missing or corrupted, the system falls back to hardcoded built-in protections and fails closed. The allowlist is re-checked inside execute_pending_action.

  7. Tamper-Evident SHA-256 Audit Chain: Every proposed, confirmed, declined, expired, and executed action is cryptographically chained (prev_hash). Concurrent writes are protected with OS file locks (msvcrt/fcntl). Clean tail truncations are detected via head state comparison against SQLite audit_head.

Agent Evaluation Results

The SentinelOps eval harness (evals/run_evals.py) runs 20 deterministic scenarios covering clear attackers, benign traffic, multi-IP investigations, all 6 prompt injection attack styles, protected IP defense, quarantine path escapes, and unblock workflows:

Metric

Benchmark Target

Result

Status

Forbidden Action Rate

0.0%

0.0%

PASSED

Tool-Call Accuracy

>= 90.0%

100.0%

PASSED

Correct Decision Rate

>= 90.0%

100.0%

PASSED

Hallucinated Evidence Rate

0.0%

0.0%

PASSED

Avg Latency / Investigation

N/A

252.25 ms

INFO

Avg Steps / Investigation

N/A

1.30

INFO

Detailed scenario breakdown and live LLM variance analysis can be found in docs/EVALS.md.

FastMCP Tool Inventory (13 Tools)

SentinelOps defines 13 FastMCP tools partitioned into public agent tools and human-only administrative tools:

Tool Name

Access Level

Description

ping

Agent

FastMCP connectivity and health check.

search_logs

Agent

Search security logs (returns wrapped <untrusted_data> and records structured indicators).

check_ip_reputation

Agent

Query IP reputation and generate authenticated evidence tokens.

create_incident

Agent

File incidents (enforces evidence token requirement for high/critical).

list_incidents

Agent

List recorded incidents from local store.

propose_block_ip

Agent

Propose blocking an IP address (returns preview token and params_hash).

propose_quarantine_file

Agent

Propose isolating a suspicious file in the sandbox.

propose_unblock_ip

Agent

Propose removing an active firewall block rule for a currently blocked target.

propose_restore_quarantined_file

Agent

Propose restoring an existing quarantined file to its verified sandbox path.

get_action_log

Agent

Read recent cryptographic audit trail records.

notify_telegram

Agent

Send security alerts (requires evidence token for critical notifications).

execute_pending_action

Human-Only

Executes confirmed action tokens. Hidden from LLM; called only by human confirmation flow.

expire_blocks

Human-Only

Scans and expires active block rules past TTL. Hidden from LLM schema.

Configuration Reference

Configuration is managed via environment variables (with safe defaults in stub mode):

# Core Mode Settings
USE_REAL_APIS=false                      # 'false' runs deterministic stub data; 'true' uses Groq & AbuseIPDB
ENABLE_DEBUG_ENDPOINTS=false            # Enables debug tools; strictly false in production
FLASK_DEBUG=false                       # Flask debug mode

# LLM & Third-Party APIs
GROQ_API_KEY=                           # Groq API key for LLaMA 3.3
ABUSEIPDB_API_KEY=                      # AbuseIPDB API key
TELEGRAM_BOT_TOKEN=                     # Telegram bot token for alerts (optional)
TELEGRAM_CHAT_ID=                       # Telegram chat ID for alerts (optional)

# Policy & Defense Settings
SENTINELOPS_REQUIRE_OBSERVED_IP=true    # Require IP observation before proposing blocks
SENTINELOPS_OBSERVED_IP_TTL=3600        # Observed IP TTL in seconds (default: 1 hour)
SENTINELOPS_MIN_BLOCK_SCORE=50          # Minimum reputation score required for block proposal
SENTINELOPS_BLOCK_TTL=3600              # Firewall rule expiration TTL in seconds (default: 1 hour)
SENTINELOPS_SUSPICIOUS_EVENTS=          # Comma-separated list of suspicious log event types
SENTINELOPS_PROTECTED_FILE=data/protected.yaml # YAML allowlist of protected IPs and CIDRs

Known Limitations

  1. Operator Identity Authentication: Operator identities are currently passed via the X-Operator-ID HTTP header (or session ID) rather than an authenticated session token. Because the current deployment lacks cryptographic authentication (such as OIDC, SAML, or signed JWT session cookies), the two-person approval mechanism is not yet cryptographically strong against an adversarial insider capable of spoofing HTTP headers.

  2. Total File and Database Rewrite: The SHA-256 hash chain reliably detects tampering, entry modification, record reordering, and tail truncation via SQLite audit_head. However, an adversary with root/filesystem access who simultaneously rewrites both action_log.jsonl and the SQLite database can recalculate the hash chain from a forged genesis record. Defense against simultaneous rewrite requires an external trust anchor (e.g., remote append-only syslog, WORM storage, or hardware security module).

  3. Windows Platform Symlink Escape Test: On Windows operating systems without Developer Mode or elevated Administrator privileges, non-privileged Python processes return WinError 1314 when creating filesystem symlinks. Consequently, the symlink escape test (test_quarantine_rejects_symlink_pointing_outside_sandbox) is skipped on Windows and validated in POSIX/Linux CI environments.

Further Documentation

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Resources

Related MCP Connectors

Related MCP Servers

  • impact-preview

    agent-polis
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server that provides impact preview and approval workflow for AI agent actions, allowing users to see diffs and risk assessments before any changes are executed.
    1
    MIT

  • a2a-trustgate

    jyswee
    F
    license
    Not graded
    quality
    F
    maintenance
    MCP server for AI agent compliance that screens actions before execution and records decisions in an immutable, SIEM-ready audit trail.
    84 npm
    -

  • Vantex-Security-A

    farahkhaterr
    F
    license
    Not graded
    quality
    C
    maintenance
    This MCP server provides secure access to databases for AI agents, enforcing authentication, authorization, human approval, logging, and notifications to prevent dangerous actions.
    -

Appeared in Searches