CrowdSentinel MCP Server

AI-Powered Threat Hunting & Incident Response Framework

MCP Official Registry · PyPI Package

Open-source threat hunting orchestrator connecting LLMs to enterprise security data via Model Context Protocol (MCP)

Quick Start · Installation · CLI Usage · Features · Architecture · Documentation · Examples

Warning This project is in active development and intended for security testing, research, and educational purposes only. It is not production-ready. Do not deploy in production environments. APIs, tool interfaces, and data formats may change without notice. Use at your own risk.

---

Demo

https://github.com/user-attachments/assets/0d0381f0-5b68-43b2-8630-19ec130885b2

---

What is CrowdSentinel?

CrowdSentinel transforms traditional SIEM querying into intelligent, framework-driven investigations using natural language. It serves as a unified security intelligence layer that connects large language models to enterprise security data sources, enabling:

• Natural Language Threat Hunting — Query Elasticsearch using plain English
• AI-Guided Investigation Workflows — Built-in prompts guide agents through proper IR methodology
• Persistent Investigation State — Memory-managed IoC tracking, forensic timelines, and cross-query correlation that survives across sessions (8GB FIFO storage)
• Cross-Tool IoC Correlation — IoCs discovered in one tool are automatically available to all others
• Multi-Source Analysis — Elasticsearch, EVTX logs (Chainsaw), PCAP files (Wireshark), live endpoint forensics (Velociraptor), local host forensics (osquery)
• Velociraptor Endpoint Forensics — 25 MCP tools for live artefact collection (processes, network, persistence, execution evidence, NTFS MFT, SRUM, remote EVTX) with automatic IoC extraction
• Encoded-Command Deobfuscation — Automatically peels base64/UTF-16LE/gzip/hex layers off encoded commands (e.g. PowerShell -EncodedCommand) so C2 addresses hidden inside them surface as IoCs
• Adaptive Schema Intelligence — Data-driven schema registry (ECS, Sysmon, Windows Security, auditd, Zeek, Packetbeat, AWS CloudTrail) adapts hunts to each index's field conventions
• DFIR Knowledge Resources — 9 MCP resources exposing investigation playbooks, Pyramid of Pain reference, and cross-correlation guidance directly to connected AI agents
• Standalone CLI — Full threat hunting from the terminal without an MCP client

---

Installation

Install from PyPI (recommended)

# Install with pip
pip install crowdsentinel-mcp-server

# Or install with uv
uv pip install crowdsentinel-mcp-server

# Download detection rules, Chainsaw, and Sigma rules (one-time)
crowdsentinel setup

# Validate connector configuration and readiness (offline, no external calls)
crowdsentinel doctor

Optional extras:

# Velociraptor live endpoint forensics (adds 25 MCP tools)
pip install 'crowdsentinel-mcp-server[velociraptor]'

# Long-tail deobfuscation coverage via chepy (XOR, exotic encodings).
# The stdlib decoder core works without this — chepy only extends it.
pip install 'crowdsentinel-mcp-server[deobf]'

Detection rules (6,060 Lucene + EQL + ES|QL) are bundled with the package — no download needed. The setup command downloads additional tools:

• Chainsaw binary for EVTX analysis
• 3,000+ Sigma rules for Chainsaw

Downloaded tools are stored in ~/.crowdsentinel/ and persist across package upgrades.

System dependency for PCAP analysis:

# Required for network traffic analysis and cross-tool IoC correlation
sudo apt install tshark    # Debian/Ubuntu/Kali
sudo dnf install wireshark-cli  # Fedora/RHEL
brew install wireshark     # macOS

Run directly with uvx (no install needed)

# Elasticsearch 8.x (default)
uvx crowdsentinel-mcp-server

# Other backends
uvx crowdsentinel-mcp-server-es7   # Elasticsearch 7.x
uvx crowdsentinel-mcp-server-es9   # Elasticsearch 9.x
uvx opensearch-mcp-server          # OpenSearch 1.x/2.x/3.x

Install from source

git clone https://github.com/thomasxm/CrowdSentinels-AI-MCP.git
cd CrowdSentinels-AI-MCP
chmod +x setup.sh && ./setup.sh

# Or install everything, including all optional extras (deobf/chepy, velociraptor)
./setup.sh --full

The setup script will:

• Install dependencies (pipx, uv, Claude Code CLI if needed)
• Bundle 6,060 detection rules and download Chainsaw binary
• Prompt for Elasticsearch credentials (never hardcoded)
• Configure the MCP server with Claude Code
• Validate your connection

With --full, every optional extra is installed too, so all 139 MCP tools have their dependencies available — the recommended mode for a production-ready server.

Installed Size

CrowdSentinel bundles 6,060 detection rules and integrates with external analysis tools. Below is the full disk space breakdown so you can plan accordingly.

Core package (via pip or uvx):

Component	Size	Notes
CrowdSentinel package	49 MB	The server itself
— Bundled Sigma rules (src/rules/)	30 MB	6,060 pre-converted detection rules
— Elastic TOML rules (src/detection-rules/)	17 MB	Original TOML format rules + hunting queries
— Python code (clients, tools, etc.)	2 MB	Actual application code
Dependencies	64 MB	All transitive deps
— cryptography	14 MB	Largest dependency (TLS)
— elasticsearch	8.3 MB	ES Python client
— pygments	5.2 MB	Syntax highlighting
— pydantic_core	5 MB	Validation engine
— opensearchpy	3.6 MB	OpenSearch client
— Others (27 packages)	~28 MB	mcp, fastmcp, httpx, anthropic, etc.
Core total	113 MB	pip install crowdsentinel-mcp-server

Additional tools (via crowdsentinel setup):

Component	Download	Installed	Notes
Chainsaw binary (v2.13.1)	~3 MB	~15 MB	EVTX log analysis engine
Sigma rules (SigmaHQ)	~3 MB	~30 MB	3,000+ Sigma rules for Chainsaw
Chainsaw mappings	—	<1 MB	Event log source mappings
Setup total	~6 MB	~46 MB	Stored in ~/.crowdsentinel/

System dependency (via package manager):

Component	Installed	Install Command	Notes
tshark + Wireshark libs	~132 MB	sudo apt install tshark	PCAP network analysis — required for cross-tool IoC correlation

Full installation summary:

Scenario	Total Disk Space
Core only (pip install)	~113 MB
Core + setup (crowdsentinel setup)	~159 MB
Full platform (+ tshark)	~291 MB

Note: PyPI download size is only 8.9 MB (wheel) thanks to compression of the bundled detection rules.

---

Quick Start

1. Set environment variables

export ELASTICSEARCH_HOSTS="https://localhost:9200"
export ELASTICSEARCH_API_KEY="your_api_key"
# Or use username/password:
# export ELASTICSEARCH_USERNAME="elastic"
# export ELASTICSEARCH_PASSWORD="your_password"
export VERIFY_CERTS="false"

2. Connect to an MCP Client

CrowdSentinel works with any MCP-compatible AI agent. Choose your client below:

claude mcp add crowdsentinel \
  -e ELASTICSEARCH_HOSTS="https://localhost:9200" \
  -e ELASTICSEARCH_API_KEY="your_api_key" \
  -e VERIFY_CERTS="false" \
  -- uvx crowdsentinel-mcp-server

Edit ~/.config/Claude/claude_desktop_config.json (Linux) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "crowdsentinel": {
      "command": "uvx",
      "args": ["crowdsentinel-mcp-server"],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_API_KEY": "your_api_key",
        "VERIFY_CERTS": "false"
      }
    }
  }
}

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "crowdsentinel": {
      "command": "uvx",
      "args": ["crowdsentinel-mcp-server"],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_API_KEY": "your_api_key",
        "VERIFY_CERTS": "false"
      }
    }
  }
}

Then enable MCP in VS Code settings: "chat.mcp.enabled": true

Create or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "crowdsentinel": {
      "command": "uvx",
      "args": ["crowdsentinel-mcp-server"],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_API_KEY": "your_api_key",
        "VERIFY_CERTS": "false"
      }
    }
  }
}

Create .roo/mcp.json in your workspace:

{
  "mcpServers": {
    "crowdsentinel": {
      "command": "uvx",
      "args": ["crowdsentinel-mcp-server"],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_API_KEY": "your_api_key",
        "VERIFY_CERTS": "false"
      }
    }
  }
}

Or configure via Roo Code settings panel: Settings > MCP Servers > Add Server.

In 5ire settings (v0.15.0+), add an MCP server with:

• Command: uvx
• Arguments: crowdsentinel-mcp-server
• Environment Variables:
  • ELASTICSEARCH_HOSTS = https://localhost:9200
  • ELASTICSEARCH_API_KEY = your_api_key
  • VERIFY_CERTS = false

Note: 5ire v0.14.0 has known MCP compatibility issues. Use v0.15.0+ for reliable operation.

stdio transport (default — works with most clients):

{
  "mcpServers": {
    "crowdsentinel": {
      "command": "uvx",
      "args": ["crowdsentinel-mcp-server"],
      "env": {
        "ELASTICSEARCH_HOSTS": "https://localhost:9200",
        "ELASTICSEARCH_API_KEY": "your_api_key",
        "VERIFY_CERTS": "false"
      }
    }
  }
}

SSE transport (for web-based clients):

crowdsentinel-mcp-server --transport sse --port 8001
# Connect to: http://localhost:8001/sse/

HTTP transport (for REST API clients):

crowdsentinel-mcp-server --transport streamable-http --port 8001
# Connect to: http://localhost:8001/mcp/

3. Or use the CLI directly

# Download rules and tools (one-time)
crowdsentinel setup

# Check cluster health
crowdsentinel health

# Hunt for threats
crowdsentinel hunt "powershell encoded" -i winlogbeat-*

# Run detection rules
crowdsentinel rules -p windows --tactic credential_access
crowdsentinel detect windows_builtin_win_alert_mimikatz_keywords_lucene -i winlogbeat-*

# Analyse PCAP files
crowdsentinel pcap overview capture.pcap
crowdsentinel pcap beaconing capture.pcap

# Hunt EVTX logs with Chainsaw
crowdsentinel chainsaw hunt /path/to/evtx/ --sigma-rules /path/to/sigma/

---

CLI Usage

CrowdSentinel provides a full CLI for threat hunting from the terminal:

pip install crowdsentinel-mcp-server
crowdsentinel setup    # Download rules, Chainsaw, Sigma (one-time)
crowdsentinel --help

Available Commands

Command	Description	Example
setup	Download detection rules, Chainsaw, and Sigma rules	crowdsentinel setup
health	Show cluster health	crowdsentinel health
indices	List all indices	crowdsentinel indices
hunt	IR-focused threat hunt with IoC extraction	crowdsentinel hunt "powershell" -i winlogbeat-*
eql	Execute an EQL query	crowdsentinel eql "process where process.name == 'cmd.exe'" -i winlogbeat-*
esql	Execute an ES|QL query	crowdsentinel esql "FROM logs-* | LIMIT 10"
detect	Execute a detection rule by ID	crowdsentinel detect win_susp_logon -i winlogbeat-*
rules	List available detection rules	crowdsentinel rules -p windows --tactic credential_access --type eql
schema	Detect schema for an index pattern	crowdsentinel schema -i winlogbeat-*
ioc	Hunt for a specific Indicator of Compromise	crowdsentinel ioc 203.0.113.42 --type ip -i winlogbeat-*
analyse	Analyse search results from stdin (JSON)	cat results.json | crowdsentinel analyse -c "context"
analyse --mcp	AI agent analysis using all 139 MCP tools	crowdsentinel hunt "query" | crowdsentinel analyse --mcp -c "context"
auth	Manage LLM authentication for agent mode	crowdsentinel auth login
pcap	Analyse PCAP files (overview, beaconing, lateral movement)	crowdsentinel pcap beaconing capture.pcap
chainsaw	Hunt EVTX logs with Chainsaw and Sigma rules	crowdsentinel chainsaw hunt /path/to/evtx/
doctor	Validate connector configuration and readiness (offline — no external calls)	crowdsentinel doctor

Output Formats

All commands support --output/-o with three formats:

crowdsentinel hunt "failed login" -i winlogbeat-* -o json     # Structured JSON (default)
crowdsentinel hunt "failed login" -i winlogbeat-* -o table    # Human-readable table
crowdsentinel hunt "failed login" -i winlogbeat-* -o summary  # Condensed summary

Agent Mode (--mcp)

The analyse --mcp flag replaces deterministic analysis with an AI agent that autonomously uses all 139 MCP tools to investigate. The agent follows the 4-phase IR methodology: hunt, analyse, correlate, report.

Authentication:

# Option 1: Browser sign-in (ChatGPT subscription — no API billing)
crowdsentinel auth login

# Option 2: Anthropic (setup-token or API key)
crowdsentinel auth login --provider anthropic

# Option 3: Environment variable
export ANTHROPIC_API_KEY="sk-ant-..."   # or OPENAI_API_KEY

# Option 4: Local models (Ollama, vLLM — free)
crowdsentinel analyse --mcp --model-url http://localhost:11434/v1 --model llama3.1

# Check auth status
crowdsentinel auth status

Agent flags:

Flag	Default	Description
--mcp	off	Enable AI agent with MCP tools
--mcp-server NAME:CMD	none	Add external MCP server (e.g., VirusTotal)
--model	auto-detect	LLM model to use
--model-url	none	OpenAI-compatible API endpoint
--max-steps	30	Maximum tool calls
--timeout	300	Maximum seconds

Pipeline Examples

Deterministic analysis (no API key needed):

# Hunt then analyse
crowdsentinel hunt "powershell encoded" -i winlogbeat-* -o json | \
  crowdsentinel analyse -c "Encoded PowerShell commands" -o summary

# Investigate failed authentication attempts
crowdsentinel hunt "event.code:4625" -i winlogbeat-* -o json | \
  crowdsentinel analyse -c "Failed login brute force investigation" -o summary

# Triage process execution and privilege escalation
crowdsentinel hunt "event.code:4688 OR event.code:4672 OR event.code:1" -i winlogbeat-* -o json | \
  crowdsentinel analyse -c "Process execution and privilege escalation" -o summary

AI agent investigation (requires auth):

# Credential dumping investigation — agent hunts, analyses kill chain, checks adjacent stages
crowdsentinel hunt "mimikatz OR lsass OR procdump" -i winlogbeat-* -o json | \
  crowdsentinel analyse --mcp -c "Credential dumping tools investigation" --max-steps 15 -o summary

# Encoded PowerShell — full IR workflow with kill chain and adjacent stage hunting
crowdsentinel hunt "powershell -enc OR FromBase64String" -i winlogbeat-* -o json | \
  crowdsentinel analyse --mcp -c "Full IR workflow: encoded PowerShell" --max-steps 30 -o table

# Process execution with detection rules
crowdsentinel hunt "event.code:4688" -i winlogbeat-* -o json | \
  crowdsentinel analyse --mcp -c "Execute detection rules against process creation" --max-steps 20 -o summary

# PCAP beaconing — agent generates IoCs and maps to kill chain
crowdsentinel pcap beaconing capture.pcap -o json | \
  crowdsentinel analyse --mcp -c "Investigate beaconing for C2 infrastructure" --max-steps 10 -o summary

# Anti-forensics investigation
crowdsentinel hunt "event.code:1102" -i winlogbeat-* -o json | \
  crowdsentinel analyse --mcp -c "Security log cleared - anti-forensics" --max-steps 10 -o summary

# With external MCP server (e.g., VirusTotal)
crowdsentinel hunt "powershell" -i winlogbeat-* -o json | \
  crowdsentinel analyse --mcp --mcp-server "vt:uvx virustotal-mcp-server" \
  -c "Check IoCs against VirusTotal" -o summary

---

Key Features

139 MCP Tools

Threat hunting, detection rules, forensics, endpoint collection, network analysis, cross-correlation, command deobfuscation, and IoC enrichment — all accessible via natural language

6,060 Detection Rules

Pre-built Lucene, EQL & ES|QL rules with automatic MITRE ATT&CK mapping

Investigation State

Persistent IoC tracking across tools and sessions with cross-source correlation and FIFO storage

4 Security Frameworks

• Cyber Kill Chain (7 stages)
• Pyramid of Pain (6 levels)
• Diamond Model (4 vertices)
• MITRE ATT&CK (automatic mapping)

5 Data Sources + Threat Intel

• Elasticsearch / OpenSearch (SIEM)
• Velociraptor (live endpoint forensics)
• osquery (local host forensics)
• EVTX logs (Chainsaw + Sigma)
• PCAP files (Wireshark/TShark)
• IoC enrichment (Shodan, VirusTotal, AbuseIPDB, ThreatFox)
• MISP (export events, search attributes)

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                 LLM Client / Claude Code CLI                    │
└─────────────────────────────┬───────────────────────────────────┘
                              │ MCP Protocol (stdio/SSE/HTTP)
                              │ HTTP: Origin validation (anti DNS-rebinding)
                              │       + transport-level audit logging
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    CrowdSentinel MCP Server                     │
│  ┌───────────────┐ ┌───────────────┐ ┌───────────────────────┐  │
│  │  139 Tools    │ │ 6,060 Rules   │ │ Security Frameworks   │  │
│  │ - Hunting     │ │ - Lucene      │ │ - Cyber Kill Chain    │  │
│  │ - Detection   │ │ - EQL         │ │ - Pyramid of Pain     │  │
│  │ - Forensics   │ │ - ES|QL       │ │ - Diamond Model       │  │
│  │ - Endpoint    │ │               │ │ - MITRE ATT&CK        │  │
│  │ - Network     │ ├───────────────┤ │                       │  │
│  │ - Enrichment  │ │ Schema        │ │ 9 MCP Resources       │  │
│  │ - Correlation │ │ Registry      │ │ (DFIR knowledge base) │  │
│  │ - Deobfuscate │ │ (data-driven) │ │                       │  │
│  └───────────────┘ └───────────────┘ └───────────────────────┘  │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │              Investigation State (Persistent)               ││
│  │    Cross-source IoC sharing, auto-capture, STIX 2.1 export  ││
│  └─────────────────────────────────────────────────────────────┘│
└─────┬──────────┬──────────┬──────────────┬─────────────┬────────┘
      │          │          │              │             │
      ▼          ▼          ▼              ▼             ▼
┌───────────┐ ┌──────────┐ ┌────────┐ ┌───────────┐ ┌───────────┐
│Elastic-   │ │Velocirap-│ │osquery │ │ Chainsaw  │ │ Wireshark │
│search/    │ │tor       │ │(local  │ │(EVTX/     │ │  (PCAP)   │
│OpenSearch │ │(EDR/DFIR)│ │ host)  │ │ Sigma)    │ │ (Network) │
│  (SIEM)   │ │(Endpoint)│ │        │ │(Offline)  │ │           │
└───────────┘ └──────────┘ └────────┘ └───────────┘ └───────────┘
                          │
  ┌───────────────────────┼───────────────────────┐
  ▼                       ▼                       ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────────────────┐
│ Shodan        │ │  VirusTotal   │ │  AbuseIPDB + ThreatFox    │
│ InternetDB    │ │     (v3)      │ │  + MISP (export/search)   │
│  (free/no key)│ │  (free tier)  │ │  (free tier)              │
└───────────────┘ └───────────────┘ └───────────────────────────┘
                          │
                          ▼ (Roadmap)
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│    Splunk     │ │     Wazuh     │ │     Zeek      │
│               │ │  (EDR/XDR)    │ │   (NSM/IDS)   │
└───────────────┘ └───────────────┘ └───────────────┘

---

What's Included

Tool Categories (139 Tools)

Category	Tools	Description
Elasticsearch Core	19	Index, document, cluster, alias, data stream, raw API operations
Threat Hunting	8	Attack pattern detection, kill-chain stage hunting, timeframe hunts, anomaly detection
EQL & ES|QL Hunting	11	Event-sequence queries, ES|QL pipes, saved hunt history, capability detection
Asset Discovery & Schema Intelligence	12	Index discovery, data-driven schema detection (ECS, Sysmon, auditd, Zeek, CloudTrail…), smart search
IoC Analysis & Deobfuscation	6	IoC extraction, encoded-command decoding, kill-chain mapping, investigation reports
Detection Rules	9	6,060 rule library — list, execute, validate, suggest, batch execution
Investigation Prompts	5	Fast triage spine — 10 critical IR questions
Chainsaw (EVTX)	5	Sigma rule hunting, iterative IoC discovery
Wireshark (PCAP)	11	Network forensics, beaconing, lateral movement detection, traffic decoding
Threat Intelligence	5	IoC enrichment (Shodan, VirusTotal, AbuseIPDB, ThreatFox) + MISP export/search
Investigation State	10	Persistent IoCs, cross-tool sharing, STIX 2.1 export, reporting
Velociraptor (Endpoint)	25	Live forensic artefact collection — processes, network, persistence, execution evidence, MFT, SRUM
osquery (Local Host)	4	SQL-based local host forensics — processes, sockets, users, ad-hoc queries
Cross-Source Correlation	5	SIEM ↔ endpoint pivots, IoC-driven endpoint hunts, unified timelines, time correlation
Workflow Guidance & Status	4	Next-step guidance, progressive disclosure, system status, storage cleanup