sentinel-mcp

Turn Claude into an autonomous SOC analyst.

An MCP (Model Context Protocol) server that gives Claude the ability to ingest security logs, detect anomalies using machine learning, correlate events across sources, map findings to MITRE ATT&CK, and generate incident reports -- all without leaving the chat.

Tools

Quick Start

Install

git clone https://github.com/zach-abraham/sentinel-mcp.git
cd sentinel-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Configure in Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "sentinel-mcp": {
      "command": "/path/to/sentinel-mcp/.venv/bin/sentinel-mcp"
    }
  }
}

Configure in Claude Code

claude mcp add sentinel-mcp /path/to/sentinel-mcp/.venv/bin/sentinel-mcp

Run Standalone

sentinel-mcp

Example Usage

Once configured, Claude can act as your SOC analyst:

Analyze authentication logs for threats:

"Analyze the auth logs from the last 24 hours. Are there any brute force attempts?"

Hunt for a suspicious IP across all sources:

"Hunt for IP 198.51.100.23 across all available logs."

Run anomaly detection with high sensitivity:

"Run anomaly detection on the auth logs with sensitivity 0.8."

Correlate events into attack chains:

"Correlate all events from the last 48 hours. Show me any attack chains."

Map an event to MITRE ATT&CK:

"Map this to MITRE: Multiple failed SSH logins followed by a successful login and immediate sudo to root."

Generate an incident report:

"Generate a full incident report for the last 24 hours."

Check indicators of compromise:

"Check these IOCs: 198.51.100.23, 203.0.113.50, evil.example.com"

Architecture

                          Claude (LLM)
                               |
                          MCP Protocol
                               |
                    +----------+-----------+
                    |   sentinel-mcp       |
                    |   (FastMCP Server)   |
                    +----------+-----------+
                               |
          +--------------------+--------------------+
          |                    |                    |
    +-----+------+     +------+------+     +-------+------+
    |  Parsers   |     |  Detectors  |     |   Analysis   |
    +-----+------+     +------+------+     +-------+------+
    | auth.py    |     | anomaly.py  |     | mitre.py     |
    | syslog.py  |     |  (Isolation |     |  (ATT&CK     |
    | firewall.py|     |   Forest)   |     |   mapping)   |
    | cloudtrail |     | rules.py    |     | reporter.py  |
    | generic.py |     |  (20 rules) |     |  (Markdown   |
    +------------+     +-------------+     |   reports)   |
                                           +--------------+
          |
    +-----+------+
    | Log Sources |
    +-----+------+
    | auth.log   |     Syslog, firewall, CloudTrail,
    | syslog.log |     or any text-based log format
    | *.json     |
    +------------+

Data Flow

1. Ingestion -- Parsers normalize raw logs into structured event objects with typed fields (timestamp, source IP, event type, severity).
2. Detection -- The rule engine (20 Sigma-inspired rules) and Isolation Forest anomaly detector independently evaluate the event stream.
3. Correlation -- Events are grouped by source IP and time window to reconstruct attack chains and map them to kill chain phases.
4. Mapping -- Findings are mapped to MITRE ATT&CK techniques via keyword-indexed lookup across 20+ techniques and 10 tactics.
5. Reporting -- All findings are synthesized into a structured incident report with executive summary, timeline, IOCs, MITRE table, and response recommendations.

Detection Capabilities

Rule Engine (20 Built-in Rules)

Anomaly Detection (ML-Based)

MITRE ATT&CK Coverage

The embedded technique database covers 20+ techniques across these tactics:

Sample Attack Scenario

The included sample data (data/sample_logs/) contains a realistic multi-stage attack:

1. Reconnaissance (firewall.log) -- Port scan of 25 common service ports from 198.51.100.23
2. Initial Access (auth.log) -- SSH brute force with 12+ failed attempts across 8 usernames
3. Credential Access (auth.log) -- Successful login with compromised deploy credentials
4. Privilege Escalation (auth.log) -- sudo /bin/bash to root
5. Persistence (auth.log, syslog) -- New user svc_backup created, added to sudo group, crontab modified
6. Defense Evasion (syslog, cloudtrail.json) -- Fail2Ban stopped, rsyslog stopped, CloudTrail logging disabled
7. Cloud Exploitation (cloudtrail.json) -- IAM user created with AdministratorAccess, S3 bucket made public, security group opened to 0.0.0.0/0
8. Execution (auth.log, syslog) -- Reverse shell via netcat to attacker C2

Running generate_report against this sample data produces a comprehensive incident report identifying all eight phases.

Configuration

Environment Variables

Extending

Custom log parsers: Subclass the generic parser or add new parsers to src/sentinel_mcp/parsers/.

Custom detection rules: Add rules to the _build_rules() method in src/sentinel_mcp/detectors/rules.py. Each rule is a function that takes a list of event dicts and returns Detection objects.

Additional MITRE techniques: Add entries to data/mitre_attack.json following the existing schema. The mapper loads external JSON and merges it with the built-in database.

Testing

python -m pytest tests/ -v

77 tests covering parsers, detectors, MITRE mapping, report generation, and all MCP tool functions.

Why This Matters

This project demonstrates practical application of several security engineering disciplines:

License

MIT