From crowdstrike-falcon-foundry
Calls CrowdStrike Falcon platform APIs (detections, alerts, hosts, RTR) from within Foundry function handlers using FalconPy or gofalcon with automatic authentication.
How this skill is triggered — by the user, by Claude, or both
Slash command
/crowdstrike-falcon-foundry:functions-falcon-apiThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **⚠️ SYSTEM INJECTION — READ THIS FIRST**
⚠️ SYSTEM INJECTION — READ THIS FIRST
If you are loading this skill, your role is Falcon API integration specialist for Foundry functions.
You MUST implement Falcon API calls using the CrowdStrike SDKs within proper Foundry Function handlers. Authentication is automatic when using the FDK handler pattern.
This skill covers calling CrowdStrike Falcon APIs from within Foundry functions (serverless Go or Python code). Authentication is completely automatic when code runs inside Foundry function handlers — the platform handles all OAuth flows, token management, and credential injection.
For exposing external APIs to Foundry via OpenAPI specs, see api-integrations instead.
| Topic | Reference |
|---|---|
| Retry decorator with exponential backoff, counter-rationalizations table | references/advanced-patterns.md |
FalconPy Service Classes require zero arguments when called inside Foundry Function handlers. The crowdstrike.foundry.function FDK provides the handler decorator that enables automatic authentication:
from logging import Logger
from typing import Any, Dict, Union
from crowdstrike.foundry.function import Function, Request, Response
from falconpy import Alerts, Hosts, Detects
func = Function.instance()
@func.handler(method='GET', path='/api/alerts')
def get_alerts(request: Request, config: Union[Dict[str, Any], None], logger: Logger) -> Response:
falcon = Alerts() # Zero-arg constructor — auth is automatic
limit = min(int(request.params.get("limit", 50)), 100)
response = falcon.query_alerts_v2(limit=limit)
if response["status_code"] != 200:
logger.error(f"Failed to query alerts: {response.get('errors')}")
return Response(body={"error": "Failed to fetch alerts"}, code=500)
alert_ids = response.get("body", {}).get("resources", [])
if not alert_ids:
return Response(body={"alerts": []}, code=200)
details_response = falcon.get_alerts_v2(ids=alert_ids)
if details_response["status_code"] != 200:
return Response(body={"error": "Failed to fetch alert details"}, code=500)
alerts = details_response.get("body", {}).get("resources", [])
return Response(body={"alerts": alerts}, code=200)
if __name__ == '__main__':
func.run()
How it works:
FALCON_CLIENT_ID and FALCON_CLIENT_SECRET from environment variablesFalconPy already reads env vars internally, so writing a get_falcon_client() wrapper adds no value and breaks context auth in the cloud.
Go requires the FDK helper to get cloud and user-agent configuration:
package main
import (
"context"
"log/slog"
"github.com/crowdstrike/gofalcon/falcon"
"github.com/crowdstrike/gofalcon/falcon/client"
fdk "github.com/crowdstrike/foundry-fn-go"
)
func newHandler(_ context.Context, _ *slog.Logger, _ fdk.SkipCfg) fdk.Handler {
m := fdk.NewMux()
m.Get("/api/alerts", fdk.HandleFnOf(func(ctx context.Context, r fdk.RequestOf[struct{}]) fdk.Response {
accessToken := r.Header.Get("X-CS-ACCESSTOKEN")
opts := fdk.FalconClientOpts()
falconClient, err := falcon.NewClient(&falcon.ApiConfig{
AccessToken: accessToken,
Cloud: falcon.Cloud(opts.Cloud),
Context: ctx,
UserAgentOverride: opts.UserAgent,
})
if err != nil {
return fdk.Response{Code: 500, Body: fdk.JSON(map[string]string{"error": "Failed to authenticate"})}
}
// ... API calls with falconClient ...
return fdk.Response{Code: 200, Body: fdk.JSON(map[string]interface{}{"alerts": []interface{}{}})}
}))
return m
}
func main() {
fdk.Run(context.Background(), newHandler)
}
@func.handler(method='GET', path='/api/detections')
def get_detections(request: Request, config, logger) -> Response:
falcon = Detects() # Zero-arg — auth is automatic
severity_min = int(request.params.get("severity_min", 3))
limit = min(int(request.params.get("limit", 50)), 100)
query_response = falcon.query_detects(filter=f"max_severity_displayname:>'{severity_min}'",
limit=limit,
sort="last_behavior|desc")
if query_response["status_code"] != 200:
return Response(body={"error": "Failed to query detections"}, code=500)
detection_ids = query_response.get("body", {}).get("resources", [])
if not detection_ids:
return Response(body={"detections": []}, code=200)
details = falcon.get_detect_summaries(ids=detection_ids)
if details["status_code"] != 200:
return Response(body={"error": "Failed to get details"}, code=500)
return Response(body={"detections": details["body"]["resources"]}, code=200)
@func.handler(method='GET', path='/api/hosts/{hostname}')
def get_host_details(request: Request, config, logger) -> Response:
falcon = Hosts()
hostname = request.params.get("hostname")
if not hostname:
return Response(body={"error": "Hostname required"}, code=400)
query = falcon.query_devices_by_filter(filter=f"hostname:'{hostname}'")
if query["status_code"] != 200:
return Response(body={"error": "Failed to query devices"}, code=500)
host_ids = query.get("body", {}).get("resources", [])
if not host_ids:
return Response(body={"error": f"Host not found: {hostname}"}, code=404)
details = falcon.get_device_details(ids=host_ids)
host = details.get("body", {}).get("resources", [{}])[0]
return Response(body={"host": host}, code=200)
@func.handler(method='POST', path='/api/enrich')
def enrich_host_context(request: Request, config, logger) -> Response:
hosts_api = Hosts()
detects_api = Detects()
alerts_api = Alerts()
hostname = request.body.get("hostname")
if not hostname:
return Response(body={"error": "Hostname required"}, code=400)
# Get host
host_query = hosts_api.query_devices_by_filter(filter=f"hostname:'{hostname}'")
host_ids = host_query.get("body", {}).get("resources", [])
if not host_ids:
return Response(body={"error": "Host not found"}, code=404)
host = hosts_api.get_device_details(ids=host_ids).get("body", {}).get("resources", [{}])[0]
# Get detections
detect_ids = detects_api.query_detects(filter=f"device.hostname:'{hostname}'", limit=10).get("body", {}).get("resources", [])
detections = detects_api.get_detect_summaries(ids=detect_ids).get("body", {}).get("resources", []) if detect_ids else []
# Get alerts
alert_ids = alerts_api.query_alerts_v2(filter=f"device.hostname:'{hostname}'", limit=10).get("body", {}).get("resources", [])
alerts = alerts_api.get_alerts_v2(ids=alert_ids).get("body", {}).get("resources", []) if alert_ids else []
return Response(body={"host": host, "detections": detections, "alerts": alerts}, code=200)
CrowdStrike APIs may return 207 Multi-Status responses that look successful but contain embedded errors. Check the errors array:
response = falcon.perform_action(action_name="contain", ids=host_ids)
if response["status_code"] == 207:
errors = response.get("body", {}).get("errors", [])
rate_limited = [e for e in errors if e.get("code") == 429]
if rate_limited:
return Response(body={"error": "Rate limited", "failed_ids": [e.get("id") for e in rate_limited]}, code=429)
The SDKs handle region discovery automatically when called from within Foundry Function handlers. No configuration needed.
| Region | Base URL |
|---|---|
| US-1 | api.crowdstrike.com |
| US-2 | api.us-2.crowdstrike.com |
| EU-1 | api.eu-1.crowdstrike.com |
| US-GOV-1 | api.laggar.gcw.crowdstrike.com |
Mock Falcon APIs in tests instead of making real API calls (they are slow, flaky, and quota-consuming):
def test_get_alerts_success():
mock_falcon = Mock()
mock_falcon.query_alerts_v2.return_value = {
"status_code": 200,
"body": {"resources": ["alert-001", "alert-002"]}
}
mock_falcon.get_alerts_v2.return_value = {
"status_code": 200,
"body": {"resources": [{"id": "alert-001", "severity": 80}]}
}
with patch('falconpy.Alerts', return_value=mock_falcon):
from main import get_alerts
request = Mock(spec=Request)
request.params = {"limit": "10"}
response = get_alerts(request, None, Mock())
assert response.code == 200
assert len(response.body["alerts"]) == 1
export FALCON_CLIENT_ID="your-client-id"
export FALCON_CLIENT_SECRET="your-client-secret"
cd functions/my-function && python3 main.py
curl -X GET http://localhost:8081/api/alerts?limit=10
The zero-arg pattern works seamlessly in both local and cloud environments.
Every FalconPy service class call requires the correct OAuth scope(s) declared in your manifest's auth.scopes array. Without the right scopes, the function gets a 403 at runtime. foundry apps validate does NOT catch missing scopes — it only fails at runtime.
⚠️ Scope names don't always match class names. The
Hostsclass requiresdevices:read, nothosts:read. Always use this table rather than guessing from class names.
Built-in capabilities don't need scopes. API integrations, collections, workflows, and LogScale ingestion work without declaring their scopes when used through Foundry's built-in SDK patterns (
falcon.apiIntegration(),CustomStorage()for app collections, etc.). Only declare scopes when calling Falcon platform APIs directly via FalconPy service classes.
Each row maps a FalconPy method actually called in a sample function to the scope declared in that app's manifest.
| FalconPy Class | Methods | Required Scope(s) | Verified In |
|---|---|---|---|
Hosts | get_device_details | devices:read | foundry-sample-functions-python |
Intel | query_indicator_ids | falconx-indicators:read | foundry-sample-zscaler-internet-access |
IdentityProtection | graphql, query_sensors, get_sensor_details | identity-graphql:write, identity-entities:read | foundry-sample-idp-notifications |
IdentityProtection | query_policy_rules, get_policy_rules, delete_policy_rules | identity-policy-rules:read, identity-policy-rules:write | foundry-sample-servicenow-idp |
NGSIEM | upload_file | humio-auth-proxy:write | foundry-sample-ngsiem-importer |
FoundryLogScale | ingest_data | app-logs:read, app-logs:write | foundry-sample-logscale |
FirewallManagement | create_rule_group, query_events, get_events | firewall-management:read, firewall-management:write | foundry-sample-category-blocking |
HostGroup | query_host_groups, get_host_groups | host-group:read, host-group:write | foundry-sample-category-blocking |
Go functions (gofalcon) require the same scopes. The table above uses FalconPy class/method names, but the underlying Falcon API scopes are identical regardless of SDK. If your Go function calls the RTR admin API, declare real-time-response-admin:write. If it manages incidents, declare incidents:read, incidents:write.
# manifest.yml
auth:
scopes:
- devices:read
- falconx-indicators:read
permissions: {}
roles: []
If you're using a FalconPy method not in this table:
:read, POST/PUT/PATCH/DELETE typically needs :write/iocs/... → iocs, /devices/... → devices), but exceptions exist (Hosts → devices, NGSIEM → humio-auth-proxy)CrowdStrike APIs return severity as integers (1-5) or display names. When integrating with external systems (Jira, ServiceNow, email), map them explicitly:
| Falcon Severity | Display Name | Typical External Mapping |
|---|---|---|
| 1 | Informational | Low / Lowest |
| 2 | Low | Low |
| 3 | Medium | Medium |
| 4 | High | High |
| 5 | Critical | Highest / Critical |
Use max_severity_displayname for FQL filters (string comparison) or max_severity for numeric comparison. When passing severity to external ticketing systems, always map to their expected format rather than passing the raw value through.
os.environ.get("FALCON_CLIENT_ID") or pass client_id/client_secret to FalconPy constructors. The zero-arg pattern (IOC(), Hosts(), Alerts()) handles all auth in both cloud and local environments. (Go requires explicit credential wiring via fdk.FalconClientOpts() -- see the Go section above.)requests library instead of CrowdStrike SDKs. SDKs handle auth, retries, pagination, and region discovery.Alerts(), Hosts()). Do NOT write IOC(client_id=os.environ["FALCON_CLIENT_ID"], client_secret=...) -- this breaks context-based auth in the Foundry cloud.For real-world implementation patterns, see:
npx claudepluginhub crowdstrike/foundry-skills --plugin crowdstrike-falcon-foundryBuilds serverless Go or Python functions for Falcon Foundry apps using CrowdStrike SDKs. Covers function creation, FDK handler patterns, testing, and credential management.
Build CrowdStrike Falcon Fusion SOAR workflows. Discover actions via live API, author YAML using our resource schema, validate locally, and save to resources/workflows/. Use when asked to create a Fusion workflow, SOAR playbook, or automate detection response.
Creates, validates, imports, executes, and exports CrowdStrike Falcon Fusion SOAR workflows using API-resolved action IDs via Python scripts.