Make NG-SIEM detection hydration guidance detection-type-dependent

Detection hydration from an NG-SIEM Signal trigger is not one-size-fits-all. First-party and third-party detections can be pulled with an Event Query matching the composite DetectionID against Ngsiem.alert.id (verified live). Correlation-rule detections cannot: the rule trigger exposes only a composite DetectionID and an opaque ID, neither of which matches the Ngsiem.detection.id value that Advanced event search filters on, and that field is not in the trigger schema. The field that used to bridge it (Ngsiem.original_indicator.id) is gone from the rule-trigger events, so correlation-rule detections must be hydrated with a Get Detection Details action (or an HTTP Request to /alerts/entities/alerts/v2 passing the composite DetectionID as composite_id).

Splits the "enriching a detection you already hold" guidance by detection type in event-query-vs-api.md, adds the same caveat to both trigger-types.md copies and the event-queries use case, and widens the validate.py detection.id-join guard message so it points first-party/third-party detections at Ngsiem.alert.id and correlation-rule detections at Get Detection Details, instead of implying alert.id always works. The guard itself is unchanged (Ngsiem.detection.id = ?arg is never a valid trigger-provided join). 503 tests pass, markdownlint clean.

Author: mraible

skills/authoring/references/event-query-vs-api.md

@@ -63,21 +63,34 @@ the customer's **ingestion connectors** — a tenant with no connectors returns
 audit-log events, not alerts, so an Event Query for "high-severity alerts" can
 silently return zero. The split is about whether you already hold the object:
 
-- **Enriching a detection you already hold** → Event Query. When a workflow is
-  triggered on a detection and has its ID, an Event Query to pull more fields is
-  the right tool (go schemaless, since detection field shapes vary). **Match the
-  detection's composite ID against `Ngsiem.alert.id`, NOT `Ngsiem.detection.id`.**
-  The Signal trigger's `Trigger.Detection.DetectionID` is the *composite* ID
-  (`cid:ngsiem:cid:id`), and in the NG-SIEM event store that value lives in
-  `Ngsiem.alert.id`; `Ngsiem.detection.id` holds a different, short ID, so a query
-  keyed on it silently returns **zero rows** (verified live). So:
-
-  ```
-  # RIGHT — composite DetectionID matches Ngsiem.alert.id
-  Ngsiem.alert.id = ?detectID
-  # WRONG — returns 0 rows for a composite DetectionID
-  Ngsiem.detection.id = ?detectID
-  ```
+- **Enriching a detection you already hold** → depends on the detection type.
+  When a workflow is triggered on a detection and has its ID, how you pull more
+  fields depends on what kind of detection fired:
+  - **First-party and third-party detections** → Event Query. Go schemaless
+    (detection field shapes vary) and **match the detection's composite ID
+    against `Ngsiem.alert.id`, NOT `Ngsiem.detection.id`.** The Signal trigger's
+    `Trigger.Detection.DetectionID` is the *composite* ID (`cid:...:cid:id`), and
+    in the NG-SIEM event store that value lives in `Ngsiem.alert.id`;
+    `Ngsiem.detection.id` holds a different, short ID, so a query keyed on it
+    silently returns **zero rows** (verified live). So:
+
+    ```
+    # RIGHT — composite DetectionID matches Ngsiem.alert.id
+    Ngsiem.alert.id = ?detectID
+    # WRONG — returns 0 rows for a composite DetectionID
+    Ngsiem.detection.id = ?detectID
+    ```
+
+  - **Correlation-rule detections** → **Get Detection Details** action, NOT an
+    Event Query. The rule trigger exposes only the composite `DetectionID` and an
+    opaque `ID`; neither matches the `Ngsiem.detection.id` value that Advanced
+    event search filters on, and that field is not in the trigger schema. The
+    field that used to bridge it (`Ngsiem.original_indicator.id`) is gone from the
+    rule-trigger events, so a correlation-rule detection cannot be hydrated via
+    Event Query today. Add a **Get Detection Details** gather step (or a
+    CrowdStrike HTTP Request to `/alerts/entities/alerts/v2` passing the composite
+    `DetectionID` as `composite_id`) to fetch the full detection, then read fields
+    from its response.
 
   **Treat detection IDs as opaque.** Per the detections team, `composite_id` (what
   the trigger hands you) is the primary key used to retrieve a detection, but its
@@ -86,7 +99,7 @@ silently return zero. The split is about whether you already hold the object:
   NG-SIEM → Advanced event search or via the NG-SIEM search API before assuming the
   detection has no data. **If the detection type carries indicators directly in the
   trigger payload (e.g. EPP: `Trigger.Detection.EPP.Process.SHA256`), prefer reading
-  them straight from the payload over a hydration query — no join, no empty-result
+  them straight from the payload over any hydration step — no join, no empty-result
   risk.** Discover payload fields with `trigger_search.py --fields <category>`.
 - **Fetching the alert/detection *population* you don't have** — "summarize all
   high-severity alerts", "list open detections across products" → the Falcon

skills/authoring/references/trigger-types.md

@@ -214,6 +214,14 @@ list), hydrate with an Event Query and read from its `results` array:
 through an inline Python extractor** (`cs.json.decode(data['<Python>.output_stdout'])`)
 — that form does not resolve at release. Read `results[0].<Field>` directly.
 
+**Event Query hydration only works for first-party and third-party detections**
+(match the composite `DetectionID` against `Ngsiem.alert.id`, not
+`Ngsiem.detection.id`). **Correlation-rule detections cannot be hydrated by an
+Event Query** — their `Ngsiem.detection.id` is not exposed on the trigger and no
+Event Query field matches it. For those, add a **Get Detection Details** action
+(or an HTTP Request to `/alerts/entities/alerts/v2` passing the composite
+`DetectionID` as `composite_id`). See `references/event-query-vs-api.md`.
+
 **Not every `Trigger.Detection.*` field resolves on the NG-SIEM trigger.**
 `${Trigger.Detection.Product}` and `${Trigger.Detection.Description}` are available
 on the **base `event: Investigatable`** trigger (the multi-product Detection trigger

skills/authoring/scripts/validate.py

@@ -419,12 +419,16 @@ def _check_detection_hydration_join(label, config, issues):
     if isinstance(query, str) and _DETECTION_ID_JOIN_RE.search(query):
         issues.append(
             f"ERROR: Event Query action '{label}' hydrates a detection by "
-            f"matching 'Ngsiem.detection.id = ?...'. The trigger's composite "
-            f"DetectionID is stored in 'Ngsiem.alert.id', NOT "
-            f"'Ngsiem.detection.id' (a different, short ID the trigger never "
-            f"provides) — this query returns zero rows at runtime and the "
-            f"workflow enriches nothing, despite releasing cleanly. Change the "
-            f"join field to 'Ngsiem.alert.id'. See references/event-query-vs-api.md."
+            f"matching 'Ngsiem.detection.id = ?...'. The trigger never provides "
+            f"that field. For first-party and third-party detections, the "
+            f"trigger's composite DetectionID is stored in 'Ngsiem.alert.id' — "
+            f"change the join field to 'Ngsiem.alert.id'. For correlation-rule "
+            f"detections, neither Event Query field matches; use a 'Get Detection "
+            f"Details' action (or an HTTP Request to /alerts/entities/alerts/v2 "
+            f"passing the composite DetectionID as composite_id) instead. As "
+            f"written this query returns zero rows at runtime and the workflow "
+            f"enriches nothing, despite releasing cleanly. See "
+            f"references/event-query-vs-api.md."
         )
 
 

skills/workflows/references/trigger-types.md

@@ -123,6 +123,15 @@ rejected at release as "unknown variable" for EPP triggers. Enrich indicators
 straight from the trigger payload (e.g. send `Process.SHA256` to VirusTotal);
 you do not need an Event Query to hydrate the detection.
 
+**If you must hydrate a detection** (indicators not on the trigger), the path
+depends on detection type. First-party/third-party detections can be pulled with
+an Event Query matching the composite `DetectionID` against `Ngsiem.alert.id` (not
+`Ngsiem.detection.id`). **Correlation-rule detections cannot be hydrated by an
+Event Query** — their `Ngsiem.detection.id` is not exposed on the trigger; use a
+**Get Detection Details** action (or an HTTP Request to
+`/alerts/entities/alerts/v2` passing the composite `DetectionID` as `composite_id`)
+instead. See `../../authoring/references/event-query-vs-api.md`.
+
 **Severity is an integer (1-5) at `Trigger.Detection.Severity`, not a string.** Use numeric comparison in CEL conditions:
 
 | Value | Display Name |

use-cases/event-queries.md

@@ -10,8 +10,10 @@ capabilities: [workflow, event-query]
 
 User wants a workflow to query the NG-SIEM event store — ingested logs, custom telemetry,
 LogScale search results, or enriching a detection the workflow already holds (e.g.
-`Ngsiem.alert.id = ?detectID` — the trigger's composite `DetectionID` is stored as
-`Ngsiem.alert.id`, not `Ngsiem.detection.id`) — without defining a schema up front. The Event Query action
+`Ngsiem.alert.id = ?detectID` — for first-party/third-party detections the trigger's composite
+`DetectionID` is stored as `Ngsiem.alert.id`, not `Ngsiem.detection.id`; correlation-rule
+detections can't be hydrated this way, use a Get Detection Details action) — without defining a
+schema up front. The Event Query action
 runs a CQL/FQL query inline and
 returns matching events, which subsequent actions process and branch on. This is the
 "schemaless" path: you query whatever the event store holds and shape the results downstream,
@@ -104,7 +106,9 @@ code-driven querying belongs in a function.
 > **Mention** the alternative when the workflow must be shared: a **Foundry app + FalconPy
 > `Alerts`/`Detects` function** (route to **foundry-skills**) — distributable/certifiable, prompts
 > for creds on install. This does NOT apply to *enriching a detection
-> you already hold* — when the workflow was triggered on a detection and has its ID, an Event Query
-> like `Ngsiem.alert.id = ?detectID` to pull more fields is the right tool (match the composite
-> `DetectionID` against `Ngsiem.alert.id`, not `Ngsiem.detection.id`). See
-> [event-query-vs-api.md](../skills/authoring/references/event-query-vs-api.md).
+> you already hold* — when the workflow was triggered on a **first-party or third-party** detection
+> and has its ID, an Event Query like `Ngsiem.alert.id = ?detectID` to pull more fields is the right
+> tool (match the composite `DetectionID` against `Ngsiem.alert.id`, not `Ngsiem.detection.id`).
+> **Correlation-rule detections are the exception:** their `Ngsiem.detection.id` is not in the
+> trigger and can't be reached by an Event Query — use a **Get Detection Details** action instead.
+> See [event-query-vs-api.md](../skills/authoring/references/event-query-vs-api.md).