/security-patterns

name: security-patterns
description: Security patterns for Falcon Foundry apps including OAuth scopes, RBAC, input validation, UI security, and credential management. TRIGGER when user asks to "configure OAuth scopes", "secure a Foundry app", "handle secrets", "add input validation", or needs to review a Foundry app for security concerns (XSS, CSP, credential management). Also trigger during pre-deployment security reviews.
version: 1.7.1
updated: 2026-11-10
tags: [foundry, oauth, rbac, xss, csp]
author: CrowdStrike
license: MIT
compatibility: Claude Code >=1.0
metadata:
  category: security

Foundry Security Patterns

> **Part of a suite.** If `development-workflow` has not already run, and this is a new app or its first capability, load the `development-workflow` skill first — it owns the CLI prerequisite check, scaffolding order, and manifest coordination.

Security patterns for Falcon Foundry app development covering authentication, input validation, UI security, and platform-specific considerations. Foundry apps run on a cybersecurity platform — security is a core requirement.

RBAC (Role-Based Access Control)

| Capability | RBAC Supported | |-----------|----------------| | Collections | Yes | | Dashboards | Yes | | Functions | Yes | | UI extensions / pages / navigation | Yes | | RTR scripts | Yes | | API integrations | **No** | | Queries | **No** | | Workflows | **No** |

The Permission → Role → Artifact Model

RBAC is three linked pieces the table above doesn't spell out — you need all three or the gate is silently absent.

**1. Permission** (one command, also creates the role):

foundry auth permissions create \
  --key "myapp:access" \
  --name "My App Access" \
  --description "Access to My App" \
  --role-name "My App Operator" \
  --role-description "My App operator role" \
  --no-prompt

**`--key` must be colon-segmented** (`myapp:access`, not a plain word; otherwise `invalid permission key, should be permission segments separated by :`), and **`--description` must be 50 characters or fewer** (`input must be at most 50 characters long`). `--name` needs at least 3 characters and `--role-description` at least 5. The command writes `auth.permissions["myapp:access"]: {id, name, description}` into `manifest.yml` and adds the role to `auth.roles`, with the permission key in its `permissions` list.

> **Prefix the key and role name with your app name.** A generic name (`app:access`, `Operator`) is hard to tell apart from other apps' roles in the console's role list.

**2. Role** — appears automatically under `auth.roles` after step 1; inspect it there, and do NOT run `foundry auth roles create` for it (that would orphan a duplicate role). Reserve standalone `foundry auth roles create` for a role built *independently* of `permissions create` — e.g. one that bundles permission keys that already exist (via `--permissions`); it creates a role but no permission:

foundry auth roles create --name "Analyst" --permissions "myapp:access" --description "Read-only analyst access" --no-prompt

That makes a second role carrying already-created permission keys; it does NOT create a new permission. Use it only when you deliberately want a role separate from the one `permissions create` already made — never to "add" the role from step 1.

**3. Artifact gates** — pass `--permissions "myapp:access"` to `collections create`, `functions create`, `ui pages create`, `ui extensions create`, or `ui navigation add` (CLI 2.1.2), or add the permission **key** to the `permissions:` list the CLI already wrote on an existing artifact ([docs](https://docs.crowdstrike.com/access?ft:originId=w88f0d03)). Edit only that list; leave the generated `path`, `entrypoint`, and `ref` values alone. The page gate is what blocks access; a gate on the navigation link only hides the menu entry (Foundry checks roles on pages, not links), so set both:

ui:
  pages:
    dashboard:                       # pages is a map keyed by page ID
      name: dashboard
      path: ui/pages/dashboard/src/dist
      entrypoint: ui/pages/dashboard/src/dist/index.html
      permissions: [ "myapp:access" ]
  navigation:
    links:
      - path: /
        name: Dashboard
        permissions: [ "myapp:access" ]
        ref: pages.dashboard
collections:
  - name: app_config
    schema: collections/app_config.json
    permissions: [ "myapp:access" ]

`foundry apps validate --no-prompt` is a free syntax check before deploying. A full end-to-end manifest example is in [references/security-examples.md](references/security-examples.md).

New roles auto-assign to all Falcon Administrators

`foundry auth roles create --help` says: *"Your new role will be automatically assigned to all Falcon Administrators and can later be assigned to other users individually."* The same applies to the role `permissions create` makes. Implications:

• The console role view shows **"0 users"** — that counts only *explicit* assignments; the Falcon Admin grant is implicit and invisible there. The role is active even at zero.
• **RBAC can't exclude Falcon Administrators** — admins always hold the permission and bypass every gate, so you can't lock them *out*. Restricting an app *to* admins is the easy direction: create the permission and simply never assign its role to a non-admin.
• It **cushions lockout**: if your own account is a Falcon Admin you keep implicit access even if you forget to assign the role before release. Assign explicitly anyway.

Lockout-safe RBAC rollout

Turning on RBAC is the one change that can lock you out of your own app mid-release. Safe sequence:

1. `foundry auth permissions create` — permission + role into the manifest. 2. `foundry apps deploy --change-type Minor --change-log "Add RBAC" --no-prompt` — the gate is in the deployment but not live until you release. 3. **Assign the role in the Falcon console** (Users → Roles & Permissions) to yourself and everyone who should keep access, befo