Sign in

v1

latestOpenAPI 3.0.02026-07-141,4077,1665.2 MB
Security Monitoring

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.
get/api/v2/posture_management/findings

Query parameters

page[limit]integer

Limit the number of findings returned. Must be <= 1000.

snapshot_timestampinteger

Return findings for a given snapshot of time (Unix ms).

page[cursor]string

Return the next page of findings pointed to by the cursor.

filter[tags]string

Return findings that have these associated tags (repeatable).

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).

filter[muted]boolean

Set to true to return findings that are muted. Set to false to return unmuted findings.

filter[rule_id]string

Return findings for the specified rule ID.

filter[rule_name]string

Return findings for the specified rule.

filter[resource_type]string

Return only findings for the specified resource type.

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).

filter[evaluation]'pass' | 'fail'

The evaluation of the finding.

Example:pass

Return only pass or fail findings.

filter[status]'critical' | 'high' | 'medium' | 'low' | 'info'

The status of the finding.

Example:critical

Return only findings with the specified status.

filter[vulnerability_type]FindingVulnerabilityType[]

Return findings that match the selected vulnerability types (repeatable).

[
  "misconfiguration"
]
detailed_findingsboolean

Return additional fields for some findings.

Response

OK

Example response

{
  "data": [
    {
      "attributes": {
        "datadog_link": "/security/compliance?panels=cpfinding%7Cevent%7CruleId%3Adef-000-u5t%7CresourceId%3Ae8c9ab7c52ebd7bf2fdb4db641082d7d%7CtabId%3Aoverview",
        "description": "## Remediation\n\n1. In the console, go to **Storage Account**.\n2. For each Storage Account, navigate to **Data Protection**.\n3. Select **Set soft delete enabled** and enter the number of days to retain soft deleted data.",
        "evaluation": "pass",
        "evaluation_changed_at": 1678721573794,
        "external_id": "arn:aws:s3:::my-example-bucket",
        "mute": {
          "description": "To be resolved later",
          "expiration_date": 1778721573794,
          "muted": true,
          "reason": "ACCEPTED_RISK",
          "start_date": 1678721573794,
          "uuid": "e51c9744-d158-11ec-ad23-da7ad0900002"
        },
        "resource": "my_resource_name",
        "resource_discovery_date": 1678721573794,
        "resource_type": "azure_storage_account",
        "rule": {
          "id": "dv2-jzf-41i",
          "name": "Soft delete is enabled for Azure Storage"
        },
        "status": "critical",
        "tags": [
          "cloud_provider:aws",
          "myTag:myValue"
        ],
        "vulnerability_type": "misconfiguration"
      },
      "id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==",
      "type": "finding"
    }
  ],
  "meta": {
    "page": {
      "cursor": "eyJhZnRlciI6IkFRQUFBWWJiaEJXQS1OY1dqUUFBQUFCQldXSmlhRUpYUVVGQlJFSktkbTlDTUdaWFRVbDNRVUUiLCJ2YWx1ZXMiOlsiY3JpdGljYWwiXX0=",
      "total_filtered_count": 213
    },
    "snapshot_timestamp": 1678721573794
  }
}