# CrowdStrike Falcon MCP Server
A Model Context Protocol (MCP) server for interacting with the CrowdStrike Falcon API. This server provides both STDIO (for MCP-aware clients) and HTTP/REST (for broader interoperability) transport modes.
## Features
- **Dual Transport Support**: Supports both STDIO (MCP protocol) and HTTP/REST simultaneously
- **Secure Credential Handling**: Credentials can be passed as function parameters or via environment variables
- **Multi-tenant Support**: Optional tenant ID support for multi-tenant scenarios
- **Comprehensive API Coverage**: Tools for hosts, detections, IOCs, policies, and more
- **Production Ready**: Docker support with health checks and GitHub Actions CI/CD
## Architecture
```
┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐
│ MCP Client │─────▶│ STDIO Port │─────▶│ MCP Core │
│ (Claude/Cursor) │ │ (8080) │ │ (FastMCP) │
└─────────────────┘ └──────────────┘ └─────────────────┘
│
┌─────────────────┐ ┌──────────────┐ │
│ REST Client │─────▶│ HTTP Gateway │─────────────┘
│ (curl/Python) │ │ (Port 80) │
└─────────────────┘ └──────────────┘
```
## Installation
### Docker (Recommended)
```bash
docker pull <your-registry>/crowdstrike-falcon-mcp:latest
docker run -d \
--name crowdstrike-falcon-mcp \
--publish 8080:8080 \
--publish 80:80 \
-e TRANSPORT_MODE=dual \
-e FALCON_API_KEY=your_api_key_here \
<your-registry>/crowdstrike-falcon-mcp:latest
```
## Configuration
### Environment Variables
- `FALCON_API_KEY` (or `CROWDSTRIKE_API_KEY`): Your CrowdStrike API key
- `FALCON_TENANT_ID` (or `CROWDSTRIKE_TENANT_ID`): Optional tenant ID for multi-tenant scenarios
- `FALCON_API_BASE_URL`: API base URL (default: `https://api.crowdstrike.com`)
- `TRANSPORT_MODE`: Transport mode - `stdio`, `http`, or `dual` (default: `dual`)
- `HTTP_PORT`: HTTP server port (default: `80`)
- `STDIO_PORT`: STDIO port (default: `8080`)
### Credential Handling
**Security Note**: Credentials are never stored. They can be provided in two ways:
1. **Function Parameters**: Pass `api_key` and optional `tenant_id` to each tool call
2. **Environment Variables**: Set `FALCON_API_KEY` and optionally `FALCON_TENANT_ID`
## Connection Methods
### 1. STDIO (MCP Protocol)
For MCP-aware clients like Claude Desktop, Cursor, or MCP Toolkit.
#### Claude Desktop
Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"crowdstrike-falcon": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"<your-registry>/crowdstrike-falcon-mcp:latest",
"python",
"-m",
"src.mcp_server"
],
"env": {
"TRANSPORT_MODE": "stdio"
}
}
}
}
```
#### Cursor
Similar configuration in Cursor's MCP settings.
#### MCP Toolkit
The `mcp-toolkit.yml` file enables automatic discovery. Place it in your MCP Toolkit configuration directory.
### 2. HTTP/REST API
For REST clients, curl, Python requests, Node.js fetch, etc.
#### Health Check
```bash
curl http://localhost:80/healthz
```
#### List Available Tools
```bash
curl http://localhost:80/tools
```
#### Call a Tool
```bash
curl -X POST http://localhost:80/tools/query_hosts \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key_here" \
-d '{
"filter": "hostname:\"example.com\"",
"limit": 10
}'
```
#### Python Example
```python
import requests
# Using header for API key
response = requests.post(
"http://localhost:80/tools/query_hosts",
headers={"X-API-Key": "your_api_key_here"},
json={"filter": "hostname:\"example.com\"", "limit": 10}
)
print(response.json())
# Or using body
response = requests.post(
"http://localhost:80/tools/query_hosts",
json={
"api_key": "your_api_key_here",
"filter": "hostname:\"example.com\"",
"limit": 10
}
)
print(response.json())
```
#### Node.js Example
```javascript
const fetch = require('node-fetch');
async function queryHosts() {
const response = await fetch('http://localhost:80/tools/query_hosts', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'your_api_key_here'
},
body: JSON.stringify({
filter: 'hostname:"example.com"',
limit: 10
})
});
const data = await response.json();
console.log(data);
}
queryHosts();
```
## Available Tools
### Host/Device Management
- `query_hosts`: Query hosts/devices with filters
- `get_host_details`: Get detailed information about specific hosts
### Detection Management
- `query_detections`: Query detections with filters
- `get_detection_details`: Get detailed information about specific detections
- `update_detection_status`: Update detection status
### IOC Management
- `query_iocs`: Query Indicators of Compromise
- `create_ioc`: Create a new IOC
- `delete_ioc`: Delete IOCs
### Host Group Management
- `query_host_groups`: Query host groups
- `get_host_group_details`: Get detailed information about host groups
### Policy Management
- `query_prevention_policies`: Query prevention policies
- `get_prevention_policy_details`: Get detailed information about prevention policies
- `query_sensor_update_policies`: Query sensor update policies
- `get_sensor_update_policy_details`: Get detailed information about sensor update policies
## Example Tool Calls
### Query Hosts (STDIO/MCP)
When using MCP clients, tools are called directly:
```python
# In MCP client context
result = await mcp.call_tool("query_hosts", {
"api_key": "your_api_key",
"filter": "hostname:'example.com'",
"limit": 10
})
```
### Query Hosts (HTTP/REST)
```bash
curl -X POST http://localhost:80/tools/query_hosts \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"filter": "hostname:\"example.com\"",
"limit": 10
}'
```
### Create IOC
```bash
curl -X POST http://localhost:80/tools/create_ioc \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"type": "domain",
"value": "malicious.example.com",
"action": "prevent",
"platforms": ["Windows", "Mac", "Linux"],
"description": "Malicious domain",
"severity": "high"
}'
```
### Update Detection Status
```bash
curl -X POST http://localhost:80/tools/update_detection_status \
-H "Content-Type: application/json" \
-H "X-API-Key: your_api_key" \
-d '{
"detection_ids": ["detection_id_1", "detection_id_2"],
"status": "true_positive",
"comment": "Confirmed malicious activity"
}'
```
## HTTPS Deployment
### Using nginx as Reverse Proxy
```nginx
server {
listen 443 ssl;
server_name your-domain.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://localhost:80;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
### Using Traefik
```yaml
services:
crowdstrike-falcon-mcp:
image: <your-registry>/crowdstrike-falcon-mcp:latest
labels:
- "traefik.enable=true"
- "traefik.http.routers.falcon.rule=Host(`your-domain.com`)"
- "traefik.http.routers.falcon.tls=true"
- "traefik.http.routers.falcon.tls.certresolver=letsencrypt"
- "traefik.http.services.falcon.loadbalancer.server.port=80"
```
## Production Deployment Considerations
1. **Security**:
- Use HTTPS in production
- Implement rate limiting
- Use API key rotation
- Monitor access logs
2. **Scaling**:
- Use a load balancer for HTTP mode
- Consider horizontal scaling for high traffic
- Use connection pooling for API calls
3. **Monitoring**:
- Monitor `/healthz` endpoint
- Set up alerting for failed health checks
- Log API errors and rate limits
4. **High Availability**:
- Deploy multiple instances
- Use health checks in orchestrators
- Implement graceful shutdown
## Development
### Running Tests
```bash
# Install test dependencies
pip install pytest pytest-asyncio
# Run tests
pytest
```
### Building Docker Image Locally
```bash
# Build
docker build -t crowdstrike-falcon-mcp:local .
# Run
docker run -p 8080:8080 -p 80:80 \
-e FALCON_API_KEY=your_key \
crowdstrike-falcon-mcp:local
```
### Publishing Docker Image
```bash
# Using the script
python docker-publish.py \
--registry docker.io \
--image-name crowdstrike-falcon-mcp \
--tag v1.0.0
# Or manually
docker build -t your-registry/crowdstrike-falcon-mcp:v1.0.0 .
docker push your-registry/crowdstrike-falcon-mcp:v1.0.0
```
## GitHub Actions
The repository includes a GitHub Actions workflow (`.github/workflows/docker-publish.yml`) that automatically:
- Builds Docker images on push to main/master
- Builds and pushes on version tags
- Supports multi-platform builds (amd64, arm64)
- Uses Docker layer caching for faster builds
**Required Secrets**:
- `DOCKER_USERNAME`: Your Docker Hub username
- `DOCKER_PASSWORD`: Your Docker Hub password or access token
## API Reference
### CrowdStrike Falcon API
This MCP server wraps the CrowdStrike Falcon API. For detailed API documentation, refer to:
- [CrowdStrike API Documentation](https://falcon.crowdstrike.com/documentation/)
- [API Swagger Specification](https://assets.falcon.crowdstrike.com/support/api/swagger.html)
### Filter Query Language (FQL)
Many endpoints support FQL (Falcon Query Language) for filtering. Examples:
- `hostname:'example.com'` - Exact match
- `hostname:*example*` - Wildcard match
- `status:'new'+severity:'high'` - Multiple conditions
- `first_seen:>='2024-01-01T00:00:00Z'` - Date comparison
## Troubleshooting
### Health Check Failing
```bash
# Check if server is running
curl http://localhost:80/healthz
# Check logs
docker logs crowdstrike-falcon-mcp
```
### Authentication Errors
- Verify your API key is correct
- Check if API key has required scopes
- Ensure API key format is correct (may be `client_id:client_secret` format)
### Connection Issues
- Verify ports are exposed correctly
- Check firewall rules
- Ensure TRANSPORT_MODE matches your use case
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
[Add your license here]
## Support
For issues and questions:
- Open an issue on GitHub
- Check the CrowdStrike API documentation
- Review the MCP server logs
## Changelog
### v1.0.0
- Initial release
- Support for hosts, detections, IOCs, policies
- Dual transport mode (STDIO + HTTP)
- Docker support
- GitHub Actions CI/CD
