crowdsentinel-mcp-server

CrowdSentinel MCP サーバー

AI を活用した脅威ハンティングおよびインシデント対応フレームワーク

MCP 公式レジストリ · PyPI パッケージ

LLM と企業のセキュリティデータを Model Context Protocol（MCP）で接続する、オープンソースの脅威ハンティングオーケストレーター

クイックスタート · インストール · CLI の使い方 · 機能 · アーキテクチャ · ドキュメント · 使用例

警告 このプロジェクトは現在開発中であり、セキュリティテスト、研究、教育目的のみを対象としています。本番環境での使用には対応していません。本番環境にデプロイしないでください。API、ツールインターフェース、データ形式は予告なく変更される場合があります。ご自身の責任でご使用ください。

デモ

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

CrowdSentinel とは？

CrowdSentinel は、従来の SIEM クエリを、自然言語を使ったインテリジェントでフレームワーク主導の調査に変換します。LLM を企業のセキュリティデータソースに接続する統合セキュリティインテリジェンスレイヤーとして、次の機能を提供します。

• 自然言語による脅威ハンティング — 平易な英語で Elasticsearch にクエリを実行
• AI 主導の調査ワークフロー — 組み込みプロンプトが、適切な IR 手法に沿ってエージェントをガイド
• 永続的な調査状態 — メモリ管理された IoC の追跡、フォレンジックタイムライン、セッションをまたいで維持されるクエリ間相関（8GB の FIFO ストレージ）
• ツール間の IoC 相関 — あるツールで発見された IoC は、自動的にほかのすべてのツールから利用可能
• 複数ソース分析 — Elasticsearch、EVTX ログ（Chainsaw）、PCAP ファイル（Wireshark）、ライブエンドポイントフォレンジック（Velociraptor）、ローカルホストフォレンジック（osquery）
• Velociraptor エンドポイントフォレンジック — ライブアーティファクト収集用の 25 個の MCP ツール（プロセス、ネットワーク、永続化、実行証跡、NTFS MFT、SRUM、リモート EVTX）と自動 IoC 抽出
• エンコードされたコマンドの難読化解除 — エンコードされたコマンド（PowerShell の -EncodedCommand など）から Base64／UTF-16LE／gzip／hex の各レイヤーを自動的に剥がし、内部に隠された C2 アドレスを IoC として検出
• 適応型スキーマインテリジェンス — データ駆動型のスキーマレジストリ（ECS、Sysmon、Windows Security、auditd、Zeek、Packetbeat、AWS CloudTrail）により、各インデックスのフィールド規則に合わせてハンティングを調整
• DFIR ナレッジリソース — 調査プレイブック、Pyramid of Pain のリファレンス、相互相関のガイダンスを、接続された AI エージェントに直接提供する 9 個の MCP リソース
• スタンドアロン 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 バイナリ
• Chainsaw 用の 3,000 件以上の 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 エージェントで動作します。以下からクライアントを選択してください。

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

利用可能なコマンド

出力形式

すべてのコマンドは、3 つの形式で --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

エージェントモード（--mcp）

analyse --mcp フラグを指定すると、決定論的な分析が、139 個すべての MCP ツールを自律的に使用して調査を行う AI エージェントに置き換わります。エージェントは、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

エージェントのフラグ：

パイプラインの例

決定論的な分析（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 エージェントによる調査（認証が必要です）：

# 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）、ネットワーク、ID

ログソース： PowerShell、Sysmon、セキュリティイベント、プロセス作成、監査ログ

エンコードされたコマンドの難読化解除

実際の侵入では、SIEM がそのまま保存するエンコードの中に C2 アドレスや URL が隠されています。最も一般的なのは PowerShell の -EncodedCommand（UTF-16LE の base64）ですが、FromBase64String、base64→gzip、単独の base64、16 進数のデータも使われます。CrowdSentinel は、IoC 抽出時と専用の decode_command ツールを通じて、これらの層を自動的にデコードするため、内部に隠されたインジケーターを表面化できます。

• 追加の依存関係は不要 — デコーダーのコアは Python 標準ライブラリ（base64/zlib/codecs/binascii）のみを使用します
• 必要に応じて追加可能 — deobf エクストラ（pip install 'crowdsentinel-mcp-server[deobf]'）をインストールすると、XOR や特殊なエンコーディングに対応する chepy が追加されます。インストールされていない場合も、問題なく機能が制限されます
• 処理の記録 — デコードのたびにレシピ（例：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" や平文のパスワードを絶対に使用しないでください。TLS 証明書の検証を有効にしたうえで、API キーまたはサービストークンを使用してください。自己署名証明書の場合は、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 トランスポートは、トランスポート層で強化されています。

• Origin 検証（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 と連携します。設定すると、MCP ツールが 25 個、相互相関ツールが 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 のアーティファクトから抽出された 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 エージェントに構造化された調査用リファレンスデータを直接提供します。

ドキュメント

ユーザーガイド

機能ガイド

開発者ガイド

コントリビューション

コントリビューションを歓迎します！ガイドラインについては CONTRIBUTING.md をご覧ください。

ライセンス

GNU General Public Licence v3.0 — 詳細は LICENSE をご覧ください。

サイバーレンジ

CrowdSentinel には、関連プロジェクトの crowdsentinel-range が付属しています。これは、正解ラベル付きの攻撃テレメトリを生成する完全に一時的な AWS ラボであり、合成データではなく実際の検知結果を調査できます。

現在のレンジ（v1）— AWS 2 ホストラボ

┌──────────────────────────── 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 つのシェルコードペイロードをデコードし、生バイト列から 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 が提供する、LLM とツールをつなぐプロトコル
• 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