CrowdStrike/falcon-mcp
GitHub: CrowdStrike/falcon-mcp
一个基于 MCP 协议的服务器,让 AI 代理能够直接调用 CrowdStrike Falcon 平台进行自动化的安全分析和威胁猎杀。
Stars: 115 | Forks: 37


# 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 代理与 CrowdStrike Falcon 平台,为您的代理工作流提供智能安全分析支持。它提供对核心安全能力(包括检测、事件和行为)的编程访问,为高级安全操作和自动化奠定基础。
## 目录
- [API Credentials \& Required Scopes](#api-credentials--required-scopes)
- [Setting Up CrowdStrike API Credentials](#setting-up-crowdstrike-api-credentials)
- [Required API Scopes by Module](#required-api-scopes-by-module)
- [Available Modules, Tools \& Resources](#available-modules-tools--resources)
- [Cloud Security Module](#cloud-security-module)
- [Core Functionality (Built into Server)](#core-functionality-built-into-server)
- [Detections Module](#detections-module)
- [Discover Module](#discover-module)
- [Hosts Module](#hosts-module)
- [Identity Protection Module](#identity-protection-module)
- [Incidents Module](#incidents-module)
- [NGSIEM Module](#ngsiem-module)
- [Intel Module](#intel-module)
- [IOC Module](#ioc-module)
- [Scheduled Reports Module](#scheduled-reports-module)
- [Sensor Usage Module](#sensor-usage-module)
- [Serverless Module](#serverless-module)
- [Spotlight Module](#spotlight-module)
- [Installation \& Setup](#installation--setup)
- [Prerequisites](#prerequisites)
- [Environment Configuration](#environment-configuration)
- [Installation](#installation)
- [Usage](#usage)
- [Command Line](#command-line)
- [Module Configuration](#module-configuration)
- [Additional Command Line Options](#additional-command-line-options)
- [As a Library](#as-a-library)
- [Running Examples](#running-examples)
- [Container Usage](#container-usage)
- [Using Pre-built Image (Recommended)](#using-pre-built-image-recommended)
- [Building Locally (Development)](#building-locally-development)
- [Editor/Assistant Integration](#editorassistant-integration)
- [Using `uvx` (recommended)](#using-uvx-recommended)
- [With Module Selection](#with-module-selection)
- [Using Individual Environment Variables](#using-individual-environment-variables)
- [Docker Version](#docker-version)
- [Additional Deployment Options](#additional-deployment-options)
- [Amazon Bedrock AgentCore](#amazon-bedrock-agentcore)
- [Google Cloud (Cloud Run and Vertex AI)](#google-cloud-cloud-run-and-vertex-ai)
- [Contributing](#contributing)
- [Getting Started for Contributors](#getting-started-for-contributors)
- [Running Tests](#running-tests)
- [Developer Documentation](#developer-documentation)
- [License](#license)
- [Support](#support)
## API 凭证与所需 Scope
### 设置 CrowdStrike API 凭证
Before using the Falcon MCP Server, you need to create API credentials in your CrowdStrike console:
1. **Log into your CrowdStrike console**
2. **Navigate to Support > API Clients and Keys**
3. **Click "Add new API client"**
4. **Configure your API client**:
- **Client Name**: Choose a descriptive name (e.g., "Falcon MCP Server")
- **Description**: Optional description for your records
- **API Scopes**: Select the scopes based on which modules you plan to use (see below)
### 按模块划分的所需 API Scope
The Falcon MCP Server supports different modules, each requiring specific API scopes:
| Module | Required API Scopes | Purpose |
| - | - | - |
| **Cloud Security** | `Falcon Container Image:read` | Find and analyze kubernetes containers inventory and container imges vulnerabilities |
| **Core** | _No additional scopes_ | Basic connectivity and system information |
| **Detections** | `Alerts:read` | Find and analyze detections to understand malicious activity |
| **Discover** | `Assets:read` | Search and analyze application inventory across your environment |
| **Hosts** | `Hosts:read` | Manage and query host/device information |
| **Identity Protection** | `Identity Protection Entities:read`
`Identity Protection Timeline:read`
`Identity Protection Detections:read`
`Identity Protection Assessment:read`
`Identity Protection GraphQL:write` | Comprehensive entity investigation and identity protection analysis | | **Incidents** | `Incidents:read` | Analyze security incidents and coordinated activities | | **NGSIEM** | `NGSIEM:read`
`NGSIEM:write` | Execute CQL queries against Next-Gen SIEM | | **Intel** | `Actors (Falcon Intelligence):read`
`Indicators (Falcon Intelligence):read`
`Reports (Falcon Intelligence):read` | Research threat actors, IOCs, and intelligence reports | | **IOC** | `IOC Management:read`
`IOC Management:write` | Search, create, and remove custom IOCs using IOC Service Collection endpoints | | **Scheduled Reports** | `Scheduled Reports:read` | Get details about scheduled reports and searches, run reports on demand, and download report files | | **Sensor Usage** | `Sensor Usage:read` | Access and analyze sensor usage data | | **Serverless** | `Falcon Container Image:read` | Search for vulnerabilities in serverless functions across cloud service providers | | **Spotlight** | `Vulnerabilities:read` | Manage and analyze vulnerability data and security assessments | ## 可用模块、工具与资源 **About Tools & Resources**: This server provides both tools (actions you can perform) and resources (documentation and context). Tools execute operations like searching for detections or analyzing threats, while resources provide comprehensive documentation like FQL query guides that AI assistants can reference for context without requiring tool calls. ### Cloud Security 模块 **API Scopes Required**: - `Falcon Container Image:read` Provides tools for accessing and analyzing CrowdStrike Cloud Security resources: - `falcon_search_kubernetes_containers`: Search for containers from CrowdStrike Kubernetes & Containers inventory - `falcon_count_kubernetes_containers`: Count for containers by filter criteria from CrowdStrike Kubernetes & Containers inventory - `falcon_search_images_vulnerabilities`: Search for images vulnerabilities from CrowdStrike Image Assessments **Resources**: - `falcon://cloud/kubernetes-containers/fql-guide`: Comprehensive FQL documentation and examples for kubernetes containers searches - `falcon://cloud/images-vulnerabilities/fql-guide`: Comprehensive FQL documentation and examples for images vulnerabilities searches **Use Cases**: Manage kubernetes containers inventory, container images vulnerabilities analysis ### 核心功能(内置 Server) **API Scopes**: _None required beyond basic API access_ The server provides core tools for interacting with the Falcon API: - `falcon_check_connectivity`: Check connectivity to the Falcon API - `falcon_list_enabled_modules`: Lists enabled modules in the falcon-mcp server - `falcon_list_modules`: Lists all available modules in the falcon-mcp server ### Detections 模块 **API Scopes Required**: `Alerts:read` Provides tools for accessing and analyzing CrowdStrike Falcon detections: - `falcon_search_detections`: Find and analyze detections to understand malicious activity in your environment - `falcon_get_detection_details`: Get comprehensive detection details for specific detection IDs to understand security threats **Resources**: - `falcon://detections/search/fql-guide`: Comprehensive FQL documentation and examples for detection searches **Use Cases**: Threat hunting, security analysis, incident response, malware investigation ### Discover 模块 **API Scopes Required**: `Assets:read` Provides tools for accessing and managing CrowdStrike Falcon Discover applications and unmanaged assets: - `falcon_search_applications`: Search for applications in your CrowdStrike environment - `falcon_search_unmanaged_assets`: Search for unmanaged assets (systems without Falcon sensor installed) that have been discovered by managed systems **Resources**: - `falcon://discover/applications/fql-guide`: Comprehensive FQL documentation and examples for application searches - `falcon://discover/hosts/fql-guide`: Comprehensive FQL documentation and examples for unmanaged assets searches **Use Cases**: Application inventory management, software asset management, license compliance, vulnerability assessment, unmanaged asset discovery, security gap analysis ### Hosts 模块 **API Scopes Required**: `Hosts:read` Provides tools for accessing and managing CrowdStrike Falcon hosts/devices: - `falcon_search_hosts`: Search for hosts in your CrowdStrike environment - `falcon_get_host_details`: Retrieve detailed information for specified host device IDs **Resources**: - `falcon://hosts/search/fql-guide`: Comprehensive FQL documentation and examples for host searches **Use Cases**: Asset management, device inventory, host monitoring, compliance reporting ### Identity Protection 模块 **API Scopes Required**: `Identity Protection Entities:read`, `Identity Protection Timeline:read`, `Identity Protection Detections:read`, `Identity Protection Assessment:read`, `Identity Protection GraphQL:write` Provides tools for accessing and managing CrowdStrike Falcon Identity Protection capabilities: - `idp_investigate_entity`: Entity investigation tool for analyzing users, endpoints, and other entities with support for timeline analysis, relationship mapping, and risk assessment **Use Cases**: Entity investigation, identity protection analysis, user behavior analysis, endpoint security assessment, relationship mapping, risk assessment ### Incidents 模块 **API Scopes Required**: `Incidents:read` Provides tools for accessing and analyzing CrowdStrike Falcon incidents: - `falcon_show_crowd_score`: View calculated CrowdScores and security posture metrics for your environment - `falcon_search_incidents`: Find and analyze security incidents to understand coordinated activity in your environment - `falcon_get_incident_details`: Get comprehensive incident details to understand attack patterns and coordinated activities - `falcon_search_behaviors`: Find and analyze behaviors to understand suspicious activity in your environment - `falcon_get_behavior_details`: Get detailed behavior information to understand attack techniques and tactics **Resources**: - `falcon://incidents/crowd-score/fql-guide`: Comprehensive FQL documentation for CrowdScore queries - `falcon://incidents/search/fql-guide`: Comprehensive FQL documentation and examples for incident searches - `falcon://incidents/behaviors/fql-guide`: Comprehensive FQL documentation and examples for behavior searches **Use Cases**: Incident management, threat assessment, attack pattern analysis, security posture monitoring ### NGSIEM 模块 **API Scopes Required**: `NGSIEM:read`, `NGSIEM:write` Provides tools for executing CQL queries against CrowdStrike's Next-Gen SIEM: - `search_ngsiem`: Execute a CQL query against Next-Gen SIEM repositories **Use Cases**: Log search and analysis, event correlation, threat hunting with custom CQL queries, security monitoring ### Intel 模块 **API Scopes Required**: - `Actors (Falcon Intelligence):read` - `Indicators (Falcon Intelligence):read` - `Reports (Falcon Intelligence):read` Provides tools for accessing and analyzing CrowdStrike Intelligence: - `falcon_search_actors`: Research threat actors and adversary groups tracked by CrowdStrike intelligence - `falcon_search_indicators`: Search for threat indicators and indicators of compromise (IOCs) from CrowdStrike intelligence - `falcon_search_reports`: Access CrowdStrike intelligence publications and threat reports - `falcon_get_mitre_report`: Generate MITRE ATT&CK reports for threat actors, providing detailed tactics, techniques, and procedures (TTPs) in JSON or CSV format **Resources**: - `falcon://intel/actors/fql-guide`: Comprehensive FQL documentation and examples for threat actor searches - `falcon://intel/indicators/fql-guide`: Comprehensive FQL documentation and examples for indicator searches - `falcon://intel/reports/fql-guide`: Comprehensive FQL documentation and examples for intelligence report searches **Use Cases**: Threat intelligence research, adversary tracking, IOC analysis, threat landscape assessment, MITRE ATT&CK framework analysis ### IOC 模块 **API Scopes Required**: - `IOC Management:read` - `IOC Management:write` Provides tools for managing custom indicators of compromise (IOCs) with Falcon IOC Service Collection endpoints: - `falcon_search_iocs`: Search custom IOCs using FQL and return full IOC details - `falcon_add_ioc`: Create one IOC or submit multiple IOCs in a single request - `falcon_remove_iocs`: Remove IOCs by explicit IDs or by FQL filter for bulk cleanup **Resources**: - `falcon://ioc/search/fql-guide`: FQL documentation and examples for IOC searches **Use Cases**: IOC lifecycle management, automated IOC onboarding, IOC cleanup and hygiene workflows ### Sensor Usage 模块 **API Scopes Required**: `Sensor Usage:read` Provides tools for accessing and analyzing CrowdStrike Falcon sensor usage data: - `falcon_search_sensor_usage Search for weekly sensor usage data in your CrowdStrike environment **Resources**: - `falcon://sensor-usage/weekly/fql-guide`: Comprehensive FQL documentation and examples for sensor usage searches **Use Cases**: Sensor deployment monitoring, license utilization analysis, sensor health tracking ### Scheduled Reports 模块 **API Scopes Required**: `Scheduled Reports:read` Provides tools for accessing and managing CrowdStrike Falcon scheduled reports and scheduled searches: - `falcon_search_scheduled_reports`: Search for scheduled reports and searches in your CrowdStrike environment - `falcon_launch_scheduled_report`: Launch a scheduled report on demand outside of its recurring schedule - `falcon_search_report_executions`: Search for report executions to track status and results - `falcon_download_report_execution`: Download generated report files **Resources**: - `falcon://scheduled-reports/search/fql-guide`: Comprehensive FQL documentation for searching scheduled report entities - `falcon://scheduled-reports/executions/search/fql-guide`: Comprehensive FQL documentation for searching report executions **Use Cases**: Automated report management, report execution monitoring, scheduled search analysis, report download automation ### Serverless 模块 **API Scopes Required**: `Falcon Container Image:read` Provides tools for accessing and managing CrowdStrike Falcon Serverless Vulnerabilities: - `falcon_search_serverless_vulnerabilities`: Search for vulnerabilities in your serverless functions across all cloud service providers **Resources**: - `falcon://serverless/vulnerabilities/fql-guide`: Comprehensive FQL documentation and examples for serverless vulnerabilities searches **Use Cases**: Serverless security assessment, vulnerability management, cloud security monitoring ### Spotlight 模块 **API Scopes Required**: `Vulnerabilities:read` Provides tools for accessing and managing CrowdStrike Spotlight vulnerabilities: - `falcon_search_vulnerabilities`: Search for vulnerabilities in your CrowdStrike environment **Resources**: - `falcon://spotlight/vulnerabilities/fql-guide`: Comprehensive FQL documentation and examples for vulnerability searches **Use Cases**: Vulnerability management, security assessments, compliance reporting, risk analysis, patch prioritization ## 安装与设置 ### 前提条件 - Python 3.11 or higher - [`uv`](https://docs.astral.sh/uv/) or pip - CrowdStrike Falcon API credentials (see above) ### 环境配置 You can configure your CrowdStrike API credentials in several ways: #### 使用 `.env` 文件 If you prefer using a `.env` file, you have several options: ##### 选项 1:从克隆的 repository 复制(如果已克隆) ``` 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 #FALCON_MCP_STATELESS_HTTP=false #FALCON_MCP_API_KEY=your-api-key ``` #### 环境变量 Alternatively, you can use environment variables directly. Set the following environment variables in your 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" # 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) ``` **CrowdStrike API Region URLs:** - **US-1 (Default)**: `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 ``` For installation via code editors/assistants, see the [Editor/Assitant](#editorassistant-integration) section below ## 使用 ### 命令行 Run the server with default settings (stdio transport): ``` falcon-mcp ``` Run with SSE transport: ``` falcon-mcp --transport sse ``` Run with streamable-http transport: ``` falcon-mcp --transport streamable-http ``` Run with streamable-http transport on custom port: ``` falcon-mcp --transport streamable-http --host 0.0.0.0 --port 8080 ``` Run with stateless HTTP mode (for scalable deployments like AWS AgentCore): ``` falcon-mcp --transport streamable-http --stateless-http ``` Run with API key authentication (recommended for HTTP transports): ``` falcon-mcp --transport streamable-http --api-key your-secret-key ``` ### 模块配置 The Falcon MCP Server supports multiple ways to specify which modules to enable: #### 1. 命令行参数(最高优先级) Specify modules using comma-separated lists: ``` # 启用特定模块 falcon-mcp --modules detections,incidents,intel,spotlight,idp # 仅启用一个模块 falcon-mcp --modules detections ``` #### 2. 环境变量(回退) Set the `FALCON_MCP_MODULES` environment variable: ``` # 导出环境变量 export FALCON_MCP_MODULES=detections,incidents,intel,spotlight,idp falcon-mcp # 或设置为内联 FALCON_MCP_MODULES=detections,incidents,intel,spotlight,idp falcon-mcp ``` #### 3. 默认行为(所有模块) If no modules are specified via command line or environment variable, all available modules are enabled by default. **Module Priority Order:** 1. Command line `--modules` argument (overrides all) 2. `FALCON_MCP_MODULES` environment variable (fallback) 3. All modules (default when none specified) ### 其他命令行选项 For all available options: ``` falcon-mcp --help ``` ### 作为库使用 ``` from falcon_mcp.server import FalconMCPServer # 创建并运行 server 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") ``` #### 直接凭证(Secret Management 集成) For enterprise deployments using secret management systems (HashiCorp Vault, AWS Secrets Manager, etc.), you can pass credentials directly instead of using environment variables: ``` 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 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 ``` ## Container 使用 The Falcon MCP Server is available as a pre-built container image for easy deployment: ### 使用预构建 Image(推荐) ``` # 拉取最新的预构建 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 文件和自定义 port 运行 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 文件和特定 modules 运行(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 ``` ### 本地构建(开发) For development or customization purposes, you can build the image locally: ``` # 构建 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 ``` ## 编辑器/Assistant 集成 You can integrate the Falcon MCP server with your editor or AI assistant. Here are configuration examples for popular MCP clients: ### 使用 `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 To deploy the MCP Server as a tool in Amazon Bedrock AgentCore, please refer to the [following document](./docs/deployment/amazon_bedrock_agentcore.md). ### Google Cloud(Cloud Run 和 Vertex AI) To deploy the MCP server as an agent within Cloud Run or Vertex AI Agent Engine (including for registration within Agentspace), refer to the [Google ADK example](./examples/adk/README.md). ### Gemini CLI 1. Install `uv` 2. `gemini extensions install https://github.com/CrowdStrike/falcon-mcp` 3. Copy a valid `.env` file to `~/.gemini/extensions/falcon-mcp/.env` ## 贡献 ### 贡献者入门指南 1. Clone the repository: git clone https://github.com/CrowdStrike/falcon-mcp.git cd falcon-mcp 2. Install in development mode: # 创建 .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 ``` #### 集成测试 Integration tests make real API calls to validate FalconPy operation names, HTTP methods, and response schemas. They catch issues that mocked unit tests cannot detect: - Incorrect FalconPy operation names (typos) - HTTP method mismatches (POST body vs GET query parameters) - Two-step search patterns not returning full details - API response schema changes **Requirements**: Valid CrowdStrike API credentials must be configured (see [Environment Configuration](#environment-configuration)). ### 开发者文档 - [Module Development Guide](docs/development/module_development.md): Instructions for implementing new modules - [Resource Development Guide](docs/development/resource_development.md): Instructions for implementing resources - [End-to-End Testing Guide](docs/development/e2e_testing.md): Guide for running and understanding E2E tests - [Integration Testing Guide](docs/development/integration_testing.md): Guide for running integration tests with real API calls ## 许可证 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## 支持 This is a community-driven, open source project. While it is not an official CrowdStroke product, it is actively maintained by CrowdStrike and supported in collaboration with the open source developer community. For more information, please see our [SUPPORT](SUPPORT.md) file.
`Identity Protection Timeline:read`
`Identity Protection Detections:read`
`Identity Protection Assessment:read`
`Identity Protection GraphQL:write` | Comprehensive entity investigation and identity protection analysis | | **Incidents** | `Incidents:read` | Analyze security incidents and coordinated activities | | **NGSIEM** | `NGSIEM:read`
`NGSIEM:write` | Execute CQL queries against Next-Gen SIEM | | **Intel** | `Actors (Falcon Intelligence):read`
`Indicators (Falcon Intelligence):read`
`Reports (Falcon Intelligence):read` | Research threat actors, IOCs, and intelligence reports | | **IOC** | `IOC Management:read`
`IOC Management:write` | Search, create, and remove custom IOCs using IOC Service Collection endpoints | | **Scheduled Reports** | `Scheduled Reports:read` | Get details about scheduled reports and searches, run reports on demand, and download report files | | **Sensor Usage** | `Sensor Usage:read` | Access and analyze sensor usage data | | **Serverless** | `Falcon Container Image:read` | Search for vulnerabilities in serverless functions across cloud service providers | | **Spotlight** | `Vulnerabilities:read` | Manage and analyze vulnerability data and security assessments | ## 可用模块、工具与资源 **About Tools & Resources**: This server provides both tools (actions you can perform) and resources (documentation and context). Tools execute operations like searching for detections or analyzing threats, while resources provide comprehensive documentation like FQL query guides that AI assistants can reference for context without requiring tool calls. ### Cloud Security 模块 **API Scopes Required**: - `Falcon Container Image:read` Provides tools for accessing and analyzing CrowdStrike Cloud Security resources: - `falcon_search_kubernetes_containers`: Search for containers from CrowdStrike Kubernetes & Containers inventory - `falcon_count_kubernetes_containers`: Count for containers by filter criteria from CrowdStrike Kubernetes & Containers inventory - `falcon_search_images_vulnerabilities`: Search for images vulnerabilities from CrowdStrike Image Assessments **Resources**: - `falcon://cloud/kubernetes-containers/fql-guide`: Comprehensive FQL documentation and examples for kubernetes containers searches - `falcon://cloud/images-vulnerabilities/fql-guide`: Comprehensive FQL documentation and examples for images vulnerabilities searches **Use Cases**: Manage kubernetes containers inventory, container images vulnerabilities analysis ### 核心功能(内置 Server) **API Scopes**: _None required beyond basic API access_ The server provides core tools for interacting with the Falcon API: - `falcon_check_connectivity`: Check connectivity to the Falcon API - `falcon_list_enabled_modules`: Lists enabled modules in the falcon-mcp server - `falcon_list_modules`: Lists all available modules in the falcon-mcp server ### Detections 模块 **API Scopes Required**: `Alerts:read` Provides tools for accessing and analyzing CrowdStrike Falcon detections: - `falcon_search_detections`: Find and analyze detections to understand malicious activity in your environment - `falcon_get_detection_details`: Get comprehensive detection details for specific detection IDs to understand security threats **Resources**: - `falcon://detections/search/fql-guide`: Comprehensive FQL documentation and examples for detection searches **Use Cases**: Threat hunting, security analysis, incident response, malware investigation ### Discover 模块 **API Scopes Required**: `Assets:read` Provides tools for accessing and managing CrowdStrike Falcon Discover applications and unmanaged assets: - `falcon_search_applications`: Search for applications in your CrowdStrike environment - `falcon_search_unmanaged_assets`: Search for unmanaged assets (systems without Falcon sensor installed) that have been discovered by managed systems **Resources**: - `falcon://discover/applications/fql-guide`: Comprehensive FQL documentation and examples for application searches - `falcon://discover/hosts/fql-guide`: Comprehensive FQL documentation and examples for unmanaged assets searches **Use Cases**: Application inventory management, software asset management, license compliance, vulnerability assessment, unmanaged asset discovery, security gap analysis ### Hosts 模块 **API Scopes Required**: `Hosts:read` Provides tools for accessing and managing CrowdStrike Falcon hosts/devices: - `falcon_search_hosts`: Search for hosts in your CrowdStrike environment - `falcon_get_host_details`: Retrieve detailed information for specified host device IDs **Resources**: - `falcon://hosts/search/fql-guide`: Comprehensive FQL documentation and examples for host searches **Use Cases**: Asset management, device inventory, host monitoring, compliance reporting ### Identity Protection 模块 **API Scopes Required**: `Identity Protection Entities:read`, `Identity Protection Timeline:read`, `Identity Protection Detections:read`, `Identity Protection Assessment:read`, `Identity Protection GraphQL:write` Provides tools for accessing and managing CrowdStrike Falcon Identity Protection capabilities: - `idp_investigate_entity`: Entity investigation tool for analyzing users, endpoints, and other entities with support for timeline analysis, relationship mapping, and risk assessment **Use Cases**: Entity investigation, identity protection analysis, user behavior analysis, endpoint security assessment, relationship mapping, risk assessment ### Incidents 模块 **API Scopes Required**: `Incidents:read` Provides tools for accessing and analyzing CrowdStrike Falcon incidents: - `falcon_show_crowd_score`: View calculated CrowdScores and security posture metrics for your environment - `falcon_search_incidents`: Find and analyze security incidents to understand coordinated activity in your environment - `falcon_get_incident_details`: Get comprehensive incident details to understand attack patterns and coordinated activities - `falcon_search_behaviors`: Find and analyze behaviors to understand suspicious activity in your environment - `falcon_get_behavior_details`: Get detailed behavior information to understand attack techniques and tactics **Resources**: - `falcon://incidents/crowd-score/fql-guide`: Comprehensive FQL documentation for CrowdScore queries - `falcon://incidents/search/fql-guide`: Comprehensive FQL documentation and examples for incident searches - `falcon://incidents/behaviors/fql-guide`: Comprehensive FQL documentation and examples for behavior searches **Use Cases**: Incident management, threat assessment, attack pattern analysis, security posture monitoring ### NGSIEM 模块 **API Scopes Required**: `NGSIEM:read`, `NGSIEM:write` Provides tools for executing CQL queries against CrowdStrike's Next-Gen SIEM: - `search_ngsiem`: Execute a CQL query against Next-Gen SIEM repositories **Use Cases**: Log search and analysis, event correlation, threat hunting with custom CQL queries, security monitoring ### Intel 模块 **API Scopes Required**: - `Actors (Falcon Intelligence):read` - `Indicators (Falcon Intelligence):read` - `Reports (Falcon Intelligence):read` Provides tools for accessing and analyzing CrowdStrike Intelligence: - `falcon_search_actors`: Research threat actors and adversary groups tracked by CrowdStrike intelligence - `falcon_search_indicators`: Search for threat indicators and indicators of compromise (IOCs) from CrowdStrike intelligence - `falcon_search_reports`: Access CrowdStrike intelligence publications and threat reports - `falcon_get_mitre_report`: Generate MITRE ATT&CK reports for threat actors, providing detailed tactics, techniques, and procedures (TTPs) in JSON or CSV format **Resources**: - `falcon://intel/actors/fql-guide`: Comprehensive FQL documentation and examples for threat actor searches - `falcon://intel/indicators/fql-guide`: Comprehensive FQL documentation and examples for indicator searches - `falcon://intel/reports/fql-guide`: Comprehensive FQL documentation and examples for intelligence report searches **Use Cases**: Threat intelligence research, adversary tracking, IOC analysis, threat landscape assessment, MITRE ATT&CK framework analysis ### IOC 模块 **API Scopes Required**: - `IOC Management:read` - `IOC Management:write` Provides tools for managing custom indicators of compromise (IOCs) with Falcon IOC Service Collection endpoints: - `falcon_search_iocs`: Search custom IOCs using FQL and return full IOC details - `falcon_add_ioc`: Create one IOC or submit multiple IOCs in a single request - `falcon_remove_iocs`: Remove IOCs by explicit IDs or by FQL filter for bulk cleanup **Resources**: - `falcon://ioc/search/fql-guide`: FQL documentation and examples for IOC searches **Use Cases**: IOC lifecycle management, automated IOC onboarding, IOC cleanup and hygiene workflows ### Sensor Usage 模块 **API Scopes Required**: `Sensor Usage:read` Provides tools for accessing and analyzing CrowdStrike Falcon sensor usage data: - `falcon_search_sensor_usage Search for weekly sensor usage data in your CrowdStrike environment **Resources**: - `falcon://sensor-usage/weekly/fql-guide`: Comprehensive FQL documentation and examples for sensor usage searches **Use Cases**: Sensor deployment monitoring, license utilization analysis, sensor health tracking ### Scheduled Reports 模块 **API Scopes Required**: `Scheduled Reports:read` Provides tools for accessing and managing CrowdStrike Falcon scheduled reports and scheduled searches: - `falcon_search_scheduled_reports`: Search for scheduled reports and searches in your CrowdStrike environment - `falcon_launch_scheduled_report`: Launch a scheduled report on demand outside of its recurring schedule - `falcon_search_report_executions`: Search for report executions to track status and results - `falcon_download_report_execution`: Download generated report files **Resources**: - `falcon://scheduled-reports/search/fql-guide`: Comprehensive FQL documentation for searching scheduled report entities - `falcon://scheduled-reports/executions/search/fql-guide`: Comprehensive FQL documentation for searching report executions **Use Cases**: Automated report management, report execution monitoring, scheduled search analysis, report download automation ### Serverless 模块 **API Scopes Required**: `Falcon Container Image:read` Provides tools for accessing and managing CrowdStrike Falcon Serverless Vulnerabilities: - `falcon_search_serverless_vulnerabilities`: Search for vulnerabilities in your serverless functions across all cloud service providers **Resources**: - `falcon://serverless/vulnerabilities/fql-guide`: Comprehensive FQL documentation and examples for serverless vulnerabilities searches **Use Cases**: Serverless security assessment, vulnerability management, cloud security monitoring ### Spotlight 模块 **API Scopes Required**: `Vulnerabilities:read` Provides tools for accessing and managing CrowdStrike Spotlight vulnerabilities: - `falcon_search_vulnerabilities`: Search for vulnerabilities in your CrowdStrike environment **Resources**: - `falcon://spotlight/vulnerabilities/fql-guide`: Comprehensive FQL documentation and examples for vulnerability searches **Use Cases**: Vulnerability management, security assessments, compliance reporting, risk analysis, patch prioritization ## 安装与设置 ### 前提条件 - Python 3.11 or higher - [`uv`](https://docs.astral.sh/uv/) or pip - CrowdStrike Falcon API credentials (see above) ### 环境配置 You can configure your CrowdStrike API credentials in several ways: #### 使用 `.env` 文件 If you prefer using a `.env` file, you have several options: ##### 选项 1:从克隆的 repository 复制(如果已克隆) ``` 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 #FALCON_MCP_STATELESS_HTTP=false #FALCON_MCP_API_KEY=your-api-key ``` #### 环境变量 Alternatively, you can use environment variables directly. Set the following environment variables in your 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" # 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) ``` **CrowdStrike API Region URLs:** - **US-1 (Default)**: `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 ``` For installation via code editors/assistants, see the [Editor/Assitant](#editorassistant-integration) section below ## 使用 ### 命令行 Run the server with default settings (stdio transport): ``` falcon-mcp ``` Run with SSE transport: ``` falcon-mcp --transport sse ``` Run with streamable-http transport: ``` falcon-mcp --transport streamable-http ``` Run with streamable-http transport on custom port: ``` falcon-mcp --transport streamable-http --host 0.0.0.0 --port 8080 ``` Run with stateless HTTP mode (for scalable deployments like AWS AgentCore): ``` falcon-mcp --transport streamable-http --stateless-http ``` Run with API key authentication (recommended for HTTP transports): ``` falcon-mcp --transport streamable-http --api-key your-secret-key ``` ### 模块配置 The Falcon MCP Server supports multiple ways to specify which modules to enable: #### 1. 命令行参数(最高优先级) Specify modules using comma-separated lists: ``` # 启用特定模块 falcon-mcp --modules detections,incidents,intel,spotlight,idp # 仅启用一个模块 falcon-mcp --modules detections ``` #### 2. 环境变量(回退) Set the `FALCON_MCP_MODULES` environment variable: ``` # 导出环境变量 export FALCON_MCP_MODULES=detections,incidents,intel,spotlight,idp falcon-mcp # 或设置为内联 FALCON_MCP_MODULES=detections,incidents,intel,spotlight,idp falcon-mcp ``` #### 3. 默认行为(所有模块) If no modules are specified via command line or environment variable, all available modules are enabled by default. **Module Priority Order:** 1. Command line `--modules` argument (overrides all) 2. `FALCON_MCP_MODULES` environment variable (fallback) 3. All modules (default when none specified) ### 其他命令行选项 For all available options: ``` falcon-mcp --help ``` ### 作为库使用 ``` from falcon_mcp.server import FalconMCPServer # 创建并运行 server 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") ``` #### 直接凭证(Secret Management 集成) For enterprise deployments using secret management systems (HashiCorp Vault, AWS Secrets Manager, etc.), you can pass credentials directly instead of using environment variables: ``` 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 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 ``` ## Container 使用 The Falcon MCP Server is available as a pre-built container image for easy deployment: ### 使用预构建 Image(推荐) ``` # 拉取最新的预构建 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 文件和自定义 port 运行 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 文件和特定 modules 运行(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 ``` ### 本地构建(开发) For development or customization purposes, you can build the image locally: ``` # 构建 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 ``` ## 编辑器/Assistant 集成 You can integrate the Falcon MCP server with your editor or AI assistant. Here are configuration examples for popular MCP clients: ### 使用 `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 To deploy the MCP Server as a tool in Amazon Bedrock AgentCore, please refer to the [following document](./docs/deployment/amazon_bedrock_agentcore.md). ### Google Cloud(Cloud Run 和 Vertex AI) To deploy the MCP server as an agent within Cloud Run or Vertex AI Agent Engine (including for registration within Agentspace), refer to the [Google ADK example](./examples/adk/README.md). ### Gemini CLI 1. Install `uv` 2. `gemini extensions install https://github.com/CrowdStrike/falcon-mcp` 3. Copy a valid `.env` file to `~/.gemini/extensions/falcon-mcp/.env` ## 贡献 ### 贡献者入门指南 1. Clone the repository: git clone https://github.com/CrowdStrike/falcon-mcp.git cd falcon-mcp 2. Install in development mode: # 创建 .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 ``` #### 集成测试 Integration tests make real API calls to validate FalconPy operation names, HTTP methods, and response schemas. They catch issues that mocked unit tests cannot detect: - Incorrect FalconPy operation names (typos) - HTTP method mismatches (POST body vs GET query parameters) - Two-step search patterns not returning full details - API response schema changes **Requirements**: Valid CrowdStrike API credentials must be configured (see [Environment Configuration](#environment-configuration)). ### 开发者文档 - [Module Development Guide](docs/development/module_development.md): Instructions for implementing new modules - [Resource Development Guide](docs/development/resource_development.md): Instructions for implementing resources - [End-to-End Testing Guide](docs/development/e2e_testing.md): Guide for running and understanding E2E tests - [Integration Testing Guide](docs/development/integration_testing.md): Guide for running integration tests with real API calls ## 许可证 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## 支持 This is a community-driven, open source project. While it is not an official CrowdStroke product, it is actively maintained by CrowdStrike and supported in collaboration with the open source developer community. For more information, please see our [SUPPORT](SUPPORT.md) file.
标签:API集成, CrowdStrike, DNS解析, EDR, Falcon, GPT, HTTP/HTTPS抓包, LLM, MCP, Model Context Protocol, Python, Unmanaged PE, 可观测性, 威胁情报, 威胁猎杀, 安全运营, 开发者工具, 开源项目, 态势感知, 扫描框架, 无后门, 漏洞管理, 端点检测与响应, 网络安全, 网络调试, 脆弱性评估, 脱壳工具, 自动化, 请求拦截, 身份保护, 逆向工具, 隐私保护