From 601514e00c6d5c095331271078f4b10f88ac1841 Mon Sep 17 00:00:00 2001 From: etienneddog <115489978+etienneddog@users.noreply.github.com> Date: Tue, 30 Dec 2025 17:45:50 +0100 Subject: [PATCH 1/4] Revise security findings migration documentation Updated the security findings migration guide to clarify the changes in query syntax and required actions for users. Added details about the new querying syntax and the timeline for deprecating legacy API endpoints. --- .../guide/security-findings-migration.md | 43 +++++++++---------- 1 file changed, 21 insertions(+), 22 deletions(-) diff --git a/content/en/security/guide/security-findings-migration.md b/content/en/security/guide/security-findings-migration.md index c6100b1b442..47a2168c959 100644 --- a/content/en/security/guide/security-findings-migration.md +++ b/content/en/security/guide/security-findings-migration.md @@ -16,7 +16,7 @@ further_reading: ## Overview -To make it easier to search for security findings throughout Datadog, the syntax for search queries is changing: +To make it easier to search for security findings throughout Datadog, the syntax for search queries is changing starting January 28th: - **Standardized naming conventions** for security finding data fields - **A new schema** to consistently organize those fields across security products @@ -28,22 +28,32 @@ This change comes with a set of [new features](#new-features) that use the new s ### Required action -This change affects all interfaces where you can query security findings data. While some queries will receive automatic updates, others require updates on your part: -- **No change required** - queries are updated automatically - - Explorers, dashboards, notification rules, and automation pipelines -- **Changes required** - update your queries by **April 1, 2026** - - Workflow Automation and Sheets - - API endpoints: [List findings][15] and [Get a finding][16] - - Terraform resource: `datadog_security_notification_rule` -
Datadog will deprecate legacy API and Terraform resources. Update your queries on time so you can avoid workflow interruptions.
+- If you do not use public APIs or the security findings notification rules terraform resource, **no changes are required** - queries are updated automatically in the UI: + - Explorers, dashboards, notification rules, automation pipelines and workflows + +- If you do use one of the features listed below, **changes will be required** - please prepare to update before the second half of 2026: + - API endpoints: [List findings][15] and [Get a finding][16] will eventually be deprecated in favor of a new unified Findings API (docs to be shared early January). + - Terraform resource `datadog_security_notification_rule` for triggery_type: "security_findings": Starting January 28th, you can update the `query` value to match the new syntax. If you need assistance with your migration, contact [Datadog support][14]. ## What is changing +### New querying syntax + +Following this change, you can use the same query syntax for all security findings, using attributes organized around namespaces. Here are some practical examples: + +| Before | After (all findings) | +|--------|----------------------| +| **Misconfigurations:** `@workflow.triage.status:open status:critical`
**Library vulnerabilities:** `status:open severity:Critical` | `@status:open @severity:critical` | +| **Misconfigurations:** `@dd_computed_attributes.is_publicly_accessible:true`
**Host Vulnerabilities:** `is_publicly_accessible:Accessible` | `@risk.is_publicly_accessible:true` | +| **Library Vulnerabilities:** `library_name:org.apache.logging.log4j`
**Host Vulnerabilities:** `package:org.apache.logging.log4j` | `@package.name:org.apache.logging.log4j` | + +View the full specification at [Security Findings Schema Reference][1]. + ### New features -Starting late January 2026, the following features use the new data model: +Starting late January 2026, the following features will be made available and use the new data model: - Unified search queries for Cloud Security [Misconfigurations][9], [Identity Risks][10], [Attack Paths][11], [IaC][12], and [API][13] findings - A new unified public findings API - [Dashboard][2] support for Code Security @@ -114,17 +124,6 @@ Security findings encompass misconfigurations, vulnerabilities, and security ris -### New querying syntax - -Following this change, you can use the same query syntax for all security findings, using attributes organized around namespaces. Here are some practical examples: - -| Before | After (all findings) | -|--------|----------------------| -| **Misconfigurations:** `@workflow.triage.status:open status:critical`
**Library vulnerabilities:** `status:open severity:Critical` | `@status:open @severity:critical` | -| **Misconfigurations:** `@dd_computed_attributes.is_publicly_accessible:true`
**Host Vulnerabilities:** `is_publicly_accessible:Accessible` | `@risk.is_publicly_accessible:true` | -| **Library Vulnerabilities:** `library_name:org.apache.logging.log4j`
**Host Vulnerabilities:** `package:org.apache.logging.log4j` | `@package.name:org.apache.logging.log4j` | - -View the full specification at [Security Findings Schema Reference][1]. ## Further reading @@ -145,4 +144,4 @@ View the full specification at [Security Findings Schema Reference][1]. [13]: /security/application_security/api-inventory/#api-findings [14]: /help [15]: /api/latest/security-monitoring/#list-findings -[16]: /api/latest/security-monitoring/#get-a-finding \ No newline at end of file +[16]: /api/latest/security-monitoring/#get-a-finding From 0c0a2e4398e0ff3b5e53a1e1292b4fe12e51c15a Mon Sep 17 00:00:00 2001 From: Janine Chan <64388808+janine-c@users.noreply.github.com> Date: Tue, 30 Dec 2025 10:41:28 -0700 Subject: [PATCH 2/4] Minor structure/readability updates --- .../guide/security-findings-migration.md | 23 ++++++++++++------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/content/en/security/guide/security-findings-migration.md b/content/en/security/guide/security-findings-migration.md index 47a2168c959..2417ee85006 100644 --- a/content/en/security/guide/security-findings-migration.md +++ b/content/en/security/guide/security-findings-migration.md @@ -16,24 +16,30 @@ further_reading: ## Overview -To make it easier to search for security findings throughout Datadog, the syntax for search queries is changing starting January 28th: +To make it easier to search for security findings throughout Datadog, the syntax for search queries is changing: - **Standardized naming conventions** for security finding data fields - **A new schema** to consistently organize those fields across security products This change comes with a set of [new features](#new-features) that use the new schema, and may also impact your existing workflows. This page details what is changing, the workflows that Datadog automatically updates, and the changes you need to make to avoid interruptions in your existing workflows. +
Datadog will start rolling out changes January 28, 2026. You should plan to update any affected workflows in the first half of 2026 to avoid any interruptions as Datadog deprecates the old syntax. +
+ {{< learning-center-callout header="" btn_title="View the schema" btn_url="/security/guide/findings-schema/" hide_image="true" >}} View the new security findings schema so you can understand how finding details will be stored. {{< /learning-center-callout >}} ### Required action -- If you do not use public APIs or the security findings notification rules terraform resource, **no changes are required** - queries are updated automatically in the UI: - - Explorers, dashboards, notification rules, automation pipelines and workflows - -- If you do use one of the features listed below, **changes will be required** - please prepare to update before the second half of 2026: - - API endpoints: [List findings][15] and [Get a finding][16] will eventually be deprecated in favor of a new unified Findings API (docs to be shared early January). - - Terraform resource `datadog_security_notification_rule` for triggery_type: "security_findings": Starting January 28th, you can update the `query` value to match the new syntax. +- If you use certain API endpoints or Terraform resources, **changes will be required**: + - The [List findings][15] and [Get a finding][16] API endpoints will use a new unified Findings API. + - For the [`datadog_security_notification_rule`][17] Terraform resources with `trigger_source: "security_findings"`, the `query` value will use the new search syntax. +- If you do not use public APIs or the security findings notification rules terraform resource, **no changes are required**. The following queries are updated automatically in the UI: + - Explorers + - Dashboards + - Notification rules + - Automation pipelines + - Workflows If you need assistance with your migration, contact [Datadog support][14]. @@ -53,7 +59,7 @@ View the full specification at [Security Findings Schema Reference][1]. ### New features -Starting late January 2026, the following features will be made available and use the new data model: +Starting January 28, 2026, the following features will be made available and use the new data model: - Unified search queries for Cloud Security [Misconfigurations][9], [Identity Risks][10], [Attack Paths][11], [IaC][12], and [API][13] findings - A new unified public findings API - [Dashboard][2] support for Code Security @@ -145,3 +151,4 @@ Security findings encompass misconfigurations, vulnerabilities, and security ris [14]: /help [15]: /api/latest/security-monitoring/#list-findings [16]: /api/latest/security-monitoring/#get-a-finding +[17]: https://registry.terraform.io/providers/DataDog/datadog/latest/docs/resources/security_notification_rule \ No newline at end of file From dafb8e80df3e6693618a2869baea221598d3bbee Mon Sep 17 00:00:00 2001 From: Janine Chan <64388808+janine-c@users.noreply.github.com> Date: Tue, 30 Dec 2025 10:54:16 -0700 Subject: [PATCH 3/4] Apply Etienne's feedback --- content/en/security/guide/security-findings-migration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/security/guide/security-findings-migration.md b/content/en/security/guide/security-findings-migration.md index 2417ee85006..7a3d51b3d85 100644 --- a/content/en/security/guide/security-findings-migration.md +++ b/content/en/security/guide/security-findings-migration.md @@ -32,8 +32,8 @@ This change comes with a set of [new features](#new-features) that use the new s ### Required action - If you use certain API endpoints or Terraform resources, **changes will be required**: - - The [List findings][15] and [Get a finding][16] API endpoints will use a new unified Findings API. - - For the [`datadog_security_notification_rule`][17] Terraform resources with `trigger_source: "security_findings"`, the `query` value will use the new search syntax. + - For [List findings][15] and [Get a finding][16] API endpoints, update your API calls to use the new unified Findings API. The documentation for this API will be published in early January 2026. + - For [`datadog_security_notification_rule`][17] Terraform resources with `trigger_source: "security_findings"`, update `query` values to use the new search syntax. - If you do not use public APIs or the security findings notification rules terraform resource, **no changes are required**. The following queries are updated automatically in the UI: - Explorers - Dashboards From c7f6f569d4a275cb6ad2e457851ad0a4c25501db Mon Sep 17 00:00:00 2001 From: Janine Chan <64388808+janine-c@users.noreply.github.com> Date: Tue, 30 Dec 2025 11:02:20 -0700 Subject: [PATCH 4/4] Add release date for Terraform query syntax --- content/en/security/guide/security-findings-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/security/guide/security-findings-migration.md b/content/en/security/guide/security-findings-migration.md index 7a3d51b3d85..53266973552 100644 --- a/content/en/security/guide/security-findings-migration.md +++ b/content/en/security/guide/security-findings-migration.md @@ -33,7 +33,7 @@ This change comes with a set of [new features](#new-features) that use the new s - If you use certain API endpoints or Terraform resources, **changes will be required**: - For [List findings][15] and [Get a finding][16] API endpoints, update your API calls to use the new unified Findings API. The documentation for this API will be published in early January 2026. - - For [`datadog_security_notification_rule`][17] Terraform resources with `trigger_source: "security_findings"`, update `query` values to use the new search syntax. + - For [`datadog_security_notification_rule`][17] Terraform resources with `trigger_source: "security_findings"`, update `query` values to use the new search syntax, starting January 28, 2026. - If you do not use public APIs or the security findings notification rules terraform resource, **no changes are required**. The following queries are updated automatically in the UI: - Explorers - Dashboards