Falcon MCP

🚀 falcon-mcp

falcon-mcp 是一個模型上下文協議（MCP）服務器，它將 AI 代理與 CrowdStrike Falcon 平臺連接起來，為智能安全分析提供支持。該服務器提供了對重要安全功能的編程訪問，包括檢測、事件和行為分析，為高級安全操作和自動化奠定了基礎。

⚠️ 重要提示

🚧 公開預覽：此項目目前處於公開預覽階段，仍在積極開發中。在穩定的 1.0 版本發佈之前，功能和特性可能會發生變化。雖然我們鼓勵您進行探索和測試，但請避免在生產環境中部署。我們歡迎您通過 GitHub Issues 提供反饋，以幫助我們完善最終版本。

🚀 快速開始

1. 準備 API 憑證

在使用 Falcon MCP 服務器之前，您需要在 CrowdStrike 控制檯中創建 API 憑證：

1. 登錄 CrowdStrike 控制檯
2. 導航至“支持”>“API 客戶端和密鑰”
3. 點擊“添加新 API 客戶端”
4. 配置 API 客戶端：
   • 客戶端名稱：選擇一個具有描述性的名稱（例如，“Falcon MCP 服務器”）
   • 描述：可選，用於記錄的描述信息
   • API 範圍：根據您計劃使用的模塊選擇相應的範圍（見下文）

⚠️ 重要提示

請確保您的 API 客戶端具有您計劃使用的模塊所需的必要範圍。您可以隨時在 CrowdStrike 控制檯中更新範圍。

2. 安裝與配置

前提條件

• 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

# 可選配置（根據需要取消註釋並修改）
#FALCON_MCP_MODULES=detections,incidents,intel
#FALCON_MCP_TRANSPORT=stdio
#FALCON_MCP_DEBUG=false
#FALCON_MCP_HOST=127.0.0.1
#FALCON_MCP_PORT=8000

環境變量

或者，您可以直接使用環境變量。在您的 shell 中設置以下環境變量：

# 必需配置
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"                     # 傳輸方法：stdio、sse、streamable-http
export FALCON_MCP_DEBUG="false"                         # 啟用調試日誌：true、false
export FALCON_MCP_HOST="127.0.0.1"                      # HTTP 傳輸的主機
export FALCON_MCP_PORT="8000"                           # HTTP 傳輸的端口

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，請更新您的 shell PATH。

3. 運行服務器

命令行運行

使用默認設置（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

作為庫使用

from falcon_mcp.server import FalconMCPServer

# 創建並運行服務器
server = FalconMCPServer(
    base_url="https://api.us-2.crowdstrike.com",  # 可選，默認為環境變量
    debug=True,  # 可選，啟用調試日誌
    enabled_modules=["detections", "incidents", "spotlight", "idp"]  # 可選，默認為所有模塊
)

# 使用 stdio 傳輸運行（默認）
server.run()

# 或者使用 SSE 傳輸運行
server.run("sse")

# 或者使用 streamable-http 傳輸運行
server.run("streamable-http")

# 或者在自定義主機/端口上使用 streamable-http 傳輸運行
server.run("streamable-http", host="0.0.0.0", port=8080)

運行示例

# 使用 stdio 傳輸運行
python examples/basic_usage.py

# 使用 SSE 傳輸運行
python examples/sse_usage.py

# 使用 streamable-http 傳輸運行
python examples/streamable_http_usage.py

✨ 主要特性

可用模塊、工具和資源

各模塊所需 API 範圍及用途

關於 FQL 指南資源的重要說明

⚠️ 多個模塊包含 FQL（Falcon 查詢語言）指南資源，這些資源提供了全面的查詢文檔和示例。雖然這些資源旨在幫助 AI 助手和用戶構建查詢，但 FQL 具有細微的語法要求和特定字段的行為，可能不會立即顯現。AI 生成的 FQL 過濾器應在生產環境中使用之前進行 測試和驗證。我們建議從簡單的查詢開始，逐步增加複雜性，同時先在測試環境中驗證結果。

各模塊詳細信息

雲安全模塊

所需 API 範圍：Falcon Container Image:read

工具：

• falcon_search_kubernetes_containers：從 CrowdStrike Kubernetes 和容器清單中搜索容器
• falcon_count_kubernetes_containers：根據過濾條件從 CrowdStrike Kubernetes 和容器清單中統計容器數量
• falcon_search_images_vulnerabilities：從 CrowdStrike 圖像評估中搜索圖像漏洞

資源：

• falcon://cloud/kubernetes-containers/fql-guide：用於 Kubernetes 容器搜索的全面 FQL 文檔和示例
• falcon://cloud/images-vulnerabilities/fql-guide：用於圖像漏洞搜索的全面 FQL 文檔和示例

用例：管理 Kubernetes 容器清單、容器圖像漏洞分析

核心功能（內置在服務器中）

API 範圍：除基本 API 訪問外，無需額外範圍

工具：

• falcon_check_connectivity：檢查與 Falcon API 的連接
• falcon_list_enabled_modules：列出 Falcon MCP 服務器中啟用的模塊

  這些模塊由啟動服務器時的 --modules 標誌 確定。如果未指定模塊，則默認啟用所有可用模塊。

• falcon_list_modules：列出 Falcon MCP 服務器中所有可用的模塊

檢測模塊

所需 API 範圍：Alerts:read

工具：

• falcon_search_detections：查找和分析檢測信息，以瞭解環境中的惡意活動
• falcon_get_detection_details：獲取特定檢測 ID 的詳細檢測信息，以瞭解安全威脅

資源：

• falcon://detections/search/fql-guide：用於檢測搜索的全面 FQL 文檔和示例

用例：威脅狩獵、安全分析、事件響應、惡意軟件調查

發現模塊

所需 API 範圍：Assets:read

工具：

• falcon_search_applications：在您的 CrowdStrike 環境中搜索應用程序
• falcon_search_unmanaged_assets：搜索由受管系統發現的未受管資產（未安裝 Falcon 傳感器的系統）

資源：

• falcon://discover/applications/fql-guide：用於應用程序搜索的全面 FQL 文檔和示例
• falcon://discover/hosts/fql-guide：用於未受管資產搜索的全面 FQL 文檔和示例

用例：應用程序清單管理、軟件資產管理、許可證合規性、漏洞評估、未受管資產發現、安全漏洞分析

主機模塊

所需 API 範圍：Hosts:read

工具：

• falcon_search_hosts：在您的 CrowdStrike 環境中搜索主機
• falcon_get_host_details：檢索指定主機設備 ID 的詳細信息

資源：

• falcon://hosts/search/fql-guide：用於主機搜索的全面 FQL 文檔和示例

用例：資產管理、設備清單、主機監控、合規性報告

身份保護模塊

所需 API 範圍：Identity Protection GraphQL:write

工具：

• idp_investigate_entity：用於分析用戶、端點和其他實體的實體調查工具，支持時間線分析、關係映射和風險評估

用例：實體調查、身份保護分析、用戶行為分析、端點安全評估、關係映射、風險評估

事件模塊

所需 API 範圍：Incidents:read

工具：

• 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

工具：

• 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

工具：

• falcon_search_sensor_usage：在您的 CrowdStrike 環境中搜索每週傳感器使用數據

資源：

• falcon://sensor-usage/weekly/fql-guide：用於傳感器使用搜索的全面 FQL 文檔和示例

用例：傳感器部署監控、許可證利用率分析、傳感器健康跟蹤

無服務器模塊

所需 API 範圍：Falcon Container Image:read

工具：

• falcon_search_serverless_vulnerabilities：搜索跨雲服務提供商的無服務器函數中的漏洞

資源：

• falcon://serverless/vulnerabilities/fql-guide：用於無服務器漏洞搜索的全面 FQL 文檔和示例

用例：無服務器安全評估、漏洞管理、雲安全監控

聚光燈模塊

所需 API 範圍：Vulnerabilities:read

工具：

• falcon_search_vulnerabilities：在您的 CrowdStrike 環境中搜索漏洞

資源：

• falcon://spotlight/vulnerabilities/fql-guide：用於漏洞搜索的全面 FQL 文檔和示例

用例：漏洞管理、安全評估、合規性報告、風險分析、補丁優先級排序

📦 安裝指南

前提條件

• Python 3.11 或更高版本
• uv 或 pip
• CrowdStrike Falcon API 憑證（見上文）

環境配置

使用 .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

# 可選配置（根據需要取消註釋並修改）
#FALCON_MCP_MODULES=detections,incidents,intel
#FALCON_MCP_TRANSPORT=stdio
#FALCON_MCP_DEBUG=false
#FALCON_MCP_HOST=127.0.0.1
#FALCON_MCP_PORT=8000

環境變量

# 必需配置
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"                     # 傳輸方法：stdio、sse、streamable-http
export FALCON_MCP_DEBUG="false"                         # 啟用調試日誌：true、false
export FALCON_MCP_HOST="127.0.0.1"                      # HTTP 傳輸的主機
export FALCON_MCP_PORT="8000"                           # HTTP 傳輸的端口

安裝

使用 uv 安裝

uv tool install falcon-mcp

使用 pip 安裝

pip install falcon-mcp

💡 使用建議

如果找不到 falcon-mcp，請更新您的 shell 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

模塊配置

1. 命令行參數（優先級最高）

# 啟用特定模塊
falcon-mcp --modules detections,incidents,intel,spotlight,idp

# 僅啟用一個模塊
falcon-mcp --modules detections

2. 環境變量（備用）

# 導出環境變量
export FALCON_MCP_MODULES=detections,incidents,intel,spotlight,idp
falcon-mcp

# 或者內聯設置
FALCON_MCP_MODULES=detections,incidents,intel,spotlight,idp falcon-mcp

3. 默認行為（所有模塊）

如果未通過命令行或環境變量指定模塊，則默認啟用所有可用模塊。

模塊優先級順序：

1. 命令行 --modules 參數（覆蓋所有）
2. FALCON_MCP_MODULES 環境變量（備用）
3. 所有模塊（未指定時默認）

查看所有可用選項

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"]  # 可選，默認為所有模塊
)

# 使用 stdio 傳輸運行（默認）
server.run()

# 或者使用 SSE 傳輸運行
server.run("sse")

# 或者使用 streamable-http 傳輸運行
server.run("streamable-http")

# 或者在自定義主機/端口上使用 streamable-http 傳輸運行
server.run("streamable-http", host="0.0.0.0", port=8080)

運行示例

# 使用 stdio 傳輸運行
python examples/basic_usage.py

# 使用 SSE 傳輸運行
python examples/sse_usage.py

# 使用 streamable-http 傳輸運行
python examples/streamable_http_usage.py

📚 詳細文檔

容器使用

使用預構建的鏡像（推薦）

# 拉取最新的預構建鏡像
docker pull quay.io/crowdstrike/falcon-mcp:latest

# 使用 .env 文件運行（推薦）
docker run --rm --env-file /path/to/.env quay.io/crowdstrike/falcon-mcp:latest

# 使用 .env 文件和 SSE 傳輸運行
docker run --rm -p 8000:8000 --env-file /path/to/.env \
  quay.io/crowdstrike/falcon-mcp:latest --transport sse --host 0.0.0.0

# 使用 .env 文件和 streamable-http 傳輸運行
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

# 使用 .env 文件和自定義端口運行
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

# 使用 .env 文件和特定模塊運行
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 鏡像
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 以允許外部連接到容器。

編輯器/助手集成

使用 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 中，請參考 以下文檔。

🔧 技術細節

貢獻指南

貢獻者入門

1. 克隆倉庫：

git clone https://github.com/CrowdStrike/falcon-mcp.git
cd falcon-mcp

2. 以開發模式安裝：

# 創建 .venv 並安裝依賴項
uv sync --all-extras

# 激活虛擬環境
source .venv/bin/activate

⚠️ 重要提示

此項目使用 Conventional Commits 進行自動發佈和語義版本控制。請在提交更改時遵循我們 貢獻指南 中概述的提交消息格式。

運行測試

# 運行所有測試
pytest

# 運行端到端測試
pytest --run-e2e tests/e2e/

# 運行端到端測試並顯示詳細輸出（注意：需要 -s 標誌才能查看輸出）
pytest --run-e2e -v -s tests/e2e/

⚠️ 重要提示

需要 -s 標誌才能查看端到端測試的詳細輸出。

開發者文檔

• 模塊開發指南：實現新模塊的說明
• 資源開發指南：實現資源的說明
• 端到端測試指南：運行和理解端到端測試的指南

📄 許可證

本項目採用 MIT 許可證 - 有關詳細信息，請參閱 LICENSE 文件。

支持

這是一個社區驅動的開源項目。雖然它不是官方的 CrowdStrike 產品，但由 CrowdStrike 積極維護，並與開源開發者社區合作提供支持。

有關更多信息，請參閱我們的 SUPPORT 文件。