functions-development

---
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.
version: 1.6.0
updated: 2026-10-01
tags: [foundry, functions, serverless, python, go, execution, debugging, logs, testing]
author: CrowdStrike
license: MIT
compatibility: Claude Code >=1.0
metadata:
  category: backend
---

# Foundry Functions Development

> **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.
>
> When you implement or modify functions:
> 1. Use CrowdStrike SDKs (gofalcon/falconpy) for ALL API interactions
> 2. Implement structured JSON responses with proper status codes
> 3. Apply input validation before processing any request

Falcon 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.

## Functions as a Last Resort

Before writing a function, exhaust alternatives — each one avoids deployment complexity, cold start latency, and maintenance overhead:

- **Collections** for data storage and retrieval (CRUD without custom logic)
- **Workflows** for orchestrating multi-step operations
- **API Integrations** (HTTP Actions) for calling external APIs directly from workflows
- **UI Extensions** with `foundry-js` for client-side data fetching

## Credential Management — No Secrets System Exists

**There is no secrets management in Falcon Foundry.** When calling third-party REST APIs:

| Scenario | Approach | Credentials |
|----------|----------|-------------|
| Third-party REST API (VirusTotal, Slack, Jira, etc.) | API integration in manifest + `APIIntegrations().execute_command_proxy()` | Platform-managed at install time |
| CrowdStrike Falcon API | FalconPy zero-arg constructor (`Alerts()`, `Hosts()`) | Platform-managed automatically |
| Third-party GraphQL API (no OpenAPI spec) | Function with `requests` + env var | Visible in app exports (⚠️ security risk) |

**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.

## Reference Files

This skill is split across multiple files. Consult these for full examples:

| Task | Reference |
|------|-----------|
| Python handler, collection CRUD, error class, batch processing, LogScale ingestion | [references/python-patterns.md](references/python-patterns.md) |
| Go FDK handler, Falcon client auth, collection CRUD, alerts handler | [references/go-patterns.md](references/go-patterns.md) |
| 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) |

## Resource Limits

| Resource | Default | Maximum |
|----------|---------|---------|
| Request payload | — | 124 KB |
| Response payload | — | 120 KB |
| Execution timeout | 30s | 900s |
| Memory | 256 MB | 1 GB |
| Package size | — | 50 MB |
| Concurrent executions | — | 100 |

## Runtime Environment

**Python: develop on 3.14.** The docs state only a minimum (3.9+) and the platform moves faster than them, so use the latest release. The runtime is manylinux_2_28 (glibc 2.28): pick `requirements.txt` versions with `manylinux_2_17` or `manylinux_2_28` wheels; wheels needing newer glibc (e.g., `manylinux_2_39`) may fail at import time. Run tests in a venv built like CI's, not the global interpreter — see [testing-patterns](references/testing-patterns.md).

## CLI Scaffolding

```bash
foundry functions create \
  --name "my-function" \
  --language python \
  --description "Process incoming data" \
  --handler-name process \
  --handler-method POST \
  --handler-path /api/process \
  --max-exec-duration-seconds 60 \
  --max-exec-memory-mb 256 \
  --no-prompt
```

The two `--max-exec-*` flags write the manifest's `max_exec_duration_seconds` / `max_exec_memory_mb`; set them at create time instead of hand-editing later.

## Function Execution & Debugging

> **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`.

> **⚠️ DEPLOY FIRST — `exec` and `test` run against the deployed Lambda, not local code.** Never deploy automatically; ask the user first.

For 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).

Key commands:

```bash
foundry functions exec --handler <handler> '<json>' --no-prompt
foundry functions exec status <exec_id>
foundry functions logs <exec_id>
foundry functions test --no-prompt
```

## Reviewing Function Code

Before 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.

## Function I/O Schemas — Required at Creation Time

> **⚠️ 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.

### Why This Matters

The platform registers a handler's schemas with the workflow engine when the function is created. Without a response schema:
- The Fusion action shows zero output fields
- Workflow references like `${data['my_function.output.field']}` resolve to nothing
- The workflow appears to run but produces empty results

Passing `--wf-expose` alone is not enough. It creates the workflow binding; the schema fields are still written as `null`.

### Create the Function with Schemas

Write 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:

```bash
foundry functions create \
  --name "query-stats" \
  --language python \
  --description "Query execution statistics" \
  --handler-name query \
  --handler-method POST \
  --handler-path /api/query \
  --input-schema request_schema.json \
  --output-schema response_schema.json \
  --wf-expose \
  --no-prompt
```

The resulting manifest entry references the schemas **by filename on the handler** — not as inline JSON, and not under `workflow_integration`:

```yaml
functions:
    - name: query-stats
      path: functions/query-stats
      handlers:
        - name: query
          method: POST
          api_path: /api/query
          request_schema: request_schema.json
          response_schema: response_schema.json
          workflow_integration:
            id: <generated>
            disruptive: false
            system_action: true
      language: python
```

Without `--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.

### Fixing a Function Missing Schemas

Adding `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:

1. Remove the function's entry from `manifest.yml` and delete its directory
2. Recreate it with `--input-schema`/`--output-schema` as shown above
3. Update any workflow YAML referencing it — the `workflow_integration.id` changes
4. Redeploy

**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.

## Language Comparison

| Feature | Go | Python |
|---------|-----|--------|
| HTTP Methods | GET, POST, PUT, DELETE | GET, POST, PUT, PATCH, DELETE |
| FDK Package | `github.com/CrowdStrike/foundry-fn-go` | `crowdstrike-foundry-function` |
| CrowdStrike SDK | gofalcon | falconpy |
| PATCH support | **No** | Yes |
| UI Editor support | No | Yes |

Use Go for performance-critical workloads, concurrency, and type safety. Use Python for rapid development, PATCH support, and UI Editor development.

## Manifest Structure

```yaml
functions:
  - name: gather-evidence
    description: "Collect evidence from multiple sources"
    language: python
    path: "functions/gather-evidence"
    environment_variables:
      FALCON_CLIENT_ID: "${secrets.falcon_client_id}"
      LOG_LEVEL: "info"
    max_exec_duration_seconds: 30
    max_exec_memory_mb: 128
    handlers:
      - name: process
        method: POST
        api_path: "/api/investigations/evidence"
      - name: healthcheck
        method: GET
        api_path: "/api/health"
```

Handler fields: `name`, `method`, `api_path`. One function can expose several endpoints. The Python FDK matches `api_path` exactly (no `{param}` placeholders), so pass IDs in the body or query. Descriptions are length-checked only: 1024 characters per function, 512 per handler.

### Adding a Handler to an Existing Function

No CLI command adds a handler to an existing function. Append an entry (`name`, `method`, `api_path`) to that function's `handlers:` list in `manifest.yml` and add the matching `@func.handler(...)` (or Go route). This is a narrow exception to the no-manifest-edits rule, like the `ai.agents[].model` carve-out: touch only that `handlers:` list. Hand-added handlers get no bound I/O schemas, so a handler that must be a Fusion action with visible outputs needs its own CLI-created function.

## Go FDK Pattern

```go
package main

import (
    "context"
    "log/slog"
    fdk "github.com/CrowdStrike/foundry-fn-go"
)

type greetingReq struct {
    Name string `json:"name"`
}

func newHandler(_ context.Context, _ *slog.Logger, _ fdk.SkipCfg) fdk.Handler {
    m := fdk.NewMux()
    m.Post("/greetings", fdk.HandleFnOf(func(ctx context.Context, r fdk.RequestOf[greetingReq]) fdk.Response {
        return fdk.Response{
            Code: 200,
            Body: fdk.JSON(map[string]string{"greeting": "Hello, " + r.Body.Name}),
        }
    }))
    return m
}

func main() {
    fdk.Run(context.Background(), newHandler)
}
```

Key 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).

### Go Authentication

Go requires explicit credential wiring through the FDK. Use `fdk.FalconClientOpts()` for correct cloud and user-agent configuration:

```go
opts := fdk.FalconClientOpts()
falconClient, err := falcon.NewClient(&falcon.ApiConfig{
    AccessToken:       accessToken,
    Cloud:             falcon.Cloud(opts.Cloud),
    Context:           ctx,
    UserAgentOverride: opts.UserAgent,
})
```

## Python FDK Pattern

```python
from logging import Logger
from typing import Any, Dict, Union
from crowdstrike.foundry.function import Function, Request, Response

func = Function.instance()

@func.handler(method='POST', path='/greetings')
def on_post(request: Request, config: Union[Dict[str, Any], None], logger: Logger) -> Response:
    name = request.body.get("name", "World")
    return Response(body={'greeting': f'Hello, {name}!'}, code=200)

@func.handler(method='GET', path='/health')
def on_get(request: Request, config: Union[Dict[str, Any], None], logger: Logger) -> Response:
    return Response(body={'status': 'ok'}, code=200)

if __name__ == '__main__':
    func.run()
```

### The `Request` Object

No `request.query`, and `request.params` has no `.get()`: query params and headers are `request.params.query` / `.header`, both `Dict[str, List[str]]` (`request.params.query.get("limit", ["50"])[0]`). Field table: [references/python-patterns.md](references/python-patterns.md#the-request-object).

### Python Authentication

FalconPy handles credential discovery automatically. Call Service Class constructors with zero arguments:

```python
from falconpy import Alerts
falcon = Alerts()  # Auth is automatic — do not pass credentials
```

- **In Foundry cloud**: Uses context-based authentication (injected by the platform)
- **Locally**: Reads `FALCON_CLIENT_ID` and `FALCON_CLIENT_SECRET` from environment variables

FalconPy 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.

> **Construct FalconPy clients inside the handler, never at module scope.** Context auth only has the request's bearer token while a request is being handled; a module-level `falcon = Alerts()` (or `APIHarnessV2()`, `CustomStorage()`, `APIIntegrations()`) is built at import with no token and returns `401` on every call despite correct scopes.

### Calling Registered API Integrations from Functions

When 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:

```python
from falconpy import APIIntegrations

api = APIIntegrations()  # Zero-arg auth, same as other FalconPy classes

# Call using definition_id + operation_id from your manifest
response = api.execute_command_proxy(
    body={
        "resources": [
            {
                "definition_id": "ZscalerAPI",      # matches manifest api_integrations name
                "operation_id": "urlLookup",        # matches OpenAPI spec operationId
            }
        ]
    },
)
```

For APIs that need a request body or query parameters:

```python
response = api.execute_command_proxy(
    body={
        "resources": [
            {
                "definition_id": "Anomali API",
                "operation_id": "Intelligence",
                "request": {
                    "params": {
                        "query": {"type": "ip", "value": ip_address}
                    }
                },
            }
        ]
    },
)
```

**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.

**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.

Reference implementations:
- [foundry-sample-zscaler-internet-access](https://github.com/CrowdStrike/foundry-sample-zscaler-internet-access) (6 functions using `execute_command_proxy`)
- [foundry-sample-anomali-threatstream](https://github.com/CrowdStrike/foundry-sample-anomali-threatstream) (IOC ingestion via API integration)
- [foundry-sample-openrouter-toolkit](https://github.com/CrowdStrike/foundry-sample-openrouter-toolkit) (`execute_command` variant)

### requirements.txt Best Practices

Pin 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.

```
crowdstrike-foundry-function==1.1.4
crowdstrike-falconpy
```

## Workflow Array Output

When 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:

```python
# Correct — workflows can reference $step.output.items
return Response(body={'items': [{'id': 1}, {'id': 2}]}, code=200)

# Breaks workflow variable resolution
return Response(body=[{'id': 1}, {'id': 2}], code=200)
```

## Error Handling

Return structured JSON with status codes. MUST NOT leak raw stack traces:

```python
try:
    result = process(request.body)
    return Response(body={"status": 200, "data": result}, code=200)
except ValueError as e:
    return Response(body={"error": {"code": "INVALID_INPUT", "message": str(e)}}, code=400)
except Exception:
    return Response(body={"error": {"code": "INTERNAL_ERROR", "message": "An unexpected error occurred"}}, code=500)
```

For the full `FunctionError` class with enum codes, see [references/python-patterns.md](references/python-patterns.md).

## Common Pitfalls

- **Using `requests` instead of CrowdStrike SDKs.** The SDKs handle auth, retries, regions, and error parsing.
- **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).
- **Manually reading env vars for FalconPy auth.** `Alerts()` with zero arguments handles all credential discovery.
- **Constructing FalconPy clients at module scope.** `falcon = Alerts()` above the handler runs at import, before the FDK has a request token, so every call returns `401 Unauthorized`. Construct clients inside the handler.
- **`request.query` or `request.params.get()`.** Neither exists; use `request.params.query["limit"][0]` (values are lists).
- **Shared utility files across functions.** `sys.path.append("../")` works locally but not in Foundry's FaaS runtime. Copy shared files into each function directory.
- **`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.
- **Returning arrays directly to workflows.** Wrap in a JSON object (`{'items': [...]}` not `[...]`).
- **Using PATCH with Go functions.** Go only supports GET, POST, PUT, DELETE.
- **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.
- **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.

## Use Cases

For real-world implementation patterns, see:
- `use-cases/python-functions.md` — Python handler patterns, SDK usage, testing
- `use-cases/logscale-ingestion.md` — Ingesting custom data into Falcon LogScale
- `use-cases/api-pagination.md` — Pagination strategies in functions and workflows

## Reference Implementations

- **[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/).
- **[foundry-sample-anomali-threatstream](https://github.com/CrowdStrike/foundry-sample-anomali-threatstream)**: Side-by-side Go and Python auth patterns.
- **[foundry-sample-logscale](https://github.com/CrowdStrike/foundry-sample-logscale)**: LogScale ingestion patterns.
- **[foundry-sample-servicenow-itsm](https://github.com/CrowdStrike/foundry-sample-servicenow-itsm)**: Go function patterns with ServiceNow integration.
- **[foundry-sample-ngsiem-importer](https://github.com/CrowdStrike/foundry-sample-ngsiem-importer)**: Python function for importing threat intel into NG-SIEM.

From crowdstrike/foundry-skills at ec792c5, shown as plain text under its license: MIT (permissive). The license text is in skills/functions-development/SKILL.md.

• SKILL.md22 KB · 75e1c773a3bc
• references/
• code-review-checklist.md5.8 KB · f919a2fc42f0
• execution-and-testing.md26 KB · e8997288a5a9
• go-patterns.md6.8 KB · 2eba409b628a
• python-patterns.md14 KB · e783837c573a
• testing-patterns.md9.8 KB · 2cfccb962247

6 files, 84 KB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.