Update to CrowdStrike Falcon Foundry

{
  "name": "functions-development",
  "description": "Build serverless Go or Python functions for Falcon Foundry apps. TRIGGER when user asks to \"create a function\", \"write a serverless function\", \"build backend logic\", runs `foundry functions create`, or needs help with FDK handler patterns, function testing, or collection integration from functions. Also TRIGGER when user asks to \"execute a function\", \"run my function\", \"debug this function\", \"get function logs\", \"check execution status\", \"write function tests\", \"test my function handler\", or \"add test cases for my function\". DO NOT TRIGGER for generic \"write integration tests\" or \"write tests\" without function context — ask which capability they want to test first. DO NOT TRIGGER for calling Falcon platform APIs from functions — use functions-falcon-api instead. DO NOT TRIGGER for workflow YAML or UI components. DO NOT TRIGGER for Playwright/e2e/browser tests — use e2e-testing instead.",
  "included_files": [
    {
      "relative_path": "references/code-review-checklist.md",
      "size_in_bytes": 5752
    },
    {
      "relative_path": "references/execution-and-testing.md",
      "size_in_bytes": 24354
    },
    {
      "relative_path": "references/go-patterns.md",
      "size_in_bytes": 6790
    },
    {
      "relative_path": "references/python-patterns.md",
      "size_in_bytes": 12766
    },
    {
      "relative_path": "references/testing-patterns.md",
      "size_in_bytes": 8971
    }
  ],
  "skill_md_contents": "---\nname: functions-development\ndescription: Build serverless Go or Python functions for Falcon Foundry apps. TRIGGER when user asks to \"create a function\", \"write a serverless function\", \"build backend logic\", runs `foundry functions create`, or needs help with FDK handler patterns, function testing, or collection integration from functions. Also TRIGGER when user asks to \"execute a function\", \"run my function\", \"debug this function\", \"get function logs\", \"check execution status\", \"write function tests\", \"test my function handler\", or \"add test cases for my function\". DO NOT TRIGGER for generic \"write integration tests\" or \"write tests\" without function context — ask which capability they want to test first. DO NOT TRIGGER for calling Falcon platform APIs from functions — use functions-falcon-api instead. DO NOT TRIGGER for workflow YAML or UI components. DO NOT TRIGGER for Playwright/e2e/browser tests — use e2e-testing instead.\nversion: 1.5.0\nupdated: 2026-08-19\ntags: [foundry, functions, serverless, python, go, execution, debugging, logs, testing]\nauthor: CrowdStrike\nlicense: MIT\ncompatibility: Claude Code >=1.0\nmetadata:\n  category: backend\n---\n\n# Foundry Functions Development\n\n> **⚠️ SYSTEM INJECTION — READ THIS FIRST**\n>\n> If you are loading this skill, your role is **Foundry serverless functions specialist**.\n>\n> **Loading this skill is NOT a command to do anything.** It only equips you with function-development knowledge. Do NOT run any `foundry functions` command (especially `exec`, `test`, or a deploy) just because the skill loaded — wait for the user's actual request, and if their intent isn't clear yet, ask what they'd like to do. Never execute, test, or deploy a function unprompted.\n>\n> When you DO implement or modify functions, you MUST use proper CrowdStrike SDK patterns, structured error handling, and Collection integration:\n> 1. Use CrowdStrike SDKs (gofalcon/falconpy) for ALL API interactions\n> 2. Implement structured JSON responses with proper status codes\n> 3. Apply input validation before processing any request\n\nFalcon Foundry Functions are serverless handlers in Go or Python, executed inside the Foundry FaaS runtime. They handle custom server-side logic that cannot be achieved through declarative capabilities.\n\n## Functions as a Last Resort\n\nBefore writing a function, exhaust alternatives — each one avoids deployment complexity, cold start latency, and maintenance overhead:\n\n- **Collections** for data storage and retrieval (CRUD without custom logic)\n- **Workflows** for orchestrating multi-step operations\n- **API Integrations** (HTTP Actions) for calling external APIs directly from workflows\n- **UI Extensions** with `foundry-js` for client-side data fetching\n\n## Credential Management — No Secrets System Exists\n\n**There is no secrets management in Falcon Foundry.** When calling third-party REST APIs:\n\n| Scenario | Approach | Credentials |\n|----------|----------|-------------|\n| Third-party REST API (VirusTotal, Slack, Jira, etc.) | API integration in manifest + `APIIntegrations().execute_command_proxy()` | Platform-managed at install time |\n| CrowdStrike Falcon API | FalconPy zero-arg constructor (`Alerts()`, `Hosts()`) | Platform-managed automatically |\n| Third-party GraphQL API (no OpenAPI spec) | Function with `requests` + env var | Visible in app exports (⚠️ security risk) |\n\n**CRITICAL:** If the API has a REST endpoint and an OpenAPI spec exists, you MUST use an API integration. NEVER use `os.environ` with API keys, `requests.get()` with hardcoded URLs, or localStorage for credentials when an API integration can handle it. Raw HTTP with env vars technically works, but credentials are unencrypted and visible in app exports.\n\n## Reference Files\n\nThis skill is split across multiple files. Consult these for full examples:\n\n| Task | Reference |\n|------|-----------|\n| Python handler, collection CRUD, error class, batch processing, LogScale ingestion | [references/python-patterns.md](references/python-patterns.md) |\n| Go FDK handler, Falcon client auth, collection CRUD, alerts handler | [references/go-patterns.md](references/go-patterns.md) |\n| Falcon console testing (Python editor), function logs (viewing logs in UI and Advanced Event Search), Go/Python tests, local testing, Docker vs direct, config file patterns | [references/testing-patterns.md](references/testing-patterns.md) |\n\n## Resource Limits\n\n| Resource | Default | Maximum |\n|----------|---------|---------|\n| Request payload | — | 124 KB |\n| Response payload | — | 120 KB |\n| Execution timeout | 30s | 900s |\n| Memory | 256 MB | 1 GB |\n| Package size | — | 50 MB |\n| Concurrent executions | — | 100 |\n\n## Runtime Environment\n\n**Python runtime version: 3.13** (manylinux_2_28, glibc 2.28). When choosing package versions for `requirements.txt`, ensure they have wheels compatible with this environment. Packages requiring `manylinux_2_17` (glibc 2.17) or `manylinux_2_28` (glibc 2.28) are compatible; those requiring newer glibc versions (e.g., `manylinux_2_39`) may fail at import time.\n\nWhen linting Python functions with pylint, use `--py-version=3.13` or set `py-version=3.13` in `.pylintrc` to match the runtime.\n\n## CLI Scaffolding\n\n```bash\nfoundry functions create \\\n  --name \"my-function\" \\\n  --language python \\\n  --description \"Process incoming data\" \\\n  --handler-name process \\\n  --handler-method POST \\\n  --handler-path /api/process \\\n  --no-prompt\n```\n\n## Function Execution & Debugging\n\n> **Requires Foundry CLI 2.1.0+.** The commands below (`foundry functions exec`, `test`, `logs`) do not exist in CLI 2.0.x. If the user's CLI is below 2.1.0, inform them and offer to upgrade: `brew upgrade crowdstrike/foundry-cli/foundry`.\n\n> **⚠️ DEPLOY FIRST — `exec` and `test` run against the deployed Lambda, not local code.** Never deploy automatically; ask the user first.\n\nFor the full command reference, request-data confirmation workflow, tests.yml schema, and debugging steps, see [references/execution-and-testing.md](references/execution-and-testing.md).\n\nKey commands:\n\n```bash\nfoundry functions exec --handler <handler> '<json>' --no-prompt\nfoundry functions exec status <exec_id>\nfoundry functions logs <exec_id>\nfoundry functions test --no-prompt\n```\n\n## Reviewing Function Code\n\nBefore recommending a deploy, review the handler for logging adequacy, sensitive data, and schema coverage. See [references/code-review-checklist.md](references/code-review-checklist.md) for the full checklist.\n\n## Function I/O Schemas — Required at Creation Time\n\n> **⚠️ CRITICAL:** Functions called from workflows MUST be created with `--input-schema` and `--output-schema`. Schemas bind only at creation time. A function created without an output schema produces **no visible output** in its Fusion action — the action completes, but downstream steps cannot reference any data from it.\n\n### Why This Matters\n\nThe platform registers a handler's schemas with the workflow engine when the function is created. Without a response schema:\n- The Fusion action shows zero output fields\n- Workflow references like `${data['my_function.output.field']}` resolve to nothing\n- The workflow appears to run but produces empty results\n\nPassing `--wf-expose` alone is not enough. It creates the workflow binding; the schema fields are still written as `null`.\n\n### Create the Function with Schemas\n\nWrite the two JSON Schema files first, then pass them to `foundry functions create`. The CLI copies them into the function directory and records them in the manifest:\n\n```bash\nfoundry functions create \\\n  --name \"query-stats\" \\\n  --language python \\\n  --description \"Query execution statistics\" \\\n  --handler-name query \\\n  --handler-method POST \\\n  --handler-path /api/query \\\n  --input-schema request_schema.json \\\n  --output-schema response_schema.json \\\n  --wf-expose \\\n  --no-prompt\n```\n\nThe resulting manifest entry references the schemas **by filename on the handler** — not as inline JSON, and not under `workflow_integration`:\n\n```yaml\nfunctions:\n    - name: query-stats\n      path: functions/query-stats\n      handlers:\n        - name: query\n          method: POST\n          api_path: /api/query\n          request_schema: request_schema.json\n          response_schema: response_schema.json\n          workflow_integration:\n            id: <generated>\n            disruptive: false\n            system_action: true\n      language: python\n```\n\nWithout `--input-schema`/`--output-schema`, both fields are written as `null` — including when `--wf-expose` is set. `--wf-expose` creates the workflow binding but does NOT generate schemas.\n\n### Fixing a Function Missing Schemas\n\nAdding `request_schema`/`response_schema` to the manifest by hand and redeploying does NOT bind them. The binding happens only at creation time via the CLI flags. To fix a function that was created without them:\n\n1. Remove the function's entry from `manifest.yml` and delete its directory\n2. Recreate it with `--input-schema`/`--output-schema` as shown above\n3. Update any workflow YAML referencing it — the `workflow_integration.id` changes\n4. Redeploy\n\n**Warning:** Step 3 matters. Recreating the function gives it a new workflow integration ID, so existing workflow YAML points at nothing. Edit the workflow YAML in place to reference the new ID — do NOT delete and recreate the *workflows* to force a refresh, which triggers `409 name must be unique for an app` and can corrupt the app's dependency graph. See the `workflows-development` skill for details.\n\n## Language Comparison\n\n| Feature | Go | Python |\n|---------|-----|--------|\n| HTTP Methods | GET, POST, PUT, DELETE | GET, POST, PUT, PATCH, DELETE |\n| FDK Package | `github.com/CrowdStrike/foundry-fn-go` | `crowdstrike-foundry-function` |\n| CrowdStrike SDK | gofalcon | falconpy |\n| PATCH support | **No** | Yes |\n| UI Editor support | No | Yes |\n\nUse Go for performance-critical workloads, concurrency, and type safety. Use Python for rapid development, PATCH support, and UI Editor development.\n\n## Manifest Structure\n\n```yaml\nfunctions:\n  - name: gather-evidence\n    description: \"Collect evidence from multiple sources\"\n    language: python\n    path: \"functions/gather-evidence\"\n    environment_variables:\n      FALCON_CLIENT_ID: \"${secrets.falcon_client_id}\"\n      LOG_LEVEL: \"info\"\n    max_exec_duration_seconds: 30\n    max_exec_memory_mb: 128\n    handlers:\n      - name: process\n        method: POST\n        path: \"/api/investigations/{id}/evidence\"\n      - name: healthcheck\n        method: GET\n        path: \"/api/health\"\n```\n\nHandler fields: `name` (identifier), `method` (HTTP verb), `path` (route, supports `{param}` placeholders). A single function can expose multiple HTTP endpoints. Function description max 100 characters (alphanumeric only).\n\n## Go FDK Pattern\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"log/slog\"\n    fdk \"github.com/CrowdStrike/foundry-fn-go\"\n)\n\ntype greetingReq struct {\n    Name string `json:\"name\"`\n}\n\nfunc newHandler(_ context.Context, _ *slog.Logger, _ fdk.SkipCfg) fdk.Handler {\n    m := fdk.NewMux()\n    m.Post(\"/greetings\", fdk.HandleFnOf(func(ctx context.Context, r fdk.RequestOf[greetingReq]) fdk.Response {\n        return fdk.Response{\n            Code: 200,\n            Body: fdk.JSON(map[string]string{\"greeting\": \"Hello, \" + r.Body.Name}),\n        }\n    }))\n    return m\n}\n\nfunc main() {\n    fdk.Run(context.Background(), newHandler)\n}\n```\n\nKey FDK concepts: `fdk.SkipCfg` (no config file), `fdk.NewMux()` (router), `fdk.HandleFnOf[T]` (typed handler), `fdk.RequestOf[T]` (typed request with `.Body`, `.Params`, `.URL`, `.Method`), `fdk.JSON()` (response body helper).\n\n### Go Authentication\n\nGo requires explicit credential wiring through the FDK. Use `fdk.FalconClientOpts()` for correct cloud and user-agent configuration:\n\n```go\nopts := fdk.FalconClientOpts()\nfalconClient, err := falcon.NewClient(&falcon.ApiConfig{\n    AccessToken:       accessToken,\n    Cloud:             falcon.Cloud(opts.Cloud),\n    Context:           ctx,\n    UserAgentOverride: opts.UserAgent,\n})\n```\n\n## Python FDK Pattern\n\n```python\nfrom logging import Logger\nfrom typing import Any, Dict, Union\nfrom crowdstrike.foundry.function import Function, Request, Response\n\nfunc = Function.instance()\n\n@func.handler(method='POST', path='/greetings')\ndef on_post(request: Request, config: Union[Dict[str, Any], None], logger: Logger) -> Response:\n    name = request.body.get(\"name\", \"World\")\n    return Response(body={'greeting': f'Hello, {name}!'}, code=200)\n\n@func.handler(method='GET', path='/health')\ndef on_get(request: Request, config: Union[Dict[str, Any], None], logger: Logger) -> Response:\n    return Response(body={'status': 'ok'}, code=200)\n\nif __name__ == '__main__':\n    func.run()\n```\n\n### Python Authentication\n\nFalconPy handles credential discovery automatically. Call Service Class constructors with zero arguments:\n\n```python\nfrom falconpy import Alerts\nfalcon = Alerts()  # Auth is automatic — do not pass credentials\n```\n\n- **In Foundry cloud**: Uses context-based authentication (injected by the platform)\n- **Locally**: Reads `FALCON_CLIENT_ID` and `FALCON_CLIENT_SECRET` from environment variables\n\nFalconPy already reads env vars internally, so writing a `get_falcon_client()` wrapper that manually reads credentials adds no value and breaks context auth in the cloud.\n\n### Calling Registered API Integrations from Functions\n\nWhen your app has an API integration registered in `manifest.yml`, call it from functions using FalconPy's `APIIntegrations` class. Do NOT make raw HTTP calls (urllib/requests) to the third-party API — always go through the Foundry platform proxy:\n\n```python\nfrom falconpy import APIIntegrations\n\napi = APIIntegrations()  # Zero-arg auth, same as other FalconPy classes\n\n# Call using definition_id + operation_id from your manifest\nresponse = api.execute_command_proxy(\n    body={\n        \"resources\": [\n            {\n                \"definition_id\": \"ZscalerAPI\",      # matches manifest api_integrations name\n                \"operation_id\": \"urlLookup\",        # matches OpenAPI spec operationId\n            }\n        ]\n    },\n)\n```\n\nFor APIs that need a request body or query parameters:\n\n```python\nresponse = api.execute_command_proxy(\n    body={\n        \"resources\": [\n            {\n                \"definition_id\": \"Anomali API\",\n                \"operation_id\": \"Intelligence\",\n                \"request\": {\n                    \"params\": {\n                        \"query\": {\"type\": \"ip\", \"value\": ip_address}\n                    }\n                },\n            }\n        ]\n    },\n)\n```\n\n**Why the proxy?** The platform manages OAuth tokens, rate limiting, and audit logging for registered integrations. Raw HTTP calls bypass all of this — while they can work with hardcoded or env-var credentials, those values are stored unencrypted and visible to anyone who exports the app.\n\n**Local testing note:** When testing locally, you may need the UUID `definition_id` from `manifest.yml` (assigned by the platform). In production, the human-readable integration name (e.g., `\"ZscalerAPI\"`) works as the `definition_id` value.\n\nReference implementations:\n- [foundry-sample-zscaler-internet-access](https://github.com/CrowdStrike/foundry-sample-zscaler-internet-access) (6 functions using `execute_command_proxy`)\n- [foundry-sample-anomali-threatstream](https://github.com/CrowdStrike/foundry-sample-anomali-threatstream) (IOC ingestion via API integration)\n- [foundry-sample-openrouter-toolkit](https://github.com/CrowdStrike/foundry-sample-openrouter-toolkit) (`execute_command` variant)\n\n### requirements.txt Best Practices\n\nPin all dependencies to exact versions (`==`) for reproducible builds and supply chain safety. The one exception is `crowdstrike-falconpy`, which should be left unpinned so functions always pick up the latest SDK (needed for context-based auth and new service classes). Ensure the file ends with a trailing newline.\n\n```\ncrowdstrike-foundry-function==1.1.4\ncrowdstrike-falconpy\n```\n\n## Workflow Array Output\n\nWhen a function returns array data to a workflow, wrap the array in a JSON object. Direct array returns are not supported by the workflow engine:\n\n```python\n# Correct — workflows can reference $step.output.items\nreturn Response(body={'items': [{'id': 1}, {'id': 2}]}, code=200)\n\n# Breaks workflow variable resolution\nreturn Response(body=[{'id': 1}, {'id': 2}], code=200)\n```\n\n## Error Handling\n\nReturn structured JSON with status codes. MUST NOT leak raw stack traces:\n\n```python\ntry:\n    result = process(request.body)\n    return Response(body={\"status\": 200, \"data\": result}, code=200)\nexcept ValueError as e:\n    return Response(body={\"error\": {\"code\": \"INVALID_INPUT\", \"message\": str(e)}}, code=400)\nexcept Exception:\n    return Response(body={\"error\": {\"code\": \"INTERNAL_ERROR\", \"message\": \"An unexpected error occurred\"}}, code=500)\n```\n\nFor the full `FunctionError` class with enum codes, see [references/python-patterns.md](references/python-patterns.md).\n\n## Common Pitfalls\n\n- **Using `requests` instead of CrowdStrike SDKs.** The SDKs handle auth, retries, regions, and error parsing.\n- **Using `APIHarnessV2` (Uber class) for collection operations.** Use `CustomStorage` service class instead so the Foundry functions editor can auto-detect OAuth scopes. See the Collection CRUD Pattern in [references/python-patterns.md](references/python-patterns.md).\n- **Manually reading env vars for FalconPy auth.** `Alerts()` with zero arguments handles all credential discovery.\n- **Shared utility files across functions.** `sys.path.append(\"../\")` works locally but not in Foundry's FaaS runtime. Copy shared files into each function directory.\n- **`SearchObjects` returns metadata, not objects.** Follow up with `GetObject` to retrieve actual content. For bulk reads, use FQL filters to narrow the search rather than fetching all keys and reading them one by one in a loop.\n- **Returning arrays directly to workflows.** Wrap in a JSON object (`{'items': [...]}` not `[...]`).\n- **Using PATCH with Go functions.** Go only supports GET, POST, PUT, DELETE.\n- **Using `definition_id` vs. name for API integrations.** When testing locally, use the UUID `definition_id` from `manifest.yml`. In production, the human-readable name (e.g., `\"ZscalerAPI\"`) works as the `definition_id` value. See the [Calling Registered API Integrations](#calling-registered-api-integrations-from-functions) section above.\n- **Making raw HTTP calls to third-party APIs.** When an API integration is registered in the manifest, MUST use `APIIntegrations().execute_command_proxy()`. Raw urllib/requests calls can technically work with hardcoded credentials or env vars, but credentials are stored unencrypted and visible in app exports — a security risk. Always prefer the API integration path.\n\n## Use Cases\n\nFor real-world implementation patterns, see:\n- `use-cases/python-functions.md` — Python handler patterns, SDK usage, testing\n- `use-cases/logscale-ingestion.md` — Ingesting custom data into Falcon LogScale\n- `use-cases/api-pagination.md` — Pagination strategies in functions and workflows\n\n## Reference Implementations\n\n- **[foundry-sample-functions-python](https://github.com/CrowdStrike/foundry-sample-functions-python)**: Reference Python function patterns. See also [Dive into Falcon Foundry Functions with Python](https://www.crowdstrike.com/tech-hub/ng-siem/dive-into-falcon-foundry-functions-with-python/).\n- **[foundry-sample-anomali-threatstream](https://github.com/CrowdStrike/foundry-sample-anomali-threatstream)**: Side-by-side Go and Python auth patterns.\n- **[foundry-sample-logscale](https://github.com/CrowdStrike/foundry-sample-logscale)**: LogScale ingestion patterns.\n- **[foundry-sample-servicenow-itsm](https://github.com/CrowdStrike/foundry-sample-servicenow-itsm)**: Go function patterns with ServiceNow integration.\n- **[foundry-sample-ngsiem-importer](https://github.com/CrowdStrike/foundry-sample-ngsiem-importer)**: Python function for importing threat intel into NG-SIEM.\n"
}