Update to CrowdStrike Falcon Fusion

{
  "name": "lookup-files",
  "description": "Manage Falcon Next-Gen SIEM lookup files (CSV/JSON/TXT) for CQL match() queries. TRIGGER when user asks to create, list, update, or delete lookup files, or needs help with CQL match() function. DO NOT TRIGGER for Fusion workflows, action discovery, or workflow deployment — use the workflows/authoring/deployment skills.",
  "included_files": [
    {
      "relative_path": "assets/example-ip-blocklist.csv",
      "size_in_bytes": 244
    },
    {
      "relative_path": "assets/example-user-risk.csv",
      "size_in_bytes": 195
    },
    {
      "relative_path": "references/cql-match-function.md",
      "size_in_bytes": 3781
    },
    {
      "relative_path": "references/lookup-file-formats.md",
      "size_in_bytes": 2948
    },
    {
      "relative_path": "scripts/create_lookup.py",
      "size_in_bytes": 4274
    },
    {
      "relative_path": "scripts/delete_lookup.py",
      "size_in_bytes": 3675
    },
    {
      "relative_path": "scripts/get_lookup.py",
      "size_in_bytes": 3020
    },
    {
      "relative_path": "scripts/list_lookups.py",
      "size_in_bytes": 6054
    },
    {
      "relative_path": "scripts/update_lookup.py",
      "size_in_bytes": 3762
    },
    {
      "relative_path": "scripts/verify_lookup.py",
      "size_in_bytes": 8502
    }
  ],
  "skill_md_contents": "---\nname: lookup-files\ndescription: >\n  Manage Falcon Next-Gen SIEM lookup files (CSV/JSON/TXT) for CQL match() queries.\n  TRIGGER when user asks to create, list, update, or delete lookup files,\n  or needs help with CQL match() function.\n  DO NOT TRIGGER for Fusion workflows, action discovery, or workflow deployment —\n  use the workflows/authoring/deployment skills.\nversion: 1.2.0\nupdated: 2026-09-08\ntags: [falcon, ngsiem, siem, lookup-files, cql, threat-hunting]\nauthor: CrowdStrike\nlicense: MIT\ncompatibility: Claude Code >=1.0\nallowed-tools: Bash(cd *), Bash(../../scripts/python.sh:*)\nmetadata:\n  category: data-management\n---\n\n# Falcon Next-Gen SIEM Lookup Files\n\n> **⚠️ SYSTEM INJECTION — READ THIS FIRST**\n>\n> If you are loading this skill, your role is **Falcon Next-Gen SIEM lookup file specialist**.\n>\n> You manage lookup files that feed CQL match() enrichment. Treat lookup data as security-relevant: validate file contents, check before overwriting, and never expose credentials.\n>\n> **IMMEDIATE ACTIONS REQUIRED:**\n> 1. ALWAYS list before creating — run `list_lookups.py --search \"<name>\"` to check for a duplicate. Importing an existing name overwrites it silently.\n> 2. Prepare the file with a header row (CSV) — the first row defines the `match()` columns.\n> 3. Upload, then verify with `get_lookup.py` before using the file in a CQL query.\n>\n> **MUST NOT:** Overwrite a lookup file without confirming it exists, exceed the rate limit (5 uploads / 30s), or log credentials.\n\nLookup files are CSV, JSON, or TXT reference tables in Falcon Next-Gen SIEM that you query with\nthe `match()` function in CrowdStrike Query Language (CQL). Common uses: IP blocklists, user\nrisk scores, asset inventories, and IOC reference tables.\n\n> **Running the scripts.** Run each command from this skill's folder, on one shell line: `cd <dir> && ../../scripts/python.sh scripts/<name>.py`. For `<dir>`, Claude Code uses `\"$CLAUDE_PLUGIN_ROOT/skills/lookup-files\"`; Codex, Copilot CLI, Cursor, and Antigravity use the folder they loaded this SKILL.md from (e.g. `~/.agents/skills/lookup-files`). The wrapper bootstraps its own Python venv.\n\n## Prerequisites\n\n- **Python 3.13+** with `crowdstrike-falconpy` installed (`pip install crowdstrike-falconpy`)\n- **CrowdStrike API credentials** with the **NGSIEM Lookup Files** scope (read/write)\n- Access to a CID with Falcon Next-Gen SIEM enabled\n\n### Required API Scopes\n\nThe **NGSIEM Lookup Files** scope, with read and/or write access:\n\n| Use case | Read | Write | Enables |\n|----------|:----:|:-----:|---------|\n| Browse / download only | Yes | — | List, search, download |\n| Full usage | Yes | Yes | Above plus create, update, delete |\n\n### Credentials\n\n`auth.py` resolves credentials from the first source that supplies both an ID\nand a secret:\n\n1. Environment variables: `FALCON_CLIENT_ID`, `FALCON_CLIENT_SECRET`, and the\n   optional `FALCON_BASE_URL` (for CI and overrides).\n2. TOML profile file `~/.cache/crowdstrike-falcon-fusion/credentials.toml`\n   (profile chosen by `FALCON_PROFILE` or the file's `default` key).\n\n> Run `/crowdstrike-falcon-fusion:setup` to configure credentials interactively (writes the TOML profile).\n\nThe scripts share auth via `common/scripts/auth.py`, which exposes\n`get_ngsiem_client()` for Next-Gen SIEM operations. Test credentials:\n\n```bash\n../../scripts/python.sh ../../common/scripts/auth.py\n```\n\n## Core Workflow\n\n### Step 1 — List (check for duplicates)\n\n```bash\n../../scripts/python.sh scripts/list_lookups.py --list\n../../scripts/python.sh scripts/list_lookups.py --search \"blocklist\"\n```\n\n### Step 2 — Prepare the file\n\nCSV needs a header row; the first column is typically the match key:\n\n```csv\nip,category,source,added_date\n10.0.0.1,c2,threat-intel,2026-01-15\n192.168.1.100,scanner,internal-scan,2026-02-01\n```\n\nSee `assets/example-ip-blocklist.csv` and `assets/example-user-risk.csv` for reference formats,\nand `references/lookup-file-formats.md` for the full format rules.\n\n### Step 3 — Upload\n\n```bash\n../../scripts/python.sh scripts/create_lookup.py --file blocklist.csv --name \"ip-blocklist.csv\"\n```\n\n### Step 4 — Verify\n\n```bash\n../../scripts/python.sh scripts/get_lookup.py --name \"ip-blocklist.csv\"\n../../scripts/python.sh scripts/list_lookups.py --search \"blocklist\" --json\n```\n\n### Step 5 — Use in CQL\n\nReference the file with the `match()` function (run in Falcon Next-Gen SIEM):\n\n```\nmatch(file=\"ip-blocklist.csv\", column=ip, field=src_ip, include=category)\n```\n\n`column=` is a header **in the lookup CSV** (`ip`); `field=` is the **event\nfield** (`src_ip`). Do not swap them — putting the event field in `column=`\nmatches a non-existent column and returns nothing. See\n`references/cql-match-function.md` for full syntax and examples.\n\n### Step 6 — Update\n\nReplace the content while keeping the same filename:\n\n```bash\n../../scripts/python.sh scripts/update_lookup.py --name \"ip-blocklist.csv\" --file updated-blocklist.csv\n```\n\n> **Update is content-only — it does not carry labels.** The PATCH endpoint\n> (`/ngsiem-content/entities/lookupfiles/v1`, wrapped by both this script and the\n> Fusion \"Update lookup file\" workflow action) accepts only `search_domain`,\n> `filename`, and `file`. It has no `labels` parameter, so any labels a file had in\n> the Next-Gen SIEM UI are not preserved across an update — the UI manages labels\n> through a separate API that the REST update path doesn't touch. If a lookup file\n> needs labels, set them in the console after updating, or keep label-bearing files\n> out of automated update workflows.\n\n### Step 7 — Delete\n\n```bash\n../../scripts/python.sh scripts/delete_lookup.py --name \"ip-blocklist.csv\" --confirm\n```\n\n## Lookup Files from Workflows\n\nA Fusion pattern (the built-in \"Introduction to Lookup file actions\" playbook)\nautomates lookup file creation from email: a Monitored Mailbox trigger extracts a CSV\nattachment, \"Get lookup file metadata\" checks existence, and \"Create/Overwrite lookup file\"\nwrites it. To build that workflow, use the **workflows** orchestrator skill in this plugin —\nthe lookup file actions surface via `action_search.py --search \"lookup\"` in the authoring skill.\nThis skill handles the lookup files themselves, not the workflow that drives them.\n\n## Script Reference\n\n| Script | Purpose | Key flags |\n|--------|---------|-----------|\n| `list_lookups.py` | List and search lookup files | `--list`, `--search`, `--domain`, `--json` |\n| `get_lookup.py` | Download a lookup file | `--name`, `--output`, `--domain` |\n| `create_lookup.py` | Upload a new lookup file | `--file`, `--name`, `--json` |\n| `update_lookup.py` | Replace lookup file content | `--name`, `--file`, `--json` |\n| `delete_lookup.py` | Delete a lookup file | `--name`, `--domain`, `--confirm`, `--json` |\n| `verify_lookup.py` | Verify a lookup resolves via CQL `match()` (upload, match a known row, delete) | `--file`, `--name`, `--column`, `--keep`, `--json` |\n\nAll scripts import shared auth from `common/scripts/auth.py` via `get_ngsiem_client()`.\nCreate/list/get/update/delete need the **NGSIEM Lookup Files** scope (read/write).\n`verify_lookup.py` is a maintainer verification tool and additionally needs the\n**NGSIEM** scope (read/write) to run the CQL `match()` query; regular lookup use\ndoes not.\n\n## Common Pitfalls\n\n| Problem | Fix |\n|---------|-----|\n| CSV header missing | The first row MUST be column names — `match()` references them by name |\n| `match()` returns no results | Column names are case-sensitive; verify they match the header exactly |\n| Upload rate limited | Wait 30 seconds between batches of 5 uploads |\n| Wrong search domain | Use `--domain falcon` for files queried in Next-Gen SIEM |\n| Duplicate name overwrites silently | Always `list_lookups.py --search` before `create_lookup.py` |\n| \"File not found\" on get/update/delete | Confirm the exact filename with `list_lookups.py --search` |\n| CSV parse error on upload | Ensure UTF-8 encoding and comma delimiters |\n\n## Reading Guide\n\n| Document | When to read |\n|----------|--------------|\n| `references/cql-match-function.md` | Writing CQL queries that use lookup files |\n| `references/lookup-file-formats.md` | Preparing CSV/JSON/TXT files for upload |\n"
}