carlosmmatos/falcon-mcp
GitHub: carlosmmatos/falcon-mcp
MCP 服务器，将 AI Agent 连接到 CrowdStrike Falcon 平台，实现对话式的安全分析与威胁狩猎自动化。
Stars: 0 | Forks: 0
# falcon-mcp
[](https://badge.fury.io/py/falcon-mcp)
[](https://pypi.org/project/falcon-mcp/)
[](https://opensource.org/licenses/MIT)
**falcon-mcp** 是一个 Model Context Protocol (MCP) 服务器，用于将 AI agent 与 CrowdStrike Falcon 平台连接，在您的代理工作流中实现智能安全分析。它提供对关键安全能力（包括检测、事件和行为）的编程访问，为高级安全操作和自动化奠定基础。
## 目录
- [API 凭证与所需权限范围](#api-credentials--required-scopes)
- [设置 CrowdStrike API 凭证](#setting-up-crowdstrike-api-credentials)
- [各模块所需 API 权限范围](#required-api-scopes-by-module)
- [可用模块、工具与资源](#available-modules-tools--resources)
- [云安全模块](#cloud-security-module)
- [核心功能（内置于服务器）](#core-functionality-built-into-server)
- [自定义 IOA 模块](#custom-ioa-module)
- [检测模块](#detections-module)
- [发现模块](#discover-module)
- [主机模块](#hosts-module)
- [身份保护模块](#identity-protection-module)
- [事件模块](#incidents-module)
- [NGSIEM 模块](#ngsiem-module)
- [情报模块](#intel-module)
- [IOC 模块](#ioc-module)
- [防火墙管理模块](#firewall-management-module)
- [计划报告模块](#scheduled-reports-module)
- [传感器使用模块](#sensor-usage-module)
- [Serverless 模块](#serverless-module)
- [Spotlight 模块](#spotlight-module)
- [安装与设置](#installation--setup)
- [前置条件](#prerequisites)
- [环境配置](#environment-configuration)
- [安装](#installation)
- [用法](#usage)
- [命令行](#command-line)
- [模块配置](#module-configuration)
- [其他命令行选项](#additional-command-line-options)
- [作为库使用](#as-a-library)
- [运行示例](#running-examples)
- [容器使用](#container-usage)
- [使用预构建镜像（推荐）](#using-pre-built-image-recommended)
- [本地构建（开发）](#building-locally-development)
- [编辑器/助手集成](#editorassistant-integration)
- [使用 `uvx`（推荐）](#using-uvx-recommended)
- [带模块选择](#with-module-selection)
- [使用单独的环境变量](#using-individual-environment-variables)
- [Docker 版本](#docker-version)
- [其他部署选项](#additional-deployment-options)
- [Amazon Bedrock AgentCore](#amazon-bedrock-agentcore)
- [Google Cloud（Cloud Run 和 Vertex AI）](#google-cloud-cloud-run-and-vertex-ai)
- [贡献](#contributing)
- [贡献者入门指南](#getting-started-for-contributors)
- [运行测试](#running-tests)
- [开发者文档](#developer-documentation)
- [许可证](#license)
- [支持](#support)
## API 凭证与所需权限范围
### 设置 CrowdStrike API 凭证
在使用 Falcon MCP Server 之前，您需要在 CrowdStrike 控制台中创建 API 凭证：
1. **登录您的 CrowdStrike 控制台**
2. **导航至 Support > API Clients and Keys**
3. **点击 "Add new API client"**
4. **配置您的 API 客户端**：
- **Client Name**：选择一个描述性名称（例如 "Falcon MCP Server"）
- **Description**：可选的记录描述
- **API Scopes**：根据您计划使用的模块选择权限范围（见下文）
### 各模块所需 API 权限范围
Falcon MCP Server 支持不同的模块，每个模块需要特定的 API 权限范围：
| 模块 | 所需 API 权限范围 | 用途 |
| - | - | - |
| **Cloud Security** | `Falcon Container Image:read`
`Cloud Security API Assets:Read` | 查找和分析 Kubernetes 容器清单、容器镜像漏洞以及 CSPM 云资产清单 | | **Core** | _无需额外权限_ | 基本连接性和系统信息 | | **Custom IOA** | `Custom IOA Rules:read`
`Custom IOA Rules:write` | 创建和管理自定义 IOA 行为检测规则及规则组 | | **Detections** | `Alerts:read` | 查找和分析检测以了解恶意活动 | | **Discover** | `Assets:read` | 在您的环境中搜索和分析应用程序清单 | | **Hosts** | `Hosts:read` | 管理和查询主机/设备信息 | | **Identity Protection** | `Identity Protection Entities:read`
`Identity Protection Timeline:read`
`Identity Protection Detections:read`
`Identity Protection Assessment:read`
`Identity Protection GraphQL:write` | 全面的实体调查和身份保护分析 | | **Incidents** | `Incidents:read` | 分析安全事件和协同活动 | | **NGSIEM** | `NGSIEM:read`
`NGSIEM:write` | 针对 Next-Gen SIEM 执行 CQL 查询 | | **Intel** | `Actors (Falcon Intelligence):read`
`Indicators (Falcon Intelligence):read`
`Reports (Falcon Intelligence):read` | 研究威胁行为者、IOC 和情报报告 | | **IOC** | `IOC Management:read`
`IOC Management:write` | 使用 IOC Service Collection 端点搜索、创建和删除自定义 IOC | | **Firewall Management** | `Firewall Management:read`
`Firewall Management:write` | 搜索和管理防火墙规则及规则组 | | **Scheduled Reports** | `Scheduled Reports:read` | 获取计划报告和搜索的详细信息、按需运行报告以及下载报告文件 | | **Sensor Usage** | `Sensor Usage:read` | 访问和分析传感器使用数据 | | **Serverless** | `Falcon Container Image:read` | 搜索跨云服务提供商的 Serverless 函数中的漏洞 | | **Spotlight** | `Vulnerabilities:read` | 管理和分析漏洞数据及安全评估 | ## 可用模块、工具与资源 **关于工具与资源**：本服务器同时提供工具（您可以执行的操作）和资源（文档和上下文）。工具执行诸如搜索检测或分析威胁等操作，而资源提供全面的文档（如 FQL 查询指南），AI 助手可以参考这些文档获取上下文，而无需调用工具。 ### 云安全模块 **所需 API 权限范围**： - `Falcon Container Image:read`（用于 Kubernetes 容器和镜像漏洞） - `Cloud Security API Assets:Read`（用于 CSPM 资产清单） 提供用于访问和分析 CrowdStrike Cloud Security 资源的工具： - `falcon_search_kubernetes_containers`：从 CrowdStrike Kubernetes & Containers 清单中搜索容器 - `falcon_count_kubernetes_containers`：根据过滤条件统计 CrowdStrike Kubernetes & Containers 清单中的容器 - `falcon_search_images_vulnerabilities`：从 CrowdStrike Image Assessments 搜索镜像漏洞 - `falcon_search_cspm_assets`：在 CSPM 清单中搜索云资产，支持全面的 FQL 过滤（资源类型、标签、合规性、安全态势） **资源**： - `falcon://cloud/kubernetes-containers/fql-guide`：用于 Kubernetes 容器搜索的全面 FQL 文档和示例 - `falcon://cloud/images-vulnerabilities/fql-guide`：用于镜像漏洞搜索的全面 FQL 文档和示例 - `falcon://cloud/cspm-assets/fql-guide`：用于 CSPM 资产搜索的全面 FQL 文档和示例，支持按资源类型、标签、合规性和安全态势过滤 **使用场景**：管理 Kubernetes 容器清单、容器镜像漏洞分析、基于标签过滤的云资产清单（用于合规性和成本管理） ### 核心功能（内置于服务器） **API 权限范围**：_除基本 API 访问权限外无需其他权限_ 服务器提供用于与 Falcon API 交互的核心工具： - `falcon_check_connectivity`：检查与 Falcon API 的连接性 - `falcon_list_enabled_modules`：列出 falcon-mcp 服务器中已启用的模块 - `falcon_list_modules`：列出 falcon-mcp 服务器中所有可用的模块 ### 自定义 IOA 模块 **所需 API 权限范围**： - `Custom IOA Rules:read` - `Custom IOA Rules:write` 提供用于管理自定义 IOA (Indicators of Attack) 行为检测规则和规则组的工具： - `search_ioa_rule_groups`：搜索自定义 IOA 规则组并返回包含其规则的完整详细信息 - `get_ioa_platforms`：获取自定义 IOA 规则组的所有可用平台 - `get_ioa_rule_types`：获取所有可用的自定义 IOA 规则类型及其字段和处置 ID - `create_ioa_rule_group`：为特定平台创建新的自定义 IOA 规则组 - `update_ioa_rule_group`：更新现有的自定义 IOA 规则组（名称、描述、启用状态） - `delete_ioa_rule_groups`：根据 ID 删除自定义 IOA 规则组 - `create_ioa_rule`：在规则组内创建新的行为检测规则 - `update_ioa_rule`：更新现有的行为检测规则 - `delete_ioa_rules`：从规则组中删除行为检测规则 **资源**： - `falcon://custom-ioa/rule-groups/fql-guide`：用于 IOA 规则组搜索的 FQL 文档和示例 **使用场景**：自定义行为检测管理、IOA 规则生命周期、特定平台检测规则、安全策略执行 ### 检测模块 **所需 API 权限范围**：`Alerts:read` 提供用于访问和分析 CrowdStrike Falcon 检测的工具： - `falcon_search_detections`：查找并分析检测，以了解您环境中的恶意活动 - `falcon_get_detection_details`：获取特定检测 ID 的全面检测详细信息，以了解安全威胁 **资源**： - `falcon://detections/search/fql-guide`：用于检测搜索的全面 FQL 文档和示例 **使用场景**：威胁狩猎、安全分析、事件响应、恶意软件调查 ### 发现模块 **所需 API 权限范围**：`Assets:read` 提供用于访问和管理 CrowdStrike Falcon Discover 应用程序和非受管资产的工具： - `falcon_search_applications`：在您的 CrowdStrike 环境中搜索应用程序 - `falcon_search_unmanaged_assets`：搜索非受管资产（未安装 Falcon sensor 的系统），这些资产是由受管系统发现的 **资源**： - `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 文档和示例 **使用场景**：资产管理、设备清单、主机监控、合规性报告 ### 身份保护模块 **所需 API 权限范围**：`Identity Protection Entities:read`, `Identity Protection Timeline:read`, `Identity Protection Detections:read`, `Identity Protection Assessment:read`, `Identity Protection GraphQL:write` 提供用于访问和管理 CrowdStrike Falcon Identity Protection 功能的工具： - `idp_investigate_entity`：用于分析用户、端点和其他实体的实体调查工具，支持时间线分析、关系映射和风险评估 **使用场景**：实体调查、身份保护分析、用户行为分析、端点安全评估、关系映射、风险评估 ### 事件模块 **所需 API 权限范围**：`Incidents:read` 提供用于访问和分析 CrowdStrike Falcon 事件的工具： - `falcon_show_crowd_score`：查看为您环境计算的 CrowdScore 和安全态势指标 - `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 文档和示例 **使用场景**：事件管理、威胁评估、攻击模式分析、安全态势监控 ### NGSIEM 模块 **所需 API 权限范围**：`NGSIEM:read`, `NGSIEM:write` 提供用于针对 CrowdStrike 的 Next-Gen SIEM 执行 CQL 查询的工具： - `search_ngsiem`：针对 Next-Gen SIEM 仓库执行 CQL 查询 **使用场景**：日志搜索和分析、事件关联、使用自定义 CQL 查询进行威胁狩猎、安全监控 ### 情报模块 **所需 API 权限范围**： - `Actors (Falcon Intelligence):read` - `Indicators (Falcon Intelligence):read` - `Reports (Falcon Intelligence):read` 提供用于访问和分析 CrowdStrike Intelligence 的工具： - `falcon_search_actors`：研究 CrowdStrike 情报追踪的威胁行为者和对手组织 - `falcon_search_indicators`：从 CrowdStrike 情报中搜索威胁指标和妥协指标 (IOC) - `falcon_search_reports`：访问 CrowdStrike 情报出版物和威胁报告 - `falcon_get_mitre_report`：为威胁行为者生成 MITRE ATT&CK 报告，以 JSON 或 CSV 格式提供详细的战术、技术和过程 (TTP) **资源**： - `falcon://intel/actors/fql-guide`：用于威胁行为者搜索的全面 FQL 文档和示例 - `falcon://intel/indicators/fql-guide`：用于指标搜索的全面 FQL 文档和示例 - `falcon://intel/reports/fql-guide`：用于情报报告搜索的全面 FQL 文档和示例 **使用场景**：威胁情报研究、对手追踪、IOC 分析、威胁态势评估、MITRE ATT&CK 框架分析 ### IOC 模块 **所需 API 权限范围**： - `IOC Management:read` - `IOC Management:write` 提供用于通过 Falcon IOC Service Collection 端点管理自定义妥协指标 (IOC) 的工具： - `falcon_search_iocs`：使用 FQL 搜索自定义 IOC 并返回完整的 IOC 详细信息 - `falcon_add_ioc`：创建一个 IOC 或在单个请求中提交多个 IOC - `falcon_remove_iocs`：通过显式 ID 或 FQL 过滤器删除 IOC，用于批量清理 **资源**： - `falcon://ioc/search/fql-guide`：用于 IOC 搜索的 FQL 文档和示例 **使用场景**：IOC 生命周期管理、自动化 IOC 导入、IOC 清理和维护工作流 ### 防火墙管理模块 **所需 API 权限范围**： - `Firewall Management:read` - `Firewall Management:write` 提供用于搜索和管理 Falcon 防火墙规则实体的工具： - `falcon_search_firewall_rules`：搜索防火墙规则并返回完整的规则详细信息 - `falcon_search_firewall_rule_groups`：搜索防火墙规则组并返回完整的组详细信息 - `falcon_search_firewall_policy_rules`：在特定策略容器内搜索规则 - `falcon_create_firewall_rule_group`：使用便捷字段或完整负载主体创建防火墙规则组 - `falcon_delete_firewall_rule_groups`：根据 ID 删除防火墙规则组 **资源**： - `falcon://firewall/rules/fql-guide`：用于防火墙规则搜索的 FQL 文档和示例 **使用场景**：防火墙策略维护、规则组生命周期管理、规则审计、特定策略规则分析 ### 传感器使用模块 **所需 API 权限范围**：`Sensor Usage:read` 提供用于访问和分析 CrowdStrike Falcon 传感器使用数据的工具： - `falcon_search_sensor_usage`：在您的 CrowdStrike 环境中搜索每周传感器使用数据 **资源**： - `falcon://sensor-usage/weekly/fql-guide`：用于传感器使用搜索的全面 FQL 文档和示例 **使用场景**：传感器部署监控、许可证利用率分析、传感器健康追踪 ### 计划报告模块 **所需 API 权限范围**：`Scheduled Reports:read` 提供用于访问和管理 CrowdStrike Falcon 计划报告和计划搜索的工具： - `falcon_search_scheduled_reports`：在您的 CrowdStrike 环境中搜索计划报告和搜索 - `falcon_launch_scheduled_report`：在定期计划之外按需启动计划报告 - `falcon_search_report_executions`：搜索报告执行情况以跟踪状态和结果 - `falcon_download_report_execution`：下载生成的报告文件 **资源**： - `falcon://scheduled-reports/search/fql-guide`：用于搜索计划报告实体的全面 FQL 文档 - `falcon://scheduled-reports/executions/search/fql-guide`：用于搜索报告执行的全面 FQL 文档 **使用场景**：自动化报告管理、报告执行监控、计划搜索分析、报告下载自动化 ### Serverless 模块 **所需 API 权限范围**：`Falcon Container Image:read` 提供用于访问和管理 CrowdStrike Falcon Serverless 漏洞的工具： - `falcon_search_serverless_vulnerabilities`：搜索跨所有云服务提供商的 Serverless 函数中的漏洞 **资源**： - `falcon://serverless/vulnerabilities/fql-guide`：用于 Serverless 漏洞搜索的全面 FQL 文档和示例 **使用场景**：Serverless 安全评估、漏洞管理、云安全监控 ### Spotlight 模块 **所需 API 权限范围**：`Vulnerabilities:read` 提供用于访问和管理 CrowdStrike Spotlight 漏洞的工具： - `falcon_search_vulnerabilities`：在您的 CrowdStrike 环境中搜索漏洞 **资源**： - `falcon://spotlight/vulnerabilities/fql-guide`：用于漏洞搜索的全面 FQL 文档和示例 **使用场景**：漏洞管理、安全评估、合规性报告、风险分析、补丁优先级排序 ## 安装与设置 ### 前置条件 - Python 3.11 或更高版本 - [`uv`](https://docs.astral.sh/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_MEMBER_CID=your-child-cid # Flight Control child CID #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 #FALCON_MCP_STATELESS_HTTP=false #FALCON_MCP_API_KEY=your-api-key ``` #### 环境变量 或者，您可以直接使用环境变量。 在您的 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_MEMBER_CID="your-child-cid" # Flight Control child CID export FALCON_MCP_MODULES="detections,incidents,intel" # Comma-separated list (default: all modules) export FALCON_MCP_TRANSPORT="stdio" # Transport method: stdio, sse, streamable-http export FALCON_MCP_DEBUG="false" # Enable debug logging: true, false export FALCON_MCP_HOST="127.0.0.1" # Host for HTTP transports export FALCON_MCP_PORT="8000" # Port for HTTP transports export FALCON_MCP_STATELESS_HTTP="false" # Stateless mode for scalable deployments export FALCON_MCP_API_KEY="your-api-key" # API key for HTTP transport auth (x-api-key header) ``` ### Flight Control (MSSP) 支持 falcon-mcp 支持 CrowdStrike Flight Control 用于 MSSP (Managed Security Service Provider) 环境。使用父 CID API 凭证配合 `--member-cid` 标志或 `FALCON_MEMBER_CID` 环境变量来定位特定的子 CID。 #### 配置 **环境变量**： ``` export FALCON_MEMBER_CID="abc123-child-cid-xyz" falcon-mcp ``` **命令行标志**： ``` falcon-mcp --member-cid "abc123-child-cid-xyz" ``` **在 `.env` 文件中**： ``` # Parent CID 凭据（必需） FALCON_CLIENT_ID=parent-client-id FALCON_CLIENT_SECRET=parent-client-secret # 目标 Child CID（可选 - 用于 Flight Control） FALCON_MEMBER_CID=abc123-child-cid-xyz ``` #### 要求 - 父 CID API 凭证（使用父级的 `FALCON_CLIENT_ID` 和 `FALCON_CLIENT_SECRET`） - 父租户上已启用 Flight Control - 有效的子 CID 标识符 - 父 API 客户端必须拥有对子 CID 进行操作的适当权限范围 #### 行为 - **会话级别**：服务器实例中的所有工具都针对指定的子 CID - **无法在会话中途切换**：member_cid 在认证期间设置，并在服务器的生命周期内持续有效 - **多个子 CID**：要查询多个子 CID，请运行独立的服务器实例 #### 多租户工作流示例 要同时处理多个子 CID，请运行独立的服务器实例： ``` # Parent CID（默认） falcon-mcp --transport streamable-http --port 8000 # Child CID 1 falcon-mcp --member-cid "child-cid-1" --transport streamable-http --port 8001 # Child CID 2 falcon-mcp --member-cid "child-cid-2" --transport streamable-http --port 8002 ``` 每个实例维护其自己的认证上下文，并且可以由您的 MCP 客户端独立访问。 **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 ``` 有关通过代码编辑器/助手安装，请参阅下文的 [编辑器/助手](#editorassistant-integration) 部分 ## 用法 ### 命令行 使用默认设置运行服务器（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 ``` 以无状态 HTTP 模式运行（用于 AWS AgentCore 等可扩展部署）： ``` falcon-mcp --transport streamable-http --stateless-http ``` 使用 API 密钥认证运行（推荐用于 HTTP 传输）： ``` falcon-mcp --transport streamable-http --api-key your-secret-key ``` ### 模块配置 Falcon MCP Server 支持多种方式指定要启用的模块： #### 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. 默认行为（所有模块） 如果未通过命令行或环境变量指定模块，则默认启用所有可用模块。 **模块优先级顺序：** 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", # Optional, defaults to env var debug=True, # Optional, enable debug logging enabled_modules=["detections", "incidents", "spotlight", "idp"], # Optional, defaults to all modules api_key="your-api-key" # Optional: API key for HTTP transport auth ) # 使用 stdio transport 运行（默认） server.run() # 或使用 SSE transport 运行 server.run("sse") # 或使用 streamable-http transport 运行 server.run("streamable-http") # 或使用 streamable-http transport 在自定义 host/port 上运行 server = FalconMCPServer(host="0.0.0.0", port=8080) server.run("streamable-http") ``` #### 直接凭证（密钥管理集成） 对于使用密钥管理系统（HashiCorp Vault、AWS Secrets Manager 等）的企业部署，您可以直接传递凭证，而无需使用环境变量： ``` from falcon_mcp.server import FalconMCPServer # 示例：从 secrets manager 检索凭据 # client_id = vault.read_secret("crowdstrike/client_id") # client_secret = vault.read_secret("crowdstrike/client_secret") # 使用直接凭据创建服务器 server = FalconMCPServer( client_id="your-client-id", # Or retrieved from vault/secrets manager client_secret="your-client-secret", # Or retrieved from vault/secrets manager base_url="https://api.us-2.crowdstrike.com", # Optional enabled_modules=["detections", "incidents"] # Optional ) server.run() ``` ### 运行示例 ``` # 使用 stdio transport 运行 python examples/basic_usage.py # 使用 SSE transport 运行 python examples/sse_usage.py # 使用 streamable-http transport 运行 python examples/streamable_http_usage.py ``` ## 容器使用 Falcon MCP Server 以预构建容器镜像的形式提供，便于部署： ### 使用预构建镜像（推荐） ``` # 拉取最新的预构建 image docker pull quay.io/crowdstrike/falcon-mcp:latest # 使用 .env 文件运行（推荐） docker run -i --rm --env-file /path/to/.env quay.io/crowdstrike/falcon-mcp:latest # 使用 .env 文件和 SSE transport 运行 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 transport 运行 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 文件和特定模块运行（stdio transport - 需要 -i flag） docker run -i --rm --env-file /path/to/.env \ quay.io/crowdstrike/falcon-mcp:latest --modules detections,incidents,spotlight,idp # 使用特定版本代替 latest（stdio transport - 需要 -i flag） docker run -i --rm --env-file /path/to/.env \ quay.io/crowdstrike/falcon-mcp:1.2.3 # 替代方案：单独的环境变量（stdio transport - 需要 -i flag） docker run -i --rm -e FALCON_CLIENT_ID=your_client_id -e FALCON_CLIENT_SECRET=your_secret \ quay.io/crowdstrike/falcon-mcp:latest ``` ### 本地构建（开发） 出于开发或定制目的，您可以在本地构建镜像： ``` # 构建 Docker image docker build -t falcon-mcp . # 运行本地构建的 image docker run --rm -e FALCON_CLIENT_ID=your_client_id -e FALCON_CLIENT_SECRET=your_secret falcon-mcp ``` ## 编辑器/助手集成 您可以将 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 Server 作为工具部署在 Amazon Bedrock AgentCore 中，请参考[以下文档](./docs/deployment/amazon_bedrock_agentcore.md)。 ### Google Cloud（Cloud Run 和 Vertex AI） 要将 MCP 服务器作为代理部署在 Cloud Run 或 Vertex AI Agent Engine 中（包括在 Agentspace 中注册），请参考 [Google ADK 示例](./examples/adk/README.md)。 ### Gemini CLI 1. 安装 `uv` 2. `gemini extensions install https://github.com/CrowdStrike/falcon-mcp` 3. 将有效的 `.env` 文件复制到 `~/.gemini/extensions/falcon-mcp/.env` ## 贡献 ### 贡献者入门指南 1. 克隆仓库： git clone https://github.com/CrowdStrike/falcon-mcp.git cd falcon-mcp 2. 以开发模式安装： # 创建 .venv 并安装依赖 uv sync --all-extras # 激活 venv source .venv/bin/activate ### 运行测试 ``` # 运行所有单元测试 pytest # 运行端到端测试（需要 API 凭据） pytest --run-e2e tests/e2e/ # 运行带详细输出的端到端测试（注意：需要 -s 才能看到输出） pytest --run-e2e -v -s tests/e2e/ # 运行集成测试（需要 API 凭据） pytest --run-integration tests/integration/ # 运行带详细输出的集成测试 pytest --run-integration -v -s tests/integration/ # 运行特定模块的集成测试 pytest --run-integration tests/integration/test_detections.py ``` #### 集成测试 集成测试会发起真实的 API 调用，以验证 FalconPy 操作名称、HTTP 方法和响应模式。它们能发现模拟单元测试无法检测到的问题： - 错误的 FalconPy 操作名称（拼写错误） - HTTP 方法不匹配（POST 主体与 GET 查询参数） - 两步搜索模式未返回完整详细信息 - API 响应模式变更 **要求**：必须配置有效的 CrowdStrike API 凭证（参见 [环境配置](#environment-configuration))。 ### 开发者文档 - [模块开发指南](docs/development/module_development.md)：实现新模块的说明 - [资源开发指南](
`Cloud Security API Assets:Read` | 查找和分析 Kubernetes 容器清单、容器镜像漏洞以及 CSPM 云资产清单 | | **Core** | _无需额外权限_ | 基本连接性和系统信息 | | **Custom IOA** | `Custom IOA Rules:read`
`Custom IOA Rules:write` | 创建和管理自定义 IOA 行为检测规则及规则组 | | **Detections** | `Alerts:read` | 查找和分析检测以了解恶意活动 | | **Discover** | `Assets:read` | 在您的环境中搜索和分析应用程序清单 | | **Hosts** | `Hosts:read` | 管理和查询主机/设备信息 | | **Identity Protection** | `Identity Protection Entities:read`
`Identity Protection Timeline:read`
`Identity Protection Detections:read`
`Identity Protection Assessment:read`
`Identity Protection GraphQL:write` | 全面的实体调查和身份保护分析 | | **Incidents** | `Incidents:read` | 分析安全事件和协同活动 | | **NGSIEM** | `NGSIEM:read`
`NGSIEM:write` | 针对 Next-Gen SIEM 执行 CQL 查询 | | **Intel** | `Actors (Falcon Intelligence):read`
`Indicators (Falcon Intelligence):read`
`Reports (Falcon Intelligence):read` | 研究威胁行为者、IOC 和情报报告 | | **IOC** | `IOC Management:read`
`IOC Management:write` | 使用 IOC Service Collection 端点搜索、创建和删除自定义 IOC | | **Firewall Management** | `Firewall Management:read`
`Firewall Management:write` | 搜索和管理防火墙规则及规则组 | | **Scheduled Reports** | `Scheduled Reports:read` | 获取计划报告和搜索的详细信息、按需运行报告以及下载报告文件 | | **Sensor Usage** | `Sensor Usage:read` | 访问和分析传感器使用数据 | | **Serverless** | `Falcon Container Image:read` | 搜索跨云服务提供商的 Serverless 函数中的漏洞 | | **Spotlight** | `Vulnerabilities:read` | 管理和分析漏洞数据及安全评估 | ## 可用模块、工具与资源 **关于工具与资源**：本服务器同时提供工具（您可以执行的操作）和资源（文档和上下文）。工具执行诸如搜索检测或分析威胁等操作，而资源提供全面的文档（如 FQL 查询指南），AI 助手可以参考这些文档获取上下文，而无需调用工具。 ### 云安全模块 **所需 API 权限范围**： - `Falcon Container Image:read`（用于 Kubernetes 容器和镜像漏洞） - `Cloud Security API Assets:Read`（用于 CSPM 资产清单） 提供用于访问和分析 CrowdStrike Cloud Security 资源的工具： - `falcon_search_kubernetes_containers`：从 CrowdStrike Kubernetes & Containers 清单中搜索容器 - `falcon_count_kubernetes_containers`：根据过滤条件统计 CrowdStrike Kubernetes & Containers 清单中的容器 - `falcon_search_images_vulnerabilities`：从 CrowdStrike Image Assessments 搜索镜像漏洞 - `falcon_search_cspm_assets`：在 CSPM 清单中搜索云资产，支持全面的 FQL 过滤（资源类型、标签、合规性、安全态势） **资源**： - `falcon://cloud/kubernetes-containers/fql-guide`：用于 Kubernetes 容器搜索的全面 FQL 文档和示例 - `falcon://cloud/images-vulnerabilities/fql-guide`：用于镜像漏洞搜索的全面 FQL 文档和示例 - `falcon://cloud/cspm-assets/fql-guide`：用于 CSPM 资产搜索的全面 FQL 文档和示例，支持按资源类型、标签、合规性和安全态势过滤 **使用场景**：管理 Kubernetes 容器清单、容器镜像漏洞分析、基于标签过滤的云资产清单（用于合规性和成本管理） ### 核心功能（内置于服务器） **API 权限范围**：_除基本 API 访问权限外无需其他权限_ 服务器提供用于与 Falcon API 交互的核心工具： - `falcon_check_connectivity`：检查与 Falcon API 的连接性 - `falcon_list_enabled_modules`：列出 falcon-mcp 服务器中已启用的模块 - `falcon_list_modules`：列出 falcon-mcp 服务器中所有可用的模块 ### 自定义 IOA 模块 **所需 API 权限范围**： - `Custom IOA Rules:read` - `Custom IOA Rules:write` 提供用于管理自定义 IOA (Indicators of Attack) 行为检测规则和规则组的工具： - `search_ioa_rule_groups`：搜索自定义 IOA 规则组并返回包含其规则的完整详细信息 - `get_ioa_platforms`：获取自定义 IOA 规则组的所有可用平台 - `get_ioa_rule_types`：获取所有可用的自定义 IOA 规则类型及其字段和处置 ID - `create_ioa_rule_group`：为特定平台创建新的自定义 IOA 规则组 - `update_ioa_rule_group`：更新现有的自定义 IOA 规则组（名称、描述、启用状态） - `delete_ioa_rule_groups`：根据 ID 删除自定义 IOA 规则组 - `create_ioa_rule`：在规则组内创建新的行为检测规则 - `update_ioa_rule`：更新现有的行为检测规则 - `delete_ioa_rules`：从规则组中删除行为检测规则 **资源**： - `falcon://custom-ioa/rule-groups/fql-guide`：用于 IOA 规则组搜索的 FQL 文档和示例 **使用场景**：自定义行为检测管理、IOA 规则生命周期、特定平台检测规则、安全策略执行 ### 检测模块 **所需 API 权限范围**：`Alerts:read` 提供用于访问和分析 CrowdStrike Falcon 检测的工具： - `falcon_search_detections`：查找并分析检测，以了解您环境中的恶意活动 - `falcon_get_detection_details`：获取特定检测 ID 的全面检测详细信息，以了解安全威胁 **资源**： - `falcon://detections/search/fql-guide`：用于检测搜索的全面 FQL 文档和示例 **使用场景**：威胁狩猎、安全分析、事件响应、恶意软件调查 ### 发现模块 **所需 API 权限范围**：`Assets:read` 提供用于访问和管理 CrowdStrike Falcon Discover 应用程序和非受管资产的工具： - `falcon_search_applications`：在您的 CrowdStrike 环境中搜索应用程序 - `falcon_search_unmanaged_assets`：搜索非受管资产（未安装 Falcon sensor 的系统），这些资产是由受管系统发现的 **资源**： - `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 文档和示例 **使用场景**：资产管理、设备清单、主机监控、合规性报告 ### 身份保护模块 **所需 API 权限范围**：`Identity Protection Entities:read`, `Identity Protection Timeline:read`, `Identity Protection Detections:read`, `Identity Protection Assessment:read`, `Identity Protection GraphQL:write` 提供用于访问和管理 CrowdStrike Falcon Identity Protection 功能的工具： - `idp_investigate_entity`：用于分析用户、端点和其他实体的实体调查工具，支持时间线分析、关系映射和风险评估 **使用场景**：实体调查、身份保护分析、用户行为分析、端点安全评估、关系映射、风险评估 ### 事件模块 **所需 API 权限范围**：`Incidents:read` 提供用于访问和分析 CrowdStrike Falcon 事件的工具： - `falcon_show_crowd_score`：查看为您环境计算的 CrowdScore 和安全态势指标 - `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 文档和示例 **使用场景**：事件管理、威胁评估、攻击模式分析、安全态势监控 ### NGSIEM 模块 **所需 API 权限范围**：`NGSIEM:read`, `NGSIEM:write` 提供用于针对 CrowdStrike 的 Next-Gen SIEM 执行 CQL 查询的工具： - `search_ngsiem`：针对 Next-Gen SIEM 仓库执行 CQL 查询 **使用场景**：日志搜索和分析、事件关联、使用自定义 CQL 查询进行威胁狩猎、安全监控 ### 情报模块 **所需 API 权限范围**： - `Actors (Falcon Intelligence):read` - `Indicators (Falcon Intelligence):read` - `Reports (Falcon Intelligence):read` 提供用于访问和分析 CrowdStrike Intelligence 的工具： - `falcon_search_actors`：研究 CrowdStrike 情报追踪的威胁行为者和对手组织 - `falcon_search_indicators`：从 CrowdStrike 情报中搜索威胁指标和妥协指标 (IOC) - `falcon_search_reports`：访问 CrowdStrike 情报出版物和威胁报告 - `falcon_get_mitre_report`：为威胁行为者生成 MITRE ATT&CK 报告，以 JSON 或 CSV 格式提供详细的战术、技术和过程 (TTP) **资源**： - `falcon://intel/actors/fql-guide`：用于威胁行为者搜索的全面 FQL 文档和示例 - `falcon://intel/indicators/fql-guide`：用于指标搜索的全面 FQL 文档和示例 - `falcon://intel/reports/fql-guide`：用于情报报告搜索的全面 FQL 文档和示例 **使用场景**：威胁情报研究、对手追踪、IOC 分析、威胁态势评估、MITRE ATT&CK 框架分析 ### IOC 模块 **所需 API 权限范围**： - `IOC Management:read` - `IOC Management:write` 提供用于通过 Falcon IOC Service Collection 端点管理自定义妥协指标 (IOC) 的工具： - `falcon_search_iocs`：使用 FQL 搜索自定义 IOC 并返回完整的 IOC 详细信息 - `falcon_add_ioc`：创建一个 IOC 或在单个请求中提交多个 IOC - `falcon_remove_iocs`：通过显式 ID 或 FQL 过滤器删除 IOC，用于批量清理 **资源**： - `falcon://ioc/search/fql-guide`：用于 IOC 搜索的 FQL 文档和示例 **使用场景**：IOC 生命周期管理、自动化 IOC 导入、IOC 清理和维护工作流 ### 防火墙管理模块 **所需 API 权限范围**： - `Firewall Management:read` - `Firewall Management:write` 提供用于搜索和管理 Falcon 防火墙规则实体的工具： - `falcon_search_firewall_rules`：搜索防火墙规则并返回完整的规则详细信息 - `falcon_search_firewall_rule_groups`：搜索防火墙规则组并返回完整的组详细信息 - `falcon_search_firewall_policy_rules`：在特定策略容器内搜索规则 - `falcon_create_firewall_rule_group`：使用便捷字段或完整负载主体创建防火墙规则组 - `falcon_delete_firewall_rule_groups`：根据 ID 删除防火墙规则组 **资源**： - `falcon://firewall/rules/fql-guide`：用于防火墙规则搜索的 FQL 文档和示例 **使用场景**：防火墙策略维护、规则组生命周期管理、规则审计、特定策略规则分析 ### 传感器使用模块 **所需 API 权限范围**：`Sensor Usage:read` 提供用于访问和分析 CrowdStrike Falcon 传感器使用数据的工具： - `falcon_search_sensor_usage`：在您的 CrowdStrike 环境中搜索每周传感器使用数据 **资源**： - `falcon://sensor-usage/weekly/fql-guide`：用于传感器使用搜索的全面 FQL 文档和示例 **使用场景**：传感器部署监控、许可证利用率分析、传感器健康追踪 ### 计划报告模块 **所需 API 权限范围**：`Scheduled Reports:read` 提供用于访问和管理 CrowdStrike Falcon 计划报告和计划搜索的工具： - `falcon_search_scheduled_reports`：在您的 CrowdStrike 环境中搜索计划报告和搜索 - `falcon_launch_scheduled_report`：在定期计划之外按需启动计划报告 - `falcon_search_report_executions`：搜索报告执行情况以跟踪状态和结果 - `falcon_download_report_execution`：下载生成的报告文件 **资源**： - `falcon://scheduled-reports/search/fql-guide`：用于搜索计划报告实体的全面 FQL 文档 - `falcon://scheduled-reports/executions/search/fql-guide`：用于搜索报告执行的全面 FQL 文档 **使用场景**：自动化报告管理、报告执行监控、计划搜索分析、报告下载自动化 ### Serverless 模块 **所需 API 权限范围**：`Falcon Container Image:read` 提供用于访问和管理 CrowdStrike Falcon Serverless 漏洞的工具： - `falcon_search_serverless_vulnerabilities`：搜索跨所有云服务提供商的 Serverless 函数中的漏洞 **资源**： - `falcon://serverless/vulnerabilities/fql-guide`：用于 Serverless 漏洞搜索的全面 FQL 文档和示例 **使用场景**：Serverless 安全评估、漏洞管理、云安全监控 ### Spotlight 模块 **所需 API 权限范围**：`Vulnerabilities:read` 提供用于访问和管理 CrowdStrike Spotlight 漏洞的工具： - `falcon_search_vulnerabilities`：在您的 CrowdStrike 环境中搜索漏洞 **资源**： - `falcon://spotlight/vulnerabilities/fql-guide`：用于漏洞搜索的全面 FQL 文档和示例 **使用场景**：漏洞管理、安全评估、合规性报告、风险分析、补丁优先级排序 ## 安装与设置 ### 前置条件 - Python 3.11 或更高版本 - [`uv`](https://docs.astral.sh/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_MEMBER_CID=your-child-cid # Flight Control child CID #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 #FALCON_MCP_STATELESS_HTTP=false #FALCON_MCP_API_KEY=your-api-key ``` #### 环境变量 或者，您可以直接使用环境变量。 在您的 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_MEMBER_CID="your-child-cid" # Flight Control child CID export FALCON_MCP_MODULES="detections,incidents,intel" # Comma-separated list (default: all modules) export FALCON_MCP_TRANSPORT="stdio" # Transport method: stdio, sse, streamable-http export FALCON_MCP_DEBUG="false" # Enable debug logging: true, false export FALCON_MCP_HOST="127.0.0.1" # Host for HTTP transports export FALCON_MCP_PORT="8000" # Port for HTTP transports export FALCON_MCP_STATELESS_HTTP="false" # Stateless mode for scalable deployments export FALCON_MCP_API_KEY="your-api-key" # API key for HTTP transport auth (x-api-key header) ``` ### Flight Control (MSSP) 支持 falcon-mcp 支持 CrowdStrike Flight Control 用于 MSSP (Managed Security Service Provider) 环境。使用父 CID API 凭证配合 `--member-cid` 标志或 `FALCON_MEMBER_CID` 环境变量来定位特定的子 CID。 #### 配置 **环境变量**： ``` export FALCON_MEMBER_CID="abc123-child-cid-xyz" falcon-mcp ``` **命令行标志**： ``` falcon-mcp --member-cid "abc123-child-cid-xyz" ``` **在 `.env` 文件中**： ``` # Parent CID 凭据（必需） FALCON_CLIENT_ID=parent-client-id FALCON_CLIENT_SECRET=parent-client-secret # 目标 Child CID（可选 - 用于 Flight Control） FALCON_MEMBER_CID=abc123-child-cid-xyz ``` #### 要求 - 父 CID API 凭证（使用父级的 `FALCON_CLIENT_ID` 和 `FALCON_CLIENT_SECRET`） - 父租户上已启用 Flight Control - 有效的子 CID 标识符 - 父 API 客户端必须拥有对子 CID 进行操作的适当权限范围 #### 行为 - **会话级别**：服务器实例中的所有工具都针对指定的子 CID - **无法在会话中途切换**：member_cid 在认证期间设置，并在服务器的生命周期内持续有效 - **多个子 CID**：要查询多个子 CID，请运行独立的服务器实例 #### 多租户工作流示例 要同时处理多个子 CID，请运行独立的服务器实例： ``` # Parent CID（默认） falcon-mcp --transport streamable-http --port 8000 # Child CID 1 falcon-mcp --member-cid "child-cid-1" --transport streamable-http --port 8001 # Child CID 2 falcon-mcp --member-cid "child-cid-2" --transport streamable-http --port 8002 ``` 每个实例维护其自己的认证上下文，并且可以由您的 MCP 客户端独立访问。 **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 ``` 有关通过代码编辑器/助手安装，请参阅下文的 [编辑器/助手](#editorassistant-integration) 部分 ## 用法 ### 命令行 使用默认设置运行服务器（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 ``` 以无状态 HTTP 模式运行（用于 AWS AgentCore 等可扩展部署）： ``` falcon-mcp --transport streamable-http --stateless-http ``` 使用 API 密钥认证运行（推荐用于 HTTP 传输）： ``` falcon-mcp --transport streamable-http --api-key your-secret-key ``` ### 模块配置 Falcon MCP Server 支持多种方式指定要启用的模块： #### 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. 默认行为（所有模块） 如果未通过命令行或环境变量指定模块，则默认启用所有可用模块。 **模块优先级顺序：** 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", # Optional, defaults to env var debug=True, # Optional, enable debug logging enabled_modules=["detections", "incidents", "spotlight", "idp"], # Optional, defaults to all modules api_key="your-api-key" # Optional: API key for HTTP transport auth ) # 使用 stdio transport 运行（默认） server.run() # 或使用 SSE transport 运行 server.run("sse") # 或使用 streamable-http transport 运行 server.run("streamable-http") # 或使用 streamable-http transport 在自定义 host/port 上运行 server = FalconMCPServer(host="0.0.0.0", port=8080) server.run("streamable-http") ``` #### 直接凭证（密钥管理集成） 对于使用密钥管理系统（HashiCorp Vault、AWS Secrets Manager 等）的企业部署，您可以直接传递凭证，而无需使用环境变量： ``` from falcon_mcp.server import FalconMCPServer # 示例：从 secrets manager 检索凭据 # client_id = vault.read_secret("crowdstrike/client_id") # client_secret = vault.read_secret("crowdstrike/client_secret") # 使用直接凭据创建服务器 server = FalconMCPServer( client_id="your-client-id", # Or retrieved from vault/secrets manager client_secret="your-client-secret", # Or retrieved from vault/secrets manager base_url="https://api.us-2.crowdstrike.com", # Optional enabled_modules=["detections", "incidents"] # Optional ) server.run() ``` ### 运行示例 ``` # 使用 stdio transport 运行 python examples/basic_usage.py # 使用 SSE transport 运行 python examples/sse_usage.py # 使用 streamable-http transport 运行 python examples/streamable_http_usage.py ``` ## 容器使用 Falcon MCP Server 以预构建容器镜像的形式提供，便于部署： ### 使用预构建镜像（推荐） ``` # 拉取最新的预构建 image docker pull quay.io/crowdstrike/falcon-mcp:latest # 使用 .env 文件运行（推荐） docker run -i --rm --env-file /path/to/.env quay.io/crowdstrike/falcon-mcp:latest # 使用 .env 文件和 SSE transport 运行 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 transport 运行 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 文件和特定模块运行（stdio transport - 需要 -i flag） docker run -i --rm --env-file /path/to/.env \ quay.io/crowdstrike/falcon-mcp:latest --modules detections,incidents,spotlight,idp # 使用特定版本代替 latest（stdio transport - 需要 -i flag） docker run -i --rm --env-file /path/to/.env \ quay.io/crowdstrike/falcon-mcp:1.2.3 # 替代方案：单独的环境变量（stdio transport - 需要 -i flag） docker run -i --rm -e FALCON_CLIENT_ID=your_client_id -e FALCON_CLIENT_SECRET=your_secret \ quay.io/crowdstrike/falcon-mcp:latest ``` ### 本地构建（开发） 出于开发或定制目的，您可以在本地构建镜像： ``` # 构建 Docker image docker build -t falcon-mcp . # 运行本地构建的 image docker run --rm -e FALCON_CLIENT_ID=your_client_id -e FALCON_CLIENT_SECRET=your_secret falcon-mcp ``` ## 编辑器/助手集成 您可以将 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 Server 作为工具部署在 Amazon Bedrock AgentCore 中，请参考[以下文档](./docs/deployment/amazon_bedrock_agentcore.md)。 ### Google Cloud（Cloud Run 和 Vertex AI） 要将 MCP 服务器作为代理部署在 Cloud Run 或 Vertex AI Agent Engine 中（包括在 Agentspace 中注册），请参考 [Google ADK 示例](./examples/adk/README.md)。 ### Gemini CLI 1. 安装 `uv` 2. `gemini extensions install https://github.com/CrowdStrike/falcon-mcp` 3. 将有效的 `.env` 文件复制到 `~/.gemini/extensions/falcon-mcp/.env` ## 贡献 ### 贡献者入门指南 1. 克隆仓库： git clone https://github.com/CrowdStrike/falcon-mcp.git cd falcon-mcp 2. 以开发模式安装： # 创建 .venv 并安装依赖 uv sync --all-extras # 激活 venv source .venv/bin/activate ### 运行测试 ``` # 运行所有单元测试 pytest # 运行端到端测试（需要 API 凭据） pytest --run-e2e tests/e2e/ # 运行带详细输出的端到端测试（注意：需要 -s 才能看到输出） pytest --run-e2e -v -s tests/e2e/ # 运行集成测试（需要 API 凭据） pytest --run-integration tests/integration/ # 运行带详细输出的集成测试 pytest --run-integration -v -s tests/integration/ # 运行特定模块的集成测试 pytest --run-integration tests/integration/test_detections.py ``` #### 集成测试 集成测试会发起真实的 API 调用，以验证 FalconPy 操作名称、HTTP 方法和响应模式。它们能发现模拟单元测试无法检测到的问题： - 错误的 FalconPy 操作名称（拼写错误） - HTTP 方法不匹配（POST 主体与 GET 查询参数） - 两步搜索模式未返回完整详细信息 - API 响应模式变更 **要求**：必须配置有效的 CrowdStrike API 凭证（参见 [环境配置](#environment-configuration))。 ### 开发者文档 - [模块开发指南](docs/development/module_development.md)：实现新模块的说明 - [资源开发指南](
标签：Agent, AI代理, API集成, CrowdStrike Falcon, DLL 劫持, EDR, GPT, LLM工具, MCP服务器, NGSIEM, Python, SOAR, 可观测性, 大语言模型, 威胁情报, 安全运营, 开发者工具, 扫描框架, 无后门, 模型上下文协议, 漏洞管理, 端点检测与响应, 网络安全, 脆弱性评估, 脱壳工具, 自动化安全分析, 请求拦截, 身份保护, 逆向工具, 隐私保护