crowdsentinel-mcp-server

CrowdSentinel MCP 服务

AI 驱动的威胁狩猎与事件响应框架

MCP 官方注册表 · PyPI 软件包

开源威胁狩猎编排器，通过模型上下文协议（MCP）将大模型连接到企业安全数据

快速开始 · 安装 · CLI 用法 · 功能 · 架构 · 文档 · 示例

警告 本项目正在积极开发中，仅用于安全测试、研究和教育目的。它尚未达到生产就绪状态。请勿部署在生产环境中。API、工具接口和数据格式可能会在不另行通知的情况下发生变化。使用风险自负。

演示

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

什么是 CrowdSentinel？

CrowdSentinel 将传统 SIEM 查询转变为由框架驱动的智能调查流程，支持使用自然语言操作。它作为统一的安全情报层，将大模型连接到企业安全数据源，从而实现：

• 自然语言威胁狩猎 — 使用通俗英语查询 Elasticsearch
• AI 引导的调查工作流 — 内置提示词可引导 Agent 遵循正确的事件响应方法
• 持久化调查状态 — 通过内存管理 IoC 跟踪、取证时间线和跨查询关联，并可跨会话保留（8GB FIFO 存储）
• 跨工具 IoC 关联 — 在一个工具中发现的 IoC 会自动提供给所有其他工具
• 多源分析 — Elasticsearch、EVTX 日志（Chainsaw）、PCAP 文件（Wireshark）、实时端点取证（Velociraptor）、本地主机取证（osquery）
• Velociraptor 端点取证 — 提供 25 个 MCP 工具，用于实时收集工件（进程、网络、持久化、执行证据、NTFS MFT、SRUM、远程 EVTX），并自动提取 IoC
• 编码命令反混淆 — 自动剥离编码命令中的 base64/UTF-16LE/gzip/hex 层（例如 PowerShell -EncodedCommand），让其中隐藏的 C2 地址作为 IoC 显现
• 自适应架构智能 — 数据驱动的架构注册表（ECS、Sysmon、Windows Security、auditd、Zeek、Packetbeat、AWS CloudTrail）可根据各索引的字段约定调整威胁狩猎
• DFIR 知识资源 — 提供 9 个 MCP 资源，直接向已连接的 AI Agent 提供调查手册、痛苦金字塔参考资料和跨关联指南
• 独立 CLI — 无需 MCP 客户端，即可在终端中进行完整的威胁狩猎

安装

从 PyPI 安装（推荐）

# 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

可选额外组件：

# 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]'

检测规则（6,060 条 Lucene + EQL + ES|QL）已随软件包附带——无需下载。setup 命令会下载其他工具：

• 用于 EVTX 分析的 Chainsaw 二进制文件
• 3,000 多条供 Chainsaw 使用的 Sigma 规则

下载的工具存储在 ~/.crowdsentinel/ 中，并且在软件包升级后仍会保留。

PCAP 分析的系统依赖项：

# 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

使用 uvx 直接运行（无需安装）

# 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

从源代码安装

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

设置脚本将：

• 安装依赖项（pipx、uv，以及需要时安装 Claude Code CLI）
• 随包提供 6,060 条检测规则并下载 Chainsaw 二进制文件
• 提示输入 Elasticsearch 凭据（绝不硬编码）
• 使用 Claude Code 配置 MCP 服务
• 验证连接

使用 --full 时，还会安装所有可选额外组件，使全部 139 个 MCP 工具都能使用其依赖项——这是部署可用于生产环境的服务的推荐模式。

安装大小

CrowdSentinel 随包提供 6,060 条检测规则，并集成外部分析工具。以下是完整的磁盘空间明细，便于你做好规划。

核心软件包（通过 pip 或 uvx 安装）：

其他工具（通过 crowdsentinel setup 安装）：

系统依赖项（通过软件包管理器安装）：

完整安装汇总：

**注意：**得益于随包附带的检测规则采用压缩格式，PyPI 下载大小仅为 8.9 MB（wheel）。

快速开始

1. 设置环境变量

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. 连接到 MCP 客户端

CrowdSentinel 兼容所有支持 MCP 的 AI Agent。请在下方选择你的客户端：

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

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

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

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

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

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

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

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

3. 或直接使用 CLI

# 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 用法

CrowdSentinel 提供完整的 CLI，可在终端中进行威胁狩猎：

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

可用命令

输出格式

所有命令均支持通过 --output/-o 指定以下三种格式：

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 模式（--mcp）

analyse --mcp 标志会使用可自主调用全部 139 个 MCP 工具进行调查的 AI Agent，取代确定性分析。该 Agent 遵循 4 阶段 IR 方法：搜寻、分析、关联、报告。

身份验证：

# 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 标志：

流水线示例

确定性分析（无需 API 密钥）：

# 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 调查（需要身份验证）：

# 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

主要功能

架构

┌─────────────────────────────────────────────────────────────────┐
│                 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)   │
└───────────────┘ └───────────────┘ └───────────────┘

包含内容

工具类别（139 个工具）

设置 VELOCIRAPTOR_API_CONFIG 后会注册 Velociraptor 工具；检测到本地 osqueryi 二进制文件后会注册 osquery 工具；当 DISABLE_HIGH_RISK_OPERATIONS=true 时，会隐藏 10 个高风险写入工具。

安全框架

检测规则（6,060 条规则）

**平台：**Windows、Linux、macOS、云（AWS/Azure/GCP）、网络、身份

**日志来源：**PowerShell、Sysmon、安全事件、进程创建、审计日志

编码命令去混淆

真实入侵会将 C2 地址和 URL 藏在 SIEM 原样存储的编码内容中，最常见的是 PowerShell -EncodedCommand（UTF-16LE 的 base64 编码），但也包括 FromBase64String、base64→gzip、裸 base64 和十六进制数据块。CrowdSentinel 会在 IoC 提取期间以及通过专用的 decode_command 工具自动解码这些层，让内部指标显现出来，而不是继续深埋其中：

• 无需额外依赖——解码器核心仅使用 Python 标准库（base64/zlib/codecs/binascii）
• 可选的扩展支持——安装 deobf 扩展（pip install 'crowdsentinel-mcp-server[deobf]'）即可添加 chepy，支持 XOR 和少见的编码方式；未安装时也会优雅降级
• 来源记录——每次解码都会记录所用方法（例如 base64->utf-16le），用于 IR 报告
• 安全设计——仅解码（不会执行任何内容），并限制解码深度和输出大小，避免解压炸弹导致服务挂起

配置

环境变量

# Connection (required — choose one)
ELASTICSEARCH_HOSTS="https://localhost:9200"       # Self-hosted
# OR
ELASTICSEARCH_CLOUD_ID="deployment:base64..."      # Elastic Cloud

# Authentication — choose one (in priority order):
ELASTICSEARCH_BEARER_TOKEN="service_token_here"    # Service/bearer token
ELASTICSEARCH_API_KEY="your_api_key"               # API key (recommended)
ELASTICSEARCH_USERNAME="elastic"                   # Basic auth
ELASTICSEARCH_PASSWORD="your_password"

# TLS / Certificate verification
VERIFY_CERTS="true"                                # Verify against system CA bundle
# VERIFY_CERTS="/path/to/ca.crt"                   # Verify against custom CA certificate
# ELASTICSEARCH_CA_CERT="/path/to/ca.crt"          # Explicit CA certificate path
# ELASTICSEARCH_CLIENT_CERT="/path/to/client.crt"  # Client certificate (mTLS)
# ELASTICSEARCH_CLIENT_KEY="/path/to/client.key"   # Client private key (mTLS)

# Options
REQUEST_TIMEOUT="30"                               # Request timeout in seconds
DISABLE_HIGH_RISK_OPERATIONS="true"                # Block all write operations

# HTTP/SSE transport security (stdio unaffected)
# MCP_ALLOWED_ORIGINS="https://app.example.com"    # Extra allowed Origins (comma-separated); loopback always allowed

# Velociraptor endpoint forensics (optional — enables 25 extra tools)
# VELOCIRAPTOR_API_CONFIG="/path/to/api_client.yaml"

# Threat Intelligence (optional — Shodan InternetDB works without any key)
VIRUSTOTAL_API_KEY="your_vt_key"                   # Free: 500 lookups/day
ABUSEIPDB_API_KEY="your_abuse_key"                 # Free: 1,000 lookups/day
THREATFOX_API_KEY="your_tf_key"                    # Free: unlimited

# MISP Integration (optional — offline JSON export works without a server)
MISP_URL="https://misp.example.org"                # MISP instance URL
MISP_API_KEY="your_misp_key"                       # MISP API key (40-char hex)
# MISP_SSL_VERIFY="true"                           # Set "false" for self-signed (dev only)

**安全警告：**生产环境中切勿使用 VERIFY_CERTS="false" 或明文密码。请使用 API 密钥或服务令牌，并启用 TLS 证书验证。对于自签名证书，请将 ELASTICSEARCH_CA_CERT 设置为 CA 证书路径。

生产环境配置示例

ELASTICSEARCH_CLOUD_ID="my-deployment:dXMtY2VudHJhbC0x..."
ELASTICSEARCH_API_KEY="your_cloud_api_key"
VERIFY_CERTS="true"

ELASTICSEARCH_HOSTS="https://es-cluster.internal:9200"
ELASTICSEARCH_API_KEY="your_api_key"
ELASTICSEARCH_CA_CERT="/etc/elasticsearch/certs/ca.crt"
VERIFY_CERTS="true"

ELASTICSEARCH_HOSTS="https://es-cluster.internal:9200"
ELASTICSEARCH_CA_CERT="/etc/elasticsearch/certs/ca.crt"
ELASTICSEARCH_CLIENT_CERT="/etc/elasticsearch/certs/client.crt"
ELASTICSEARCH_CLIENT_KEY="/etc/elasticsearch/certs/client.key"
VERIFY_CERTS="true"

ELASTICSEARCH_HOSTS="http://localhost:9200"
ELASTICSEARCH_USERNAME="elastic"
ELASTICSEARCH_PASSWORD="test123"
VERIFY_CERTS="false"

传输模式

HTTP 传输在传输层进行了加固：

• 来源验证（防 DNS 重绑定）——除非浏览器请求的 Origin 为回环地址或列在 MCP_ALLOWED_ORIGINS 中（以逗号分隔；单独使用 * 可禁用检查），否则会被拒绝。不含 Origin 标头的请求（即所有非浏览器 MCP 客户端）不受影响。
• 审计日志——每次 HTTP 交互都会在传输边界记录日志（JSON-RPC 方法、工具名称、正文大小、路径），包括工具层无法看到的请求，例如未知工具或协议错误。日志仅包含元数据、内存占用有界，并经过处理以防日志伪造。

禁用写操作

对于只读访问（生产环境推荐）：

DISABLE_HIGH_RISK_OPERATIONS="true"

这会隐藏具有破坏性的工具：create_index、delete_index、index_document、delete_document、delete_by_query、create_data_stream、delete_data_stream、put_alias、delete_alias、general_api_request

使用示例

示例 1：搜寻暴力破解攻击

You: Hunt for brute force attacks in the last hour

CrowdSentinel: Searching for failed authentication attempts...
[Calls hunt_by_timeframe with attack_types=["brute_force"]]

Found 47 failed login attempts from 3 source IPs targeting the "admin" account.
Top sources:
- 192.168.1.105: 28 attempts
- 10.0.0.42: 15 attempts
- 172.16.0.8: 4 attempts

示例 2：调查可疑主机

You: Show me all activity on host DESKTOP-ABC123 in the last 24 hours

CrowdSentinel: Generating a forensic timeline for that host...
[Calls get_host_activity_timeline]

Timeline shows:
- 09:15: User "jsmith" logged in (Event 4624)
- 09:17: PowerShell executed encoded command
- 09:18: New scheduled task created "WindowsUpdate"
- 09:22: Outbound connection to 203.0.113.42:443
- 09:25: LSASS memory access detected

示例 3：攻击链分析

You: We found C2 beaconing. What should we hunt for next?

CrowdSentinel: Hunting adjacent kill chain stages...
[Calls hunt_adjacent_stages with current_stage="COMMAND_AND_CONTROL"]

Looking backwards (Installation stage):
- Found scheduled task persistence on 3 hosts
- Registry Run key modifications detected

Looking forwards (Actions on Objectives):
- Lateral movement to 2 additional hosts via SMB
- Credential dumping attempts detected

示例 4：网络流量分析

You: Analyse this PCAP for C2 beaconing

CrowdSentinel: Checking for regular connection intervals...
[Calls detect_beaconing on the PCAP file]

Detected beaconing pattern:
- Host: 192.168.1.50 → 203.0.113.100:443
- Interval: 60 seconds (±2s jitter)
- Duration: 4 hours
- Confidence: HIGH

Recommend blocking 203.0.113.100 and investigating 192.168.1.50.

示例 5：通过 CLI 搜寻威胁

# Hunt for encoded PowerShell
crowdsentinel hunt "powershell -enc" -i winlogbeat-* --timeframe 1440 -o json

# Pipe results to analysis
crowdsentinel hunt "event.code:4625" -i winlogbeat-* -o json | \
  crowdsentinel analyse -c "Failed authentication investigation"

# Search detection rules for lateral movement
crowdsentinel rules --tactic lateral_movement -p windows

兼容性

面向开发者

crowdsentinel-mcp-server/
├── src/
│   ├── server.py                 # MCP server entry point
│   ├── version.py                # Version constant
│   ├── risk_config.py            # Write operation controls
│   ├── transport_security.py     # Origin validation for HTTP transports (anti DNS-rebinding)
│   ├── transport_audit.py        # Transport-level audit logging (every HTTP exchange)
│   │
│   ├── cli/                      # Standalone CLI
│   │   └── main.py               # CLI entry point (argparse) — 15 commands incl. doctor
│   │
│   ├── agent/                    # `analyse --mcp` AI agent mode (multi-provider LLM auth)
│   ├── config/                   # Connector configuration
│   │
│   ├── clients/                  # Backend logic layer
│   │   ├── base.py               # Base client, authentication
│   │   ├── exceptions.py         # Exception handling decorators
│   │   └── common/
│   │       ├── client.py         # Unified SearchClient (multiple inheritance)
│   │       ├── threat_hunting.py # Threat hunting queries
│   │       ├── ioc_analysis.py   # IoC extraction & analysis
│   │       ├── deobfuscate.py    # Encoded-command decoding (stdlib core + optional chepy)
│   │       ├── cyber_kill_chain.py # Kill chain logic
│   │       ├── rule_loader.py    # Detection rule loading
│   │       ├── chainsaw_client.py # EVTX/Sigma integration
│   │       ├── osquery_client.py # Local osquery execution (sqlglot-validated SQL)
│   │       ├── misp_client.py    # MISP export/search
│   │       ├── threat_intel.py   # Shodan/VirusTotal/AbuseIPDB/ThreatFox enrichment
│   │       └── schemas/          # Data-driven schema registry
│   │           ├── ecs.py, sysmon.py, windows_security.py, auditd.py
│   │           └── defs/         # JSON schema defs (zeek, packetbeat, aws_cloudtrail, …)
│   │
│   ├── tools/                    # MCP tool interfaces (25 modules, 139 tools)
│   │   ├── register.py           # Dynamic tool registration
│   │   ├── threat_hunting.py     # Hunting tool definitions
│   │   ├── rule_management.py    # Rule management tools
│   │   ├── velociraptor_tools.py # Live endpoint forensics (25 tools)
│   │   ├── osquery_tools.py      # Local host forensics (4 tools)
│   │   ├── cross_correlation.py  # SIEM ↔ endpoint correlation (5 tools)
│   │   ├── chainsaw_hunting.py   # Chainsaw tools
│   │   ├── wireshark_tools.py    # Network analysis tools
│   │   ├── threat_intel.py       # Enrichment + MISP tools
│   │   └── investigation_state_tools.py # State management tools
│   │
│   ├── storage/                  # Persistent investigation state
│   │   ├── investigation_state.py # Core state management
│   │   ├── storage_manager.py    # File system storage (8GB FIFO)
│   │   └── models.py             # Pydantic models (IoC, Investigation)
│   │
│   ├── utils/                    # Shared utilities
│   │
│   └── wireshark/                # Network traffic analysis
│       ├── core/                 # TShark execution, PCAP parsing
│       ├── hunting/              # Beaconing, lateral movement, IoC hunting
│       ├── baseline/             # Traffic baseline creation
│       ├── extraction/           # File carving from traffic
│       └── reporting/            # NCSC-style reports, timelines
│
├── rules/                        # 6,060 detection rules (EQL + Lucene)
├── chainsaw/                     # Chainsaw binary + 3,000+ Sigma rules
├── skills/                       # Claude Code agent skills
├── Makefile                      # Test pyramid + release automation
└── tests/                        # Tiered test suite (unit / integration / api / e2e / system)

class YourClient(SearchClientBase):
    def your_method(self, param: str) -> dict:
        # Implementation
        return results

class SearchClient(YourClient, OtherClients, ...):
    pass

class YourTools:
    def __init__(self, client, mcp):
        self.client = client
        self.mcp = mcp

    def register_tools(self):
        @self.mcp.tool()
        def your_tool(param: str) -> str:
            """Tool description for LLM."""
            result = self.client.your_method(param)
            return json.dumps(result)

from src.tools.your_tools import YourTools

def _register_tools(self):
    # ... existing tools ...
    YourTools(self.client, self.mcp).register_tools()

make test-unit          # fast hermetic loop (default developer command)
make coverage           # unit tier + coverage policy gate
make check-tests        # policy: every new function vs origin/main has a test
make test-integration   # real ES via testcontainers (Docker required)
make test-api           # + real MCP server subprocess over streamable-http
make test-e2e           # + real MCP client journey over the wire
make test-suite         # the whole pyramid, bottom-up, with a summary table

# Start Elasticsearch
docker-compose -f docker-compose-elasticsearch.yml up -d

# Start OpenSearch
docker-compose -f docker-compose-opensearch.yml up -d

路线图

详细版本历史请参阅 CHANGELOG.md。

Velociraptor 集成（实时端点取证）

CrowdSentinel 集成了 Velociraptor，用于实时收集端点取证 artefact。完成配置后，即可使用另外 25 个 MCP 工具和 5 个跨源关联工具。

设置

# Install optional dependencies
pip install crowdsentinel-mcp-server[velociraptor]

# Set the Velociraptor API config path
export VELOCIRAPTOR_API_CONFIG="/path/to/api_client.yaml"

API 客户端配置由 Velociraptor 服务端生成：

velociraptor config api_client --name crowdsentinel --role administrator,api \
  --config server.config.yaml /path/to/api_client.yaml

可用工具

跨源 IoC 共享

从 Velociraptor artefact 中提取的 IoC 会与 SIEM、Chainsaw 和 Wireshark 的发现一同自动纳入当前调查。使用 get_shared_iocs 获取合并后的指标集，以进行跨源关联。

SIEM (Elasticsearch)          Endpoint (Velociraptor)
       │                              │
  hunt_by_timeframe()         velociraptor_pslist()
       │                              │
  auto_capture ──────► Investigation State ◄────── auto_capture
                              │
                     get_shared_iocs()

DFIR 知识资源

9 个 MCP 资源可将结构化调查参考数据直接提供给已连接的 AI Agent：

文档

用户指南

功能指南

开发者指南

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解相关指南。

许可证

GNU 通用公共许可证 v3.0 — 详情请参阅 LICENSE。

网络靶场

CrowdSentinel 随附配套项目 crowdsentinel-range —— 这是一个完全临时的 AWS 实验室，可生成带有真实情况标签的攻击遥测数据，让你调查真实检测结果，而非合成数据。

当前靶场（v1）—— 2 主机 AWS 实验室

┌──────────────────────────── AWS VPC (private subnet) ────────────────────────────────┐
│                                                                                        │
│  ┌──────────────────────────────┐      ┌──────────────────────────────────────────┐  │
│  │   Linux SIEM (Ubuntu 22.04)  │      │   Windows Range Box (Server 2022)        │  │
│  │   Elasticsearch 8.x (TLS)   │◄─────│   Sysmon (olafhartong) + Winlogbeat 9    │  │
│  │   Auditbeat + Filebeat       │      │   Atomic Red Team + PurpleSharp          │  │
│  └──────────────────────────────┘      └──────────────────────────────────────────┘  │
│                         SSM VPC endpoints — no inbound ports open                     │
└───────────────────────────────────────┬────────────────────────────────────────────--┘
                                         │ SSM port-forward :19200
                              ┌──────────▼──────────────────────┐
                              │  ./range-mcp.sh → CrowdSentinel │
                              │  MCP Server → Claude Code       │
                              └─────────────────────────────────┘

只需 3 条命令，即可从零开始进行威胁狩猎：

cd crowdsentinel-range && make up && make attack-windows
cd .. && ./range-mcp.sh
# then in Claude Code: /mcp → "investigate potential intrusions on the windows machine"

演示：约 40 秒内完成 73,328 个事件的分诊 —— 解码 2 个 shellcode 载荷，从原始字节中提取 C2 IP，并生成包含 19 种 MITRE 技术的完整 IR 报告。

未来范围（v2）——企业 AD 环境

下一代靶场旨在实现完整覆盖 Active Directory 攻击链：初始访问 → 横向移动 → 域失陷，并加入网络安全监控层、运行时安全检测、集中式漏洞管理和欺骗基础设施。设计灵感来自 DetectionLab、Ludus 和 SimuLand。

┌───────────────────────────────────── AWS / Multi-VPC ───────────────────────────────────────────────────┐
│                                                                                                           │
│  ┌──── Attacker Subnet ────┐   ┌───────────── Corporate Subnet ──────────────────────────────────────┐  │
│  │                          │   │                                                                       │  │
│  │  Kali Linux (C2 server)  │   │  ┌─────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │  │
│  │  Caldera + Metasploit    │   │  │  Domain          │  │  Windows 11      │  │  Windows 11      │  │  │
│  │  Covenant C2             │──▶│  │  Controller      │  │  Workstation 1   │  │  Workstation 2   │  │  │
│  │                          │   │  │  (AD DS, DNS)    │  │  (domain-joined) │  │  (domain-joined) │  │  │
│  └──────────────────────────┘   │  └─────────────────┘  └──────────────────┘  └──────────────────┘  │  │
│                                  │  ┌──────────────────────────────────────────────────────────────┐  │  │
│  ┌──── DMZ Subnet ─────────┐    │  │   Linux File/Web Server (IIS / Apache, SMB share)            │  │  │
│  │                          │    │  └──────────────────────────────────────────────────────────────┘  │  │
│  │  Nginx reverse proxy     │    └───────────────────────────────────────────────────────────────────┘  │
│  │  Simulated internet SVC  │                                                                            │
│  └──────────────────────────┘   ┌───────────── Management / SIEM Subnet ──────────────────────────┐    │
│                                  │                                                                   │    │
│                                  │  ┌─────────────────────┐   ┌───────────────────────────────┐   │    │
│                                  │  │  Elasticsearch +     │   │  Zeek / Suricata              │   │    │
│                                  │  │  Kibana (SIEM)       │   │  (NSM — full packet + alerts) │   │    │
│                                  │  └─────────────────────┘   └───────────────────────────────┘   │    │
│                                  │  ┌─────────────────────┐   ┌───────────────────────────────┐   │    │
│                                  │  │  Velociraptor        │   │  Falco (runtime security)     │   │    │
│                                  │  │  (live EDR/forensics)│   │  eBPF probe (CO-RE, default)  │   │    │
│                                  │  └─────────────────────┘   │  + kernel module fallback     │   │    │
│                                  │  ┌─────────────────────┐   └───────────────────────────────┘   │    │
│                                  │  │  DefectDojo          │   ┌───────────────────────────────┐   │    │
│                                  │  │  (vuln management)   │   │  Honeypots + Canary tokens     │   │    │
│                                  │  │  Falco·Zeek·scanners │   │  (deception layer)             │   │    │
│                                  │  └─────────────────────┘   └───────────────────────────────┘   │    │
│                                  │  ┌─────────────────────────────────────────────────────────┐   │    │
│                                  │  │  Grafana — centralized dashboards + alerting             │   │    │
│                                  │  │  ES · Falco · Suricata · Velociraptor · DefectDojo       │   │    │
│                                  │  └─────────────────────────────────────────────────────────┘   │    │
│                                  └───────────────────────────────────────────────────────────────┘    │
│                                         VyOS router — inter-subnet ACLs + egress filter               │
└───────────────────────────────────────────────────────────────────────────────────────────────────────┘
                                                  │ SSM / VPN
                                    CrowdSentinel MCP + Claude Code

v2 目标能力：

设计参考：DetectionLab（Sysmon+WEF+Splunk 融合）、Ludus（模块化 Proxmox/Ansible、VLAN 分段）、SimuLand（多域 AD 林、云原生）、SANS FOR508（以工件为先的 DFIR 工作流）、Falco（CO-RE eBPF 探针架构、内核模块回退方案）。

致谢

CrowdSentinel 的构建离不开众多优秀开源项目的支持。感谢所有项目的维护者和贡献者。

协议与服务框架

• Model Context Protocol — 由 Anthropic 提供，将大模型连接到工具的协议
• FastMCP — 本项目基于此 Python MCP 服务框架构建

分析引擎与取证工具

• Chainsaw — WithSecure Labs 提供的 EVTX 日志分析器
• Velociraptor — Velocidex/Rapid7 提供的实时端点取证与 DFIR 平台
• osquery — osquery Foundation 提供的 SQL 驱动主机检测工具
• Wireshark / TShark — Wireshark Foundation 提供的网络协议分析工具
• Chepy — 类似 CyberChef 的解码库，为可选的长尾反混淆功能提供支持
• sqlglot — 用于安全验证 osquery 查询的 SQL 解析器

检测内容

• Sigma / SigmaHQ — 社区检测规则标准及规则库
• Elastic detection-rules — Elastic 预置的 EQL/ES|QL 检测规则
• 社区贡献的 Sigma 规则和自定义规则

数据平台与威胁情报

• Elasticsearch 和 OpenSearch Python 客户端
• MISP / PyMISP — 开源威胁情报平台及客户端
• stix2 — 用于结构化 IoC 导出的 OASIS STIX 2.1 库
• Shodan InternetDB、VirusTotal、AbuseIPDB 和 abuse.ch ThreatFox — 提供免费套餐的 IoC 丰富化服务

开发与测试

• testcontainers-python — 为实时测试层提供真实的 Elasticsearch 容器
• pytest、Ruff、Bandit — 测试运行器、代码检查和 SAST

方法论框架

• Cyber Kill Chain（Lockheed Martin）、Pyramid of Pain（David J. Bianco）、Diamond Model（Caltagirone、Pendergast 和 Betz）、MITRE ATT&CK