findings
Creates, updates, deletes, gets or lists a findings resource.
Overview
| Name | findings |
| Type | Resource |
| Id | datadog.security.findings |
Fields
The following fields are returned by SELECT queries:
- get_finding
- list_findings
| Name | Datatype | Description |
|---|---|---|
id | string | The unique ID for this finding. (example: ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==) |
attributes | object | The JSON:API attributes of the detailed finding. |
type | string | The JSON:API type for findings that have the message and resource configuration. (detailed_finding) (default: detailed_finding, example: detailed_finding) |
| Name | Datatype | Description |
|---|---|---|
id | string | The unique ID for this finding. (example: ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==) |
attributes | object | The JSON:API attributes of the finding. |
type | string | The JSON:API type for findings. (finding) (default: finding, example: finding) |
Methods
The following methods are available for this resource:
| Name | Accessible by | Required Params | Optional Params | Description |
|---|---|---|---|---|
get_finding | select | finding_id | snapshot_timestamp | Returns a single finding with message and resource configuration. |
list_findings | select | page[limit], snapshot_timestamp, page[cursor], filter[tags], filter[evaluation_changed_at], filter[muted], filter[rule_id], filter[rule_name], filter[resource_type], filter[@resource_id], filter[discovery_timestamp], filter[evaluation], filter[status], filter[vulnerability_type], detailed_findings | Get a list of findings. These include both misconfigurations and identity risks.<br /><br />Note: To filter and return only identity risks, add the following query parameter: ?filter[tags]=dd_rule_type:ciem<br /><br />### Filtering<br /><br />Filters can be applied by appending query parameters to the URL.<br /><br /> - Using a single filter: ?filter[attribute_key]=attribute_value<br /> - Chaining filters: ?filter[attribute_key]=attribute_value&filter[attribute_key]=attribute_value...<br /> - Filtering on tags: ?filter[tags]=tag_key:tag_value&filter[tags]=tag_key_2:tag_value_2<br /><br />Here, attribute_key can be any of the filter keys described further below.<br /><br />Query parameters of type integer support comparison operators (>, >=, <, <=). This is particularly useful when filtering by evaluation_changed_at or resource_discovery_timestamp. For example: ?filter[evaluation_changed_at]=>20123123121.<br /><br />You can also use the negation operator on strings. For example, use filter[resource_type]=-aws* to filter for any non-AWS resources.<br /><br />The operator must come after the equal sign. For example, to filter with the >= operator, add the operator after the equal sign: filter[evaluation_changed_at]=>=1678809373257.<br /><br />Query parameters must be only among the documented ones and with values of correct types. Duplicated query parameters (e.g. filter[status]=low&filter[status]=info) are not allowed.<br /><br />### Additional extension fields<br /><br />Additional extension fields are available for some findings.<br /><br />The data is available when you include the query parameter ?detailed_findings=true in the request.<br /><br />The following fields are available for findings:<br />- external_id: The resource external ID related to the finding.<br />- description: The description and remediation steps for the finding.<br />- datadog_link: The Datadog relative link for the finding.<br />- ip_addresses: The list of private IP addresses for the resource related to the finding.<br /><br />### Response<br /><br />The response includes an array of finding objects, pagination metadata, and a count of items that match the query.<br /><br />Each finding object contains the following:<br /><br />- The finding ID that can be used in a GetFinding request to retrieve the full finding details.<br />- Core attributes, including status, evaluation, high-level resource details, muted state, and rule details.<br />- evaluation_changed_at and resource_discovery_date time stamps.<br />- An array of associated tags. | |
mute_security_findings | exec | data | Mute or unmute security findings.<br />You can mute or unmute up to 100 security findings per request. The request body must include is_muted and reason attributes. The allowed reasons depend on whether the finding is being muted or unmuted:<br /> - To mute a finding: PENDING_FIX, FALSE_POSITIVE, OTHER, NO_FIX, DUPLICATE, RISK_ACCEPTED.<br /> - To unmute a finding: NO_PENDING_FIX, HUMAN_ERROR, NO_LONGER_ACCEPTED_RISK, OTHER. |
Parameters
Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.
| Name | Datatype | Description |
|---|---|---|
finding_id | string | The ID of the finding. |
site | string | The Datadog site (region) for your organization, for example datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, ap1.datadoghq.com, ap2.datadoghq.com, datadoghq.eu, ddog-gov.com. Resolved from the DD_SITE environment variable when set. Optional: defaults to datadoghq.com, or the value of the DD_SITE environment variable when set; a WHERE value overrides both. |
detailed_findings | boolean | Return additional fields for some findings. (example: [true]) |
filter[@resource_id] | string | Return only findings for the specified resource id. |
filter[discovery_timestamp] | string | Return findings that were found on a specified date (Unix ms) or date range (using comparison operators). (example: >=1678721573794) |
filter[evaluation] | string | Return only pass or fail findings. |
filter[evaluation_changed_at] | string | Return findings that have changed from pass to fail or vice versa on a specified date (Unix ms) or date range (using comparison operators). (example: >=1678721573794) |
filter[muted] | boolean | Set to true to return findings that are muted. Set to false to return unmuted findings. |
filter[resource_type] | string | Return only findings for the specified resource type. |
filter[rule_id] | string | Return findings for the specified rule ID. |
filter[rule_name] | string | Return findings for the specified rule. |
filter[status] | string | Return only findings with the specified status. |
filter[tags] | string | Return findings that have these associated tags (repeatable). (example: filter[tags]=cloud_provider:aws&filter[tags]=aws_account:999999999999) |
filter[vulnerability_type] | array | Return findings that match the selected vulnerability types (repeatable). (example: [misconfiguration]) |
page[cursor] | string | Return the next page of findings pointed to by the cursor. (example: eyJhZnRlciI6IkFRQUFBWWJiaEJXQS1OY1dqUUFBQUFCQldXSmlhRUpYUVVGQlJFSktkbTlDTUdaWFRVbDNRVUUiLCJ2YWx1ZXMiOlsiY3JpdGljYWwiXX0=) |
page[limit] | integer (int64) | Limit the number of findings returned. Must be <= 1000. (example: 50) |
snapshot_timestamp | integer (int64) | Return findings for a given snapshot of time (Unix ms). (example: 1678721573794) |
SELECT examples
- get_finding
- list_findings
Returns a single finding with message and resource configuration.
SELECT
id,
attributes,
type
FROM datadog.security.findings
WHERE finding_id = '{{ finding_id }}' -- required
AND snapshot_timestamp = '{{ snapshot_timestamp }}'
;
Get a list of findings. These include both misconfigurations and identity risks.<br /><br />Note: To filter and return only identity risks, add the following query parameter: ?filter[tags]=dd_rule_type:ciem<br /><br />### Filtering<br /><br />Filters can be applied by appending query parameters to the URL.<br /><br /> - Using a single filter: ?filter[attribute_key]=attribute_value<br /> - Chaining filters: ?filter[attribute_key]=attribute_value&filter[attribute_key]=attribute_value...<br /> - Filtering on tags: ?filter[tags]=tag_key:tag_value&filter[tags]=tag_key_2:tag_value_2<br /><br />Here, attribute_key can be any of the filter keys described further below.<br /><br />Query parameters of type integer support comparison operators (>, >=, <, <=). This is particularly useful when filtering by evaluation_changed_at or resource_discovery_timestamp. For example: ?filter[evaluation_changed_at]=>20123123121.<br /><br />You can also use the negation operator on strings. For example, use filter[resource_type]=-aws* to filter for any non-AWS resources.<br /><br />The operator must come after the equal sign. For example, to filter with the >= operator, add the operator after the equal sign: filter[evaluation_changed_at]=>=1678809373257.<br /><br />Query parameters must be only among the documented ones and with values of correct types. Duplicated query parameters (e.g. filter[status]=low&filter[status]=info) are not allowed.<br /><br />### Additional extension fields<br /><br />Additional extension fields are available for some findings.<br /><br />The data is available when you include the query parameter ?detailed_findings=true in the request.<br /><br />The following fields are available for findings:<br />- external_id: The resource external ID related to the finding.<br />- description: The description and remediation steps for the finding.<br />- datadog_link: The Datadog relative link for the finding.<br />- ip_addresses: The list of private IP addresses for the resource related to the finding.<br /><br />### Response<br /><br />The response includes an array of finding objects, pagination metadata, and a count of items that match the query.<br /><br />Each finding object contains the following:<br /><br />- The finding ID that can be used in a GetFinding request to retrieve the full finding details.<br />- Core attributes, including status, evaluation, high-level resource details, muted state, and rule details.<br />- evaluation_changed_at and resource_discovery_date time stamps.<br />- An array of associated tags.
SELECT
id,
attributes,
type
FROM datadog.security.findings
WHERE page[limit] = '{{ page[limit] }}'
AND snapshot_timestamp = '{{ snapshot_timestamp }}'
AND page[cursor] = '{{ page[cursor] }}'
AND filter[tags] = '{{ filter[tags] }}'
AND filter[evaluation_changed_at] = '{{ filter[evaluation_changed_at] }}'
AND filter[muted] = '{{ filter[muted] }}'
AND filter[rule_id] = '{{ filter[rule_id] }}'
AND filter[rule_name] = '{{ filter[rule_name] }}'
AND filter[resource_type] = '{{ filter[resource_type] }}'
AND filter[@resource_id] = '{{ filter[@resource_id] }}'
AND filter[discovery_timestamp] = '{{ filter[discovery_timestamp] }}'
AND filter[evaluation] = '{{ filter[evaluation] }}'
AND filter[status] = '{{ filter[status] }}'
AND filter[vulnerability_type] = '{{ filter[vulnerability_type] }}'
AND detailed_findings = '{{ detailed_findings }}'
;
Lifecycle Methods
EXEC variables use wire (API) names.
- mute_security_findings
Mute or unmute security findings.<br />You can mute or unmute up to 100 security findings per request. The request body must include is_muted and reason attributes. The allowed reasons depend on whether the finding is being muted or unmuted:<br /> - To mute a finding: PENDING_FIX, FALSE_POSITIVE, OTHER, NO_FIX, DUPLICATE, RISK_ACCEPTED.<br /> - To unmute a finding: NO_PENDING_FIX, HUMAN_ERROR, NO_LONGER_ACCEPTED_RISK, OTHER.
EXEC datadog.security.findings.mute_security_findings
@@json=
'{
"data": "{{ data }}"
}'
;