Add Migrating to the New Security Findings Data Model Guide
#33083
+117
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
github-actions
bot
added
Images
Contributor
Preview links (active after the
|
danieldebeer-dd
changed the title
Migrating to the New Security Findings Data Model Guide
janine-c
reviewed
Nov 29, 2025
Contributor
janine-c
left a comment
janine-c
left a comment
There was a problem hiding this comment.
Hey Daniel, thank you for putting together this PR and being willing to be the point of contact on your team! I made some general content suggestions, but know that this is going to be subject to change as the plan firms up. Let me know how I can help as it does! For now, I'll apply the WIP label on this while we wait for links and dates to go in the placeholders.
| @@ -0,0 +1,117 @@ | |||
| --- | |||
| title: Migrating to the New Security Findings Data Model | |||
Contributor
There was a problem hiding this comment.
Suggested change
| title: Migrating to the New Security Findings Data Model | |
| title: Migrate to the New Security Findings Data Model |
Small style thing! We tend to go for imperative verbs instead of gerunds 🤓 Just for brevity and a little extra directness.
|
|
||
| ## Overview | ||
|
|
||
| The way Security Findings are queried is changing and it may impact your workflows. You notice changes to how queries are constructed in Datadog. A set of [new features](#new-features) exposing that new schema is also released as a part of the upgrade. |
Contributor
There was a problem hiding this comment.
Suggested change
| The way Security Findings are queried is changing and it may impact your workflows. You notice changes to how queries are constructed in Datadog. A set of [new features](#new-features) exposing that new schema is also released as a part of the upgrade. | |
| The syntax for creating queries to search for Security Findings in Datadog is changing. While this change comes with a set of [new features](#new-features) exposing that new schema, it may also impact your existing workflows. | |
| This change affects all interfaces where you can query security findings data: | |
| - Explorers, dashboards, notification rules, and automation pipelines | |
| - Workflow Automation | |
| - API and Terraform resources |
|
|
||
| ## Required action | ||
|
|
||
| If you are using {insert relevant APIs / Terraform resource}, plan to migrate to the new version by {deprecation date}. |
Contributor
There was a problem hiding this comment.
Suggested change
| If you are using {insert relevant APIs / Terraform resource}, plan to migrate to the new version by {deprecation date}. | |
| If you are using {insert relevant APIs / Terraform resource}, plan to migrate to the new version by {deprecation date} so you can avoid interruptions in your existing workflows. |
|
|
||
| If you are using {insert relevant APIs / Terraform resource}, plan to migrate to the new version by {deprecation date}. | ||
|
|
||
| Configuration in Datadog is updated automatically, so no action is needed there. |
Contributor
There was a problem hiding this comment.
Can we provide some detail on what "configuration in Datadog" means? How could a user determine what they need to change and what they can leave to us?
Comment on lines
+27
to
+29
| ## What are Security Findings | ||
|
|
||
| Security Findings encompass vulnerabilities, misconfigurations, and security risks identified across your infrastructure and applications. |
Contributor
There was a problem hiding this comment.
Suggested change
| ## What are Security Findings | |
| Security Findings encompass vulnerabilities, misconfigurations, and security risks identified across your infrastructure and applications. | |
| ## Security findings | |
| Security findings encompass vulnerabilities, misconfigurations, and security risks identified across your infrastructure and applications. |
|
|
||
| - A new unified findings public API | ||
| - Dashboard support for Code Security | ||
| - Graphing Security Findings in Datadog Sheets |
Contributor
There was a problem hiding this comment.
Suggested change
| - Graphing Security Findings in Datadog Sheets | |
| - Graphing security findings in Datadog Sheets |
| - Dashboard support for Code Security | ||
| - Graphing Security Findings in Datadog Sheets | ||
| - Datadog Workflow Automation support for all finding types | ||
| - Using SQL to query Security Findings and join them with other Datadog Telemetry via DDSQL |
Contributor
There was a problem hiding this comment.
Suggested change
| - Using SQL to query Security Findings and join them with other Datadog Telemetry via DDSQL | |
| - Using SQL to query security findings and join them with other Datadog telemetry using DDSQL |
Comment on lines
+110
to
+113
| ## How to prepare | ||
|
|
||
| - Every in-app feature will be automatically migrated. | ||
| - Legacy API endpoints and Terraform resources will eventually be deprecated. |
Contributor
There was a problem hiding this comment.
The heading and the content here don't really seem to match, because the heading would make me expect instructions about how to prepare, but then the bullets aren't action items. Can we rename the section or work the bullet points into the rest of the content on the page?
Comment on lines
+54
to
+58
| | Before | After | | ||
| |--------|-------| | ||
| | **Misconfigurations:** `@workflow.triage.status:open status:critical`<br>**Library vulnerabilities:** `status:open severity:Critical` | **All findings:** `@status:open @severity:critical` | | ||
| | **Misconfigurations:** `@dd_computed_attributes.is_publicly_accessible:true`<br>**Host Vulnerabilities:** `is_publicly_accessible:Accessible` | **All findings:** `@risk.is_publicly_accessible:true` | | ||
| | **Library Vulnerabilities:** `library_name:org.apache.logging.log4j`<br>**Host Vulnerabilities:** `package:org.apache.logging.log4j` | **All findings:** `@package.name:org.apache.logging.log4j` | |
Contributor
There was a problem hiding this comment.
Suggested change
| | Before | After | | |
| |--------|-------| | |
| | **Misconfigurations:** `@workflow.triage.status:open status:critical`<br>**Library vulnerabilities:** `status:open severity:Critical` | **All findings:** `@status:open @severity:critical` | | |
| | **Misconfigurations:** `@dd_computed_attributes.is_publicly_accessible:true`<br>**Host Vulnerabilities:** `is_publicly_accessible:Accessible` | **All findings:** `@risk.is_publicly_accessible:true` | | |
| | **Library Vulnerabilities:** `library_name:org.apache.logging.log4j`<br>**Host Vulnerabilities:** `package:org.apache.logging.log4j` | **All findings:** `@package.name:org.apache.logging.log4j` | | |
| | Before | After (all findings) | | |
| |--------|----------------------| | |
| | **Misconfigurations:** `@workflow.triage.status:open status:critical`<br>**Library vulnerabilities:** `status:open severity:Critical` | `@status:open @severity:critical` | | |
| | **Misconfigurations:** `@dd_computed_attributes.is_publicly_accessible:true`<br>**Host Vulnerabilities:** `is_publicly_accessible:Accessible` | `@risk.is_publicly_accessible:true` | | |
| | **Library Vulnerabilities:** `library_name:org.apache.logging.log4j`<br>**Host Vulnerabilities:** `package:org.apache.logging.log4j` | `@package.name:org.apache.logging.log4j` | |
Thought we could put "all findings" into the column header so we didn't have to repeat it 🙂
Comment on lines
+90
to
+108
| ### Milestone 1: January 2026 | ||
|
|
||
| **Migrated Findings** (use new schema): | ||
| - Misconfigurations | ||
| - Identity Risks | ||
| - Attack Paths | ||
| - IaC & API Security Findings | ||
|
|
||
| **Platform Updates:** | ||
| - Dashboards | ||
| - DDSQL | ||
| - Sheets | ||
| - Findings Public API | ||
|
|
||
| ### Milestone 2: April 2026 | ||
|
|
||
| **Remaining Findings** (use new schema): | ||
| - Cloud Security Vulnerabilities | ||
| - Code Security Findings (SCA, SAST, IAST, Secrets) |
Contributor
There was a problem hiding this comment.
I think I would rather keep this out of the external docs so we can keep some wiggle room in case we wind up diverging from this timeline. Above, we already do a good job of describing what changes are coming, and I think that's sufficient.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What does this PR do? What is the motivation?
We need a document describing the findings v2 schema migration. See here.