From cc533e95fc2fbf80172a37237074da3252008ab3 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Wed, 20 May 2026 16:40:15 -0400 Subject: [PATCH 1/3] first draft --- .../fields-and-object-schemas/alert-schema.md | 4 +- .../cross-project-search-detection-rules.md | 47 +++++++++++++++++++ 2 files changed, 50 insertions(+), 1 deletion(-) diff --git a/reference/security/fields-and-object-schemas/alert-schema.md b/reference/security/fields-and-object-schemas/alert-schema.md index d6aadf6e49..1e491fcd5a 100644 --- a/reference/security/fields-and-object-schemas/alert-schema.md +++ b/reference/security/fields-and-object-schemas/alert-schema.md @@ -129,7 +129,9 @@ The non-ECS fields listed below are beta and subject to change. | `kibana.alert.rule.parameters.threat_mapping.*` | Controls which fields will be compared in the indicator and source documents.
Type: flattened | | `kibana.alert.rule.parameters.threat_query` | Type: flattened | | `kibana.alert.rule.parameters.threshold.*` | Type: flattened | -| `kibana.space_ids` | Type: keyword | +| `kibana.space_ids` | Space ID(s) of the {{kib}} space where the rule that created this alert runs.
Type: keyword | +| `kibana.cps_scope.expression` {applies_to}`serverless: preview` {applies_to}`stack: unavailable` | The [{{cps}}](/explore-analyze/cross-project-search.md) scope that was in effect when the detection rule generated this alert. Present only when the rule ran with {{cps}} enabled.
Type: keyword | +| `kibana.cps_scope.linked_projects` {applies_to}`serverless: preview` {applies_to}`stack: unavailable` | The linked projects that were in scope when this alert was generated. Each entry includes `id`, `alias`, `type`, and `organization`. Present only when the rule ran with {{cps}} enabled.
Type: flattened | | `kibana.alert.rule.consumer` | Type: keyword | | `kibana.alert.status` | Type: keyword | | `kibana.alert.rule.category` | Type: keyword | diff --git a/solutions/security/detect-and-alert/cross-project-search-detection-rules.md b/solutions/security/detect-and-alert/cross-project-search-detection-rules.md index 014e768383..d3c1a9b6ed 100644 --- a/solutions/security/detect-and-alert/cross-project-search-detection-rules.md +++ b/solutions/security/detect-and-alert/cross-project-search-detection-rules.md @@ -10,4 +10,51 @@ description: Learn how detection rules work with cross-project search to query d # {{cps-cap}} and detection rules [sec-rules-cross-project-search] :::{include} /solutions/_snippets/cps-sec-obs-rules.md +::: + +## {{cps-cap}} context in alerts and the event log [cps-context-in-alerts] + +When a detection rule runs with {{cps}} enabled, the scope in effect at execution time is recorded on generated alerts and in rule execution events. Use these fields during investigations to confirm which linked projects were in scope when an alert was created. + +### Alert documents + +Each alert document created by a {{cps}}-scoped rule execution can include: + +| Field | Description | +| --- | --- | +| `kibana.cps_scope.expression` | The resolved NPRE for the space-level {{cps}} scope. | +| `kibana.cps_scope.linked_projects` | The linked projects included in that scope, with `id`, `alias`, `type`, and `organization` for each project. | + +These fields are omitted when the rule does not run with {{cps}} enabled. For the full list of alert fields, refer to the [alert schema](/reference/security/fields-and-object-schemas/alert-schema.md). + +### Event log + +Rule execution events written to the [event log index](/explore-analyze/alerting/alerts/event-log-index.md) include the same {{cps}} context under the `kibana` object: + +| Field | Description | +| --- | --- | +| `kibana.cps_scope_expression` | The resolved NPRE for the {{cps}} scope. | +| `kibana.cps_scope_linked_projects` | The linked projects in scope, with the same object structure as in alert documents. | + +To find executions for a specific scope, query the event log. For example: + +```txt +GET .kibana-event-log-*/_search +{ + "size": 5, + "query": { + "match": { "kibana.cps_scope_expression": "_alias:*" } + }, + "_source": [ + "event.action", + "message", + "kibana.cps_scope_expression", + "kibana.cps_scope_linked_projects", + "kibana.space_ids" + ] +} +``` + +:::{note} +For cross-cluster deployments, use [{{ccs-cap}} and detection rules](/solutions/security/detect-and-alert/cross-cluster-search-detection-rules.md) instead. {{cps}} is available for {{serverless-short}} projects only. ::: \ No newline at end of file From 53d5c480c875511c9c8e3ddbebc492c4c6c75c50 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Wed, 20 May 2026 21:25:08 -0400 Subject: [PATCH 2/3] more additions --- .../cross-project-search-detection-rules.md | 41 +++++++++++++------ 1 file changed, 29 insertions(+), 12 deletions(-) diff --git a/solutions/security/detect-and-alert/cross-project-search-detection-rules.md b/solutions/security/detect-and-alert/cross-project-search-detection-rules.md index d3c1a9b6ed..b82846725c 100644 --- a/solutions/security/detect-and-alert/cross-project-search-detection-rules.md +++ b/solutions/security/detect-and-alert/cross-project-search-detection-rules.md @@ -12,31 +12,41 @@ description: Learn how detection rules work with cross-project search to query d :::{include} /solutions/_snippets/cps-sec-obs-rules.md ::: +If your data spans {{stack}} clusters rather than linked {{serverless-short}} projects, refer to [{{ccs-cap}} and detection rules](/solutions/security/detect-and-alert/cross-cluster-search-detection-rules.md) instead. + ## {{cps-cap}} context in alerts and the event log [cps-context-in-alerts] -When a detection rule runs with {{cps}} enabled, the scope in effect at execution time is recorded on generated alerts and in rule execution events. Use these fields during investigations to confirm which linked projects were in scope when an alert was created. +When a detection rule runs with {{cps}} enabled, the scope in effect at execution time is recorded on generated alerts and in rule execution events. During investigations, use the scope and linked project fields on the alert or in the event log to confirm which linked projects were in scope when an alert was created. + +### When scope fields appear [cps-scope-fields-when] + +Scope fields are written at rule execution time, not added to existing documents later. You need linked projects, a configured space-level {{cps}} scope, and at least one enabled detection rule that has run successfully with {{cps}} enabled. + +On **alert documents**, `kibana.cps_scope.expression` and `kibana.cps_scope.linked_projects` are present only when that run generated an alert. Alerts from runs before {{cps}} was enabled are not updated retroactively. + +On **event log entries**, `kibana.cps_scope_expression` and `kibana.cps_scope_linked_projects` are recorded for every {{cps}}-scoped execution, including runs that created no alerts. ### Alert documents -Each alert document created by a {{cps}}-scoped rule execution can include: +When a detection rule runs with {{cps}} enabled, each generated alert can include: | Field | Description | | --- | --- | -| `kibana.cps_scope.expression` | The resolved NPRE for the space-level {{cps}} scope. | -| `kibana.cps_scope.linked_projects` | The linked projects included in that scope, with `id`, `alias`, `type`, and `organization` for each project. | +| `kibana.cps_scope.expression` | The {{cps}} scope that was in effect when the rule generated the alert. | +| `kibana.cps_scope.linked_projects` | The linked projects that were in scope. Each entry includes `id`, `alias`, `type`, and `organization`. | -These fields are omitted when the rule does not run with {{cps}} enabled. For the full list of alert fields, refer to the [alert schema](/reference/security/fields-and-object-schemas/alert-schema.md). +For the full list of alert fields, refer to the [alert schema](/reference/security/fields-and-object-schemas/alert-schema.md). ### Event log -Rule execution events written to the [event log index](/explore-analyze/alerting/alerts/event-log-index.md) include the same {{cps}} context under the `kibana` object: +Rule execution events in the [event log index](/explore-analyze/alerting/alerts/event-log-index.md) record the same scope and linked project information: | Field | Description | | --- | --- | -| `kibana.cps_scope_expression` | The resolved NPRE for the {{cps}} scope. | -| `kibana.cps_scope_linked_projects` | The linked projects in scope, with the same object structure as in alert documents. | +| `kibana.cps_scope_expression` | The {{cps}} scope that was in effect during the rule execution. | +| `kibana.cps_scope_linked_projects` | The linked projects that were in scope. Each entry includes `id`, `alias`, `type`, and `organization`. | -To find executions for a specific scope, query the event log. For example: +To find rule executions that ran with a particular scope, run a search against the event log in [{{dev-tools-app}}](/explore-analyze/query-filter/tools/console.md) or your own API client. The following example returns recent detection rule execution events that include {{cps}} scope fields: ```txt GET .kibana-event-log-*/_search @@ -55,6 +65,13 @@ GET .kibana-event-log-*/_search } ``` -:::{note} -For cross-cluster deployments, use [{{ccs-cap}} and detection rules](/solutions/security/detect-and-alert/cross-cluster-search-detection-rules.md) instead. {{cps}} is available for {{serverless-short}} projects only. -::: \ No newline at end of file +This request searches the event log indices (`.kibana-event-log-*`) for documents that have a `kibana.cps_scope_expression` value. It limits the response to five events and returns only the fields listed in `_source`, including the {{cps}} scope, linked projects, and space ID for each execution. The event log is a system index, so by default only users with a `superuser` role can run this search. For more example queries and details on required privileges, refer to the [event log index](/explore-analyze/alerting/alerts/event-log-index.md). + + +:::{admonition} Before you run the example +To run this request in {{dev-tools-app}} or your own API client, update the example first: + +1. In the `match` query, replace the value for `kibana.cps_scope_expression`. The example uses `_alias:*`; change this to the scope you want to find. To match the scope from a specific alert, copy the value from that alert's `kibana.cps_scope.expression` field. +2. Change `size` to return more or fewer events. +3. Edit the `_source` array to include the fields you need in the response. +::: From 2fdbfcb5ac8859f3796937947ccf6e77880ca746 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Tue, 26 May 2026 20:33:58 -0400 Subject: [PATCH 3/3] editorial and technical feedback --- .../cross-project-search-detection-rules.md | 25 ++++++++----------- 1 file changed, 10 insertions(+), 15 deletions(-) diff --git a/solutions/security/detect-and-alert/cross-project-search-detection-rules.md b/solutions/security/detect-and-alert/cross-project-search-detection-rules.md index b82846725c..d19a0dfc0d 100644 --- a/solutions/security/detect-and-alert/cross-project-search-detection-rules.md +++ b/solutions/security/detect-and-alert/cross-project-search-detection-rules.md @@ -12,7 +12,7 @@ description: Learn how detection rules work with cross-project search to query d :::{include} /solutions/_snippets/cps-sec-obs-rules.md ::: -If your data spans {{stack}} clusters rather than linked {{serverless-short}} projects, refer to [{{ccs-cap}} and detection rules](/solutions/security/detect-and-alert/cross-cluster-search-detection-rules.md) instead. +If your data spans ECH, ECE, ECK, or self-managed clusters rather than linked {{serverless-short}} projects, refer to [{{ccs-cap}} and detection rules](/solutions/security/detect-and-alert/cross-cluster-search-detection-rules.md) instead. ## {{cps-cap}} context in alerts and the event log [cps-context-in-alerts] @@ -20,9 +20,9 @@ When a detection rule runs with {{cps}} enabled, the scope in effect at executio ### When scope fields appear [cps-scope-fields-when] -Scope fields are written at rule execution time, not added to existing documents later. You need linked projects, a configured space-level {{cps}} scope, and at least one enabled detection rule that has run successfully with {{cps}} enabled. +Scope fields are written at rule execution time, not added to existing documents later. You need [linked projects](/deploy-manage/cross-project-search-config/cps-config-link-and-manage.md), a [configured space-level {{cps}} scope](/deploy-manage/cross-project-search-config/cps-config-access-and-scope.md), and at least one enabled detection rule that has run successfully with {{cps}} enabled. -On **alert documents**, `kibana.cps_scope.expression` and `kibana.cps_scope.linked_projects` are present only when that run generated an alert. Alerts from runs before {{cps}} was enabled are not updated retroactively. +On **alert documents**, `kibana.cps_scope.expression` and `kibana.cps_scope.linked_projects` are present only when that run generated an alert. Alerts created before {{cps}} was enabled are not updated retroactively. On **event log entries**, `kibana.cps_scope_expression` and `kibana.cps_scope_linked_projects` are recorded for every {{cps}}-scoped execution, including runs that created no alerts. @@ -51,11 +51,11 @@ To find rule executions that ran with a particular scope, run a search against t ```txt GET .kibana-event-log-*/_search { - "size": 5, + "size": 5, <1> "query": { - "match": { "kibana.cps_scope_expression": "_alias:*" } + "match": { "kibana.cps_scope_expression": "_alias:*" } <2> }, - "_source": [ + "_source": [ <3> "event.action", "message", "kibana.cps_scope_expression", @@ -65,13 +65,8 @@ GET .kibana-event-log-*/_search } ``` -This request searches the event log indices (`.kibana-event-log-*`) for documents that have a `kibana.cps_scope_expression` value. It limits the response to five events and returns only the fields listed in `_source`, including the {{cps}} scope, linked projects, and space ID for each execution. The event log is a system index, so by default only users with a `superuser` role can run this search. For more example queries and details on required privileges, refer to the [event log index](/explore-analyze/alerting/alerts/event-log-index.md). - - -:::{admonition} Before you run the example -To run this request in {{dev-tools-app}} or your own API client, update the example first: - -1. In the `match` query, replace the value for `kibana.cps_scope_expression`. The example uses `_alias:*`; change this to the scope you want to find. To match the scope from a specific alert, copy the value from that alert's `kibana.cps_scope.expression` field. -2. Change `size` to return more or fewer events. +1. Change `size` to return more or fewer events. +2. Replace `_alias:*` with the scope you want to find. To match the scope from a specific alert, copy the value from that alert's `kibana.cps_scope.expression` field. 3. Edit the `_source` array to include the fields you need in the response. -::: + +This request searches the event log indices (`.kibana-event-log-*`) for documents that have a `kibana.cps_scope_expression` value. It limits the response to five events and returns only the fields listed in `_source`, including the {{cps}} scope, linked projects, and space ID for each execution. The event log is a system index, so by default only users with a `superuser` role can run this search. For more example queries and details on required privileges, refer to the [event log index](/explore-analyze/alerting/alerts/event-log-index.md).