🚀 falcon-mcp
falcon-mcpは、AIエージェントをCrowdStrike Falconプラットフォームに接続するModel Context Protocol (MCP)サーバーです。エージェントワークフローにおける高度なセキュリティ分析を実現します。検出、インシデント、ビヘイビアなどの基本的なセキュリティ機能へのプログラムによるアクセスを提供し、高度なセキュリティオペレーションと自動化の基盤を築きます。
⚠️ 重要なお知らせ
このプロジェクトは現在パブリックプレビュー中で、積極的に開発が進められています。安定版1.0リリース前に機能や動作が変更される可能性があります。試用やテストは歓迎しますが、本番環境でのデプロイは避けてください。最終リリースの改善にご協力いただけるよう、GitHub Issues を通じたフィードバックをお待ちしています。
🚀 クイックスタート
このセクションでは、falcon-mcpの基本的な使い方や必要な設定について説明します。以下の手順に沿って進めることで、すぐにサーバーを起動して利用することができます。
✨ 主な機能
API資格情報と必要なスコープ
CrowdStrike API資格情報の設定
Falcon MCPサーバーを使用する前に、CrowdStrikeコンソールでAPI資格情報を作成する必要があります。
- CrowdStrikeコンソールにログインします
- 「サポート」>「APIクライアントとキー」に移動します
- 「新しいAPIクライアントを追加」をクリックします
- APIクライアントを構成します
- クライアント名:説明的な名前を選択します(例:「Falcon MCP Server」)
- 説明:記録用の任意の説明を入力します
- APIスコープ:使用するモジュールに基づいてスコープを選択します(下記参照)
重要: 使用するモジュールに必要なスコープがAPIクライアントに設定されていることを確認してください。必要に応じて、後でCrowdStrikeコンソールでスコープを更新することができます。
モジュール別の必要APIスコープ
Falcon MCPサーバーは、それぞれ特定のAPIスコープを必要とするさまざまなモジュールをサポートしています。
| モジュール |
必要なAPIスコープ |
目的 |
| クラウドセキュリティ |
Falcon Container Image:read |
Kubernetesコンテナインベントリとコンテナイメージの脆弱性を検索および分析する |
| コア |
追加のスコープは不要 |
基本的な接続性とシステム情報を提供する |
| 検出 |
Alerts:read |
検出結果を検索および分析して、悪意のある活動を理解する |
| ディスカバリー |
Assets:read |
環境全体のアプリケーションインベントリを検索および分析する |
| ホスト |
Hosts:read |
ホスト/デバイス情報を管理および照会する |
| ID保護 |
Identity Protection Entities:read
Identity Protection Timeline:read
Identity Protection Detections:read Identity Protection Assessment:read |
包括的なエンティティ調査とID保護分析を行う |
| インシデント |
Incidents:read |
セキュリティインシデントと協調活動を分析する |
| インテリジェンス |
Actors (Falcon Intelligence):read
Indicators (Falcon Intelligence):read
Reports (Falcon Intelligence):read |
脅威アクター、IOC、インテリジェンスレポートを調査する |
| センサー使用状況 |
Sensor Usage:read |
センサー使用状況データにアクセスして分析する |
| サーバーレス |
Falcon Container Image:read |
クラウドサービスプロバイダー全体のサーバーレス関数の脆弱性を検索する |
| スポットライト |
Vulnerabilities:read |
脆弱性データとセキュリティ評価を管理および分析する |
利用可能なモジュール、ツール、リソース
⚠️ FQLガイドリソースに関する重要な注意事項: いくつかのモジュールには、包括的なクエリドキュメントと例を提供するFQL(Falcon Query Language)ガイドリソースが含まれています。これらのリソースはAIアシスタントやユーザーがクエリ構築を支援するために設計されていますが、FQLには微妙な構文要件とフィールド固有の動作があり、すぐには明らかでない場合があります。AI生成のFQLフィルターは、本番環境で使用する前にテストと検証を行う必要があります。簡単なクエリから始め、テスト環境で結果を検証しながら徐々に複雑さを増やすことをお勧めします。
このサーバーは、ツール(実行できるアクション)とリソース(ドキュメントとコンテキスト)の両方を提供します。ツールは検出結果の検索や脅威の分析などの操作を実行し、リソースはAIアシスタントがコンテキストを参照するためのFQLクエリガイドなどの包括的なドキュメントを提供します。
クラウドセキュリティモジュール
必要なAPIスコープ:
Falcon Container Image:read
CrowdStrikeクラウドセキュリティリソースにアクセスして分析するためのツールを提供します。
falcon_search_kubernetes_containers: CrowdStrike Kubernetes & Containersインベントリからコンテナを検索する
falcon_count_kubernetes_containers: フィルター条件に基づいてCrowdStrike Kubernetes & Containersインベントリのコンテナをカウントする
falcon_search_images_vulnerabilities: CrowdStrike Image Assessmentsからイメージの脆弱性を検索する
リソース:
falcon://cloud/kubernetes-containers/fql-guide: Kubernetesコンテナ検索の包括的なFQLドキュメントと例
falcon://cloud/images-vulnerabilities/fql-guide: イメージの脆弱性検索の包括的なFQLドキュメントと例
ユースケース: Kubernetesコンテナインベントリの管理、コンテナイメージの脆弱性分析
コア機能(サーバーに組み込まれている)
APIスコープ: 基本的なAPIアクセス以外に追加のスコープは必要ありません
Falcon APIとのやり取りに必要なコアツールを提供します。
falcon_check_connectivity: Falcon APIへの接続を確認する
falcon_list_enabled_modules: falcon-mcpサーバーで有効になっているモジュールをリストする
これらのモジュールは、サーバー起動時の--modules フラグによって決定されます。モジュールが指定されていない場合は、すべての利用可能なモジュールが有効になります。
falcon_list_modules: falcon-mcpサーバーで利用可能なすべてのモジュールをリストする
検出モジュール
必要なAPIスコープ: Alerts:read
CrowdStrike Falconの検出結果にアクセスして分析するためのツールを提供します。
falcon_search_detections: 環境内の悪意のある活動を理解するために検出結果を検索および分析する
falcon_get_detection_details: 特定の検出IDの包括的な検出詳細を取得して、セキュリティ脅威を理解する
リソース:
falcon://detections/search/fql-guide: 検出検索の包括的なFQLドキュメントと例
ユースケース: 脅威ハンティング、セキュリティ分析、インシデント対応、マルウェア調査
ディスカバリーモジュール
必要なAPIスコープ: Assets:read
CrowdStrike Falconのディスカバリーアプリケーションと管理されていない資産にアクセスして管理するためのツールを提供します。
falcon_search_applications: CrowdStrike環境内のアプリケーションを検索する
falcon_search_unmanaged_assets: 管理されたシステムによって検出された管理されていない資産(Falconセンサーがインストールされていないシステム)を検索する
リソース:
falcon://discover/applications/fql-guide: アプリケーション検索の包括的なFQLドキュメントと例
falcon://discover/hosts/fql-guide: 管理されていない資産検索の包括的なFQLドキュメントと例
ユースケース: アプリケーションインベントリ管理、ソフトウェア資産管理、ライセンスコンプライアンス、脆弱性評価、管理されていない資産の検出、セキュリティギャップ分析
ホストモジュール
必要なAPIスコープ: Hosts:read
CrowdStrike Falconのホスト/デバイスにアクセスして管理するためのツールを提供します。
falcon_search_hosts: CrowdStrike環境内のホストを検索する
falcon_get_host_details: 指定されたホストデバイスIDの詳細情報を取得する
リソース:
falcon://hosts/search/fql-guide: ホスト検索の包括的なFQLドキュメントと例
ユースケース: 資産管理、デバイスインベントリ、ホスト監視、コンプライアンスレポート
ID保護モジュール
必要なAPIスコープ: Identity Protection GraphQL:write
CrowdStrike FalconのID保護機能にアクセスして管理するためのツールを提供します。
idp_investigate_entity: ユーザー、エンドポイント、その他のエンティティの分析を行うエンティティ調査ツールで、タイムライン分析、関係マッピング、リスク評価をサポートします
ユースケース: エンティティ調査、ID保護分析、ユーザー行動分析、エンドポイントセキュリティ評価、関係マッピング、リスク評価
インシデントモジュール
必要なAPIスコープ: Incidents:read
CrowdStrike Falconのインシデントにアクセスして分析するためのツールを提供します。
falcon_show_crowd_score: 環境の計算されたCrowdScoresとセキュリティポスチャーメトリクスを表示する
falcon_search_incidents: 環境内の協調活動を理解するためにセキュリティインシデントを検索および分析する
falcon_get_incident_details: 攻撃パターンと協調活動を理解するために包括的なインシデント詳細を取得する
falcon_search_behaviors: 環境内の疑わしい活動を理解するためにビヘイビアを検索および分析する
falcon_get_behavior_details: 攻撃手法と戦術を理解するために詳細なビヘイビア情報を取得する
リソース:
falcon://incidents/crowd-score/fql-guide: CrowdScoreクエリの包括的なFQLドキュメント
falcon://incidents/search/fql-guide: インシデント検索の包括的なFQLドキュメントと例
falcon://incidents/behaviors/fql-guide: ビヘイビア検索の包括的なFQLドキュメントと例
ユースケース: インシデント管理、脅威評価、攻撃パターン分析、セキュリティポスチャー監視
インテリジェンスモジュール
必要なAPIスコープ:
Actors (Falcon Intelligence):read
Indicators (Falcon Intelligence):read
Reports (Falcon Intelligence):read
CrowdStrikeインテリジェンスにアクセスして分析するためのツールを提供します。
falcon_search_actors: CrowdStrikeインテリジェンスによって追跡されている脅威アクターと敵対グループを調査する
falcon_search_indicators: CrowdStrikeインテリジェンスから脅威インジケーターと攻撃指標(IOC)を検索する
falcon_search_reports: CrowdStrikeインテリジェンス出版物と脅威レポートにアクセスする
リソース:
falcon://intel/actors/fql-guide: 脅威アクター検索の包括的なFQLドキュメントと例
falcon://intel/indicators/fql-guide: インジケーター検索の包括的なFQLドキュメントと例
falcon://intel/reports/fql-guide: インテリジェンスレポート検索の包括的なFQLドキュメントと例
ユースケース: 脅威インテリジェンス調査、敵対者追跡、IOC分析、脅威状況評価
センサー使用状況モジュール
必要なAPIスコープ: Sensor Usage:read
CrowdStrike Falconのセンサー使用状況データにアクセスして分析するためのツールを提供します。
falcon_search_sensor_usage: CrowdStrike環境内の週次センサー使用状況データを検索する
リソース:
falcon://sensor-usage/weekly/fql-guide: センサー使用状況検索の包括的なFQLドキュメントと例
ユースケース: センサーデプロイメント監視、ライセンス利用率分析、センサーヘルス追跡
サーバーレスモジュール
必要なAPIスコープ: Falcon Container Image:read
CrowdStrike Falconのサーバーレス脆弱性にアクセスして管理するためのツールを提供します。
falcon_search_serverless_vulnerabilities: すべてのクラウドサービスプロバイダーのサーバーレス関数の脆弱性を検索する
リソース:
falcon://serverless/vulnerabilities/fql-guide: サーバーレス脆弱性検索の包括的なFQLドキュメントと例
ユースケース: サーバーレスセキュリティ評価、脆弱性管理、クラウドセキュリティ監視
スポットライトモジュール
必要なAPIスコープ: Vulnerabilities:read
CrowdStrikeスポットライトの脆弱性にアクセスして管理するためのツールを提供します。
falcon_search_vulnerabilities: CrowdStrike環境内の脆弱性を検索する
リソース:
falcon://spotlight/vulnerabilities/fql-guide: 脆弱性検索の包括的なFQLドキュメントと例
ユースケース: 脆弱性管理、セキュリティ評価、コンプライアンスレポート、リスク分析、パッチ優先順位付け
📦 インストール
前提条件
- Python 3.11以上
uv またはpip
- CrowdStrike Falcon API資格情報(上記参照)
環境構成
CrowdStrike API資格情報をいくつかの方法で構成することができます。
.envファイルを使用する
.envファイルを使用する場合は、いくつかのオプションがあります。
オプション1: クローンしたリポジトリからコピーする(クローンした場合)
cp .env.example .env
オプション2: GitHubからサンプルファイルをダウンロードする
curl -o .env https://raw.githubusercontent.com/CrowdStrike/falcon-mcp/main/.env.example
オプション3: 以下の内容で手動で作成する
FALCON_CLIENT_ID=your-client-id
FALCON_CLIENT_SECRET=your-client-secret
FALCON_BASE_URL=https://api.crowdstrike.com
環境変数を使用する
あるいは、直接環境変数を使用することもできます。
シェルで以下の環境変数を設定します。
export FALCON_CLIENT_ID="your-client-id"
export FALCON_CLIENT_SECRET="your-client-secret"
export FALCON_BASE_URL="https://api.crowdstrike.com"
export FALCON_MCP_MODULES="detections,incidents,intel"
export FALCON_MCP_TRANSPORT="stdio"
export FALCON_MCP_DEBUG="false"
export FALCON_MCP_HOST="127.0.0.1"
export FALCON_MCP_PORT="8000"
CrowdStrike APIリージョンURL:
- US-1(デフォルト):
https://api.crowdstrike.com
- US-2:
https://api.us-2.crowdstrike.com
- EU-1:
https://api.eu-1.crowdstrike.com
- US-GOV:
https://api.laggar.gcw.crowdstrike.com
インストール方法
uvを使用してインストールする
uv tool install falcon-mcp
pipを使用してインストールする
pip install falcon-mcp
💡 使用アドバイス
falcon-mcpが見つからない場合は、シェルのPATHを更新してください。
コードエディター/アシスタントを介したインストールについては、以下のエディター/アシスタント統合セクションを参照してください。
💻 使用例
コマンドラインでの使用
デフォルト設定(stdioトランスポート)でサーバーを実行する:
falcon-mcp
SSEトランスポートで実行する:
falcon-mcp --transport sse
streamable-httpトランスポートで実行する:
falcon-mcp --transport streamable-http
カスタムポートでstreamable-httpトランスポートを使用して実行する:
falcon-mcp --transport streamable-http --host 0.0.0.0 --port 8080
モジュール構成
Falcon MCPサーバーは、有効にするモジュールを指定する複数の方法をサポートしています。
1. コマンドライン引数(最優先)
カンマ区切りのリストを使用してモジュールを指定する:
falcon-mcp --modules detections,incidents,intel,spotlight,idp
falcon-mcp --modules detections
2. 環境変数(フォールバック)
FALCON_MCP_MODULES環境変数を設定する:
export FALCON_MCP_MODULES=detections,incidents,intel,spotlight,idp
falcon-mcp
FALCON_MCP_MODULES=detections,incidents,intel,spotlight,idp falcon-mcp
3. デフォルトの動作(すべてのモジュール)
コマンドラインまたは環境変数でモジュールが指定されていない場合、すべての利用可能なモジュールがデフォルトで有効になります。
モジュールの優先順位:
- コマンドラインの
--modules引数(すべてを上書きする)
FALCON_MCP_MODULES環境変数(フォールバック)
- すべてのモジュール(指定がない場合のデフォルト)
追加のコマンドラインオプション
利用可能なすべてのオプションを表示する:
falcon-mcp --help
ライブラリとしての使用
from falcon_mcp.server import FalconMCPServer
server = FalconMCPServer(
base_url="https://api.us-2.crowdstrike.com",
debug=True,
enabled_modules=["detections", "incidents", "spotlight", "idp"]
)
server.run()
server.run("sse")
server.run("streamable-http")
server.run("streamable-http", host="0.0.0.0", port=8080)
サンプルの実行
python examples/basic_usage.py
python examples/sse_usage.py
python examples/streamable_http_usage.py
コンテナの使用
Falcon MCPサーバーは、簡単なデプロイのために事前構築されたコンテナイメージとして利用可能です。
事前構築されたイメージを使用する(推奨)
docker pull quay.io/crowdstrike/falcon-mcp:latest
docker run --rm --env-file /path/to/.env quay.io/crowdstrike/falcon-mcp:latest
docker run --rm -p 8000:8000 --env-file /path/to/.env \
quay.io/crowdstrike/falcon-mcp:latest --transport sse --host 0.0.0.0
docker run --rm -p 8000:8000 --env-file /path/to/.env \
quay.io/crowdstrike/falcon-mcp:latest --transport streamable-http --host 0.0.0.0
docker run --rm -p 8080:8080 --env-file /path/to/.env \
quay.io/crowdstrike/falcon-mcp:latest --transport streamable-http --host 0.0.0.0 --port 8080
docker run --rm --env-file /path/to/.env \
quay.io/crowdstrike/falcon-mcp:latest --modules detections,incidents,spotlight,idp
docker run --rm --env-file /path/to/.env \
quay.io/crowdstrike/falcon-mcp:1.2.3
docker run --rm -e FALCON_CLIENT_ID=your_client_id -e FALCON_CLIENT_SECRET=your_secret \
quay.io/crowdstrike/falcon-mcp:latest
ローカルでビルドする(開発用)
開発またはカスタマイズの目的で、コンテナイメージをローカルでビルドすることができます。
docker build -t falcon-mcp .
docker run --rm -e FALCON_CLIENT_ID=your_client_id -e FALCON_CLIENT_SECRET=your_secret falcon-mcp
注意: DockerでHTTPトランスポートを使用する場合は、常に--host 0.0.0.0を設定して、コンテナへの外部接続を許可してください。
エディター/アシスタント統合
Falcon MCPサーバーをエディターまたはAIアシスタントと統合することができます。以下は、一般的なMCPクライアントの構成例です。
uvxを使用する(推奨)
{
"mcpServers": {
"falcon-mcp": {
"command": "uvx",
"args": [
"--env-file",
"/path/to/.env",
"falcon-mcp"
]
}
}
}
モジュール選択付き
{
"mcpServers": {
"falcon-mcp": {
"command": "uvx",
"args": [
"--env-file",
"/path/to/.env",
"falcon-mcp",
"--modules",
"detections,incidents,intel"
]
}
}
}
個別の環境変数を使用する
{
"mcpServers": {
"falcon-mcp": {
"command": "uvx",
"args": ["falcon-mcp"],
"env": {
"FALCON_CLIENT_ID": "your-client-id",
"FALCON_CLIENT_SECRET": "your-client-secret",
"FALCON_BASE_URL": "https://api.crowdstrike.com"
}
}
}
}
Docker版
{
"mcpServers": {
"falcon-mcp-docker": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--env-file",
"/full/path/to/.env",
"quay.io/crowdstrike/falcon-mcp:latest"
]
}
}
}
追加のデプロイオプション
Amazon Bedrock AgentCore
MCPサーバーをAmazon Bedrock AgentCoreのツールとしてデプロイするには、このドキュメントを参照してください。
コントリビューション
コントリビューター向けの始め方
-
リポジトリをクローンする:
git clone https://github.com/CrowdStrike/falcon-mcp.git
cd falcon-mcp
-
開発モードでインストールする:
uv sync --all-extras
source .venv/bin/activate
⚠️ 重要なお知らせ
このプロジェクトは自動リリースとセマンティックバージョニングのためにConventional Commitsを使用しています。変更を提出する際には、コントリビューションガイドに記載されているコミットメッセージ形式に従ってください。
テストの実行
pytest
pytest --run-e2e tests/e2e/
pytest --run-e2e -v -s tests/e2e/
注意: E2Eテストの詳細な出力を表示するには、-sフラグが必要です。
開発者向けドキュメント
- モジュール開発ガイド: 新しいモジュールを実装するための手順
- リソース開発ガイド: リソースを実装するための手順
- エンドツーエンドテストガイド: E2Eテストの実行と理解のためのガイド
📄 ライセンス
このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。
サポート
これはコミュニティ主導のオープンソースプロジェクトです。公式のCrowdStroke製品ではありませんが、CrowdStrikeによって積極的にメンテナンスされ、オープンソース開発者コミュニティと協力してサポートされています。
詳細については、SUPPORTファイルを参照してください。