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 范围及用途

模块	所需 API 范围	用途
云安全	Falcon Container Image:read	查找和分析 Kubernetes 容器清单以及容器镜像漏洞
核心	无额外范围	基本连接和系统信息
检测	Alerts:read	查找和分析检测信息，以了解恶意活动
发现	Assets:read	搜索和分析整个环境中的应用程序清单
主机	Hosts:read	管理和查询主机/设备信息
身份保护	Identity Protection Entities:read Identity Protection Timeline:read Identity Protection Detections:read Identity Protection Assessment:read	全面的实体调查和身份保护分析
事件	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 查询语言）指南资源，这些资源提供了全面的查询文档和示例。虽然这些资源旨在帮助 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 文件。