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

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. (default: detailed_finding, example: detailed_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 finding.
type	string	The JSON:API type for findings. (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, region	snapshot_timestamp	Returns a single finding with message and resource configuration.
list_findings	select	region	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. Note: To filter and return only identity risks, add the following query parameter: ?filter[tags]=dd_rule_type:ciem ### Filtering Filters can be applied by appending query parameters to the URL. - Using a single filter: ?filter[attribute_key]=attribute_value - Chaining filters: ?filter[attribute_key]=attribute_value&filter[attribute_key]=attribute_value... - Filtering on tags: ?filter[tags]=tag_key:tag_value&filter[tags]=tag_key_2:tag_value_2 Here, attribute_key can be any of the filter keys described further below. 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. You can also use the negation operator on strings. For example, use filter[resource_type]=-aws* to filter for any non-AWS resources. 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. 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. ### Additional extension fields Additional extension fields are available for some findings. The data is available when you include the query parameter ?detailed_findings=true in the request. The following fields are available for findings: - external_id: The resource external ID related to the finding. - description: The description and remediation steps for the finding. - datadog_link: The Datadog relative link for the finding. - ip_addresses: The list of private IP addresses for the resource related to the finding. ### Response The response includes an array of finding objects, pagination metadata, and a count of items that match the query. Each finding object contains the following: - The finding ID that can be used in a GetFinding request to retrieve the full finding details. - Core attributes, including status, evaluation, high-level resource details, muted state, and rule details. - evaluation_changed_at and resource_discovery_date time stamps. - An array of associated tags.
mute_findings	exec	region, data		Mute or unmute findings.

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.
region	string	(default: datadoghq.com)
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

Returns a single finding with message and resource configuration.

SELECT
id,
attributes,
type
FROM datadog.security.findings
WHERE finding_id = '{{ finding_id }}' -- required
AND region = '{{ region }}' -- required
AND snapshot_timestamp = '{{ snapshot_timestamp }}'
;

list_findings

Get a list of findings. These include both misconfigurations and identity risks.

Note: To filter and return only identity risks, add the following query parameter: ?filter[tags]=dd_rule_type:ciem

### Filtering

Filters can be applied by appending query parameters to the URL.

- Using a single filter: ?filter[attribute_key]=attribute_value
- Chaining filters: ?filter[attribute_key]=attribute_value&filter[attribute_key]=attribute_value...
- Filtering on tags: ?filter[tags]=tag_key:tag_value&filter[tags]=tag_key_2:tag_value_2

Here, attribute_key can be any of the filter keys described further below.

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.

You can also use the negation operator on strings. For example, use filter[resource_type]=-aws* to filter for any non-AWS resources.

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.

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.

### Additional extension fields

Additional extension fields are available for some findings.

The data is available when you include the query parameter ?detailed_findings=true in the request.

The following fields are available for findings:
- external_id: The resource external ID related to the finding.
- description: The description and remediation steps for the finding.
- datadog_link: The Datadog relative link for the finding.
- ip_addresses: The list of private IP addresses for the resource related to the finding.

### Response

The response includes an array of finding objects, pagination metadata, and a count of items that match the query.

Each finding object contains the following:

- The finding ID that can be used in a GetFinding request to retrieve the full finding details.
- Core attributes, including status, evaluation, high-level resource details, muted state, and rule details.
- evaluation_changed_at and resource_discovery_date time stamps.
- An array of associated tags.

SELECT
id,
attributes,
type
FROM datadog.security.findings
WHERE region = '{{ region }}' -- required
AND 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

mute_findings

Mute or unmute findings.

EXEC datadog.security.findings.mute_findings 
@region='{{ region }}' --required 
@@json=
'{
"data": "{{ data }}"
}'
;