List findings

Note: This endpoint uses the legacy security findings data model and is planned for deprecation. Use the search security findings endpoint, which is based on the new security findings schema, to search security findings. If you have any feedback, contact Datadog support.

GET https://api.ap1.datadoghq.com/api/v2/posture_management/findingshttps://api.ap2.datadoghq.com/api/v2/posture_management/findingshttps://api.datadoghq.eu/api/v2/posture_management/findingshttps://api.ddog-gov.com/api/v2/posture_management/findingshttps://api.us2.ddog-gov.com/api/v2/posture_management/findingshttps://api.uk1.datadoghq.com/api/v2/posture_management/findingshttps://api.datadoghq.com/api/v2/posture_management/findingshttps://api.us3.datadoghq.com/api/v2/posture_management/findingshttps://api.us5.datadoghq.com/api/v2/posture_management/findings

Présentation

Récupérer une liste de résultats. Ceux-ci incluent à la fois les erreurs de configuration et les risques liés aux identités.

Remarque : pour filtrer et renvoyer uniquement les risques liés aux identités, ajoutez le paramètre de requête suivant : ?filter[tags]=dd_rule_type:ciem

Filtrage

Les filtres peuvent être appliqués en ajoutant des paramètres de requête à l’URL.

  • Utilisation d’un seul filtre : ?filter[attribute_key]=attribute_value
  • Chaînage de filtres : ?filter[attribute_key]=attribute_value&filter[attribute_key]=attribute_value...
  • Filtrage sur les tags : ?filter[tags]=tag_key:tag_value&filter[tags]=tag_key_2:tag_value_2

Ici, attribute_key peut correspondre à l’une des clés de filtre décrites ci-dessous.

Les paramètres de requête de type integer prennent en charge les opérateurs de comparaison (>, >=, <, <=). Cela est particulièrement utile lors du filtrage par evaluation_changed_at ou resource_discovery_timestamp. Par exemple : ?filter[evaluation_changed_at]=>20123123121.

Vous pouvez également utiliser l’opérateur de négation sur les chaînes de caractères. Par exemple, utilisez filter[resource_type]=-aws* pour filtrer toutes les ressources non AWS.

L’opérateur doit être placé après le signe égal. Par exemple, pour filtrer avec l’opérateur >=, ajoutez l’opérateur après le signe égal : filter[evaluation_changed_at]=>=1678809373257.

Les paramètres de requête doivent uniquement faire partie des paramètres documentés et avoir des valeurs de types corrects. Les paramètres de requête dupliqués (par exemple filter[status]=low&filter[status]=info) ne sont pas autorisés.

Champs d’extension supplémentaires

Des champs d’extension supplémentaires sont disponibles pour certains résultats.

Les données sont disponibles lorsque vous incluez le paramètre de requête ?detailed_findings=true dans la requête.

Les champs suivants sont disponibles pour les résultats :

  • external_id : l’ID externe de la ressource liée au résultat.
  • description : la description et les étapes de remédiation pour le résultat.
  • datadog_link : le lien relatif Datadog pour le résultat.
  • ip_addresses : la liste des adresses IP privées de la ressource liée au résultat.

Réponse

La réponse inclut un tableau d’objets de résultats, des métadonnées de pagination et un décompte des éléments correspondant à la requête.

Chaque objet de résultat contient les éléments suivants :

  • L’ID du résultat, qui peut être utilisé dans une requête GetFinding pour récupérer les détails complets du résultat.
  • Les attributs principaux, notamment le statut, l’évaluation, les détails généraux de la ressource, l’état de mise en sourdine et les détails de la règle.
  • Les horodatages evaluation_changed_at et resource_discovery_date.
  • Un tableau de tags associés.

OAuth apps require the security_monitoring_findings_read authorization scope to access this endpoint.

Arguments

Chaînes de requête

Nom

Type

Description

page[limit]

integer

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

snapshot_timestamp

integer

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]

enum

Return only pass or fail findings.
Allowed enum values: pass, fail

filter[status]

enum

Return only findings with the specified status.
Allowed enum values: critical, high, medium, low, info

filter[vulnerability_type]

array

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

detailed_findings

boolean

Return additional fields for some findings.

Réponse

OK

The expected response schema when listing findings.

Expand All

Champ

Type

Description

data [required]

[object]

Array of findings.

attributes

object

The JSON:API attributes of the finding.

datadog_link

string

The Datadog relative link for this finding.

description

string

The description and remediation steps for this finding.

evaluation

enum

The evaluation of the finding. Allowed enum values: pass,fail

evaluation_changed_at

int64

The date on which the evaluation for this finding changed (Unix ms).

external_id

string

The cloud-based ID for the resource related to the finding.

mute

object

Information about the mute status of this finding.

description

string

Additional information about the reason why this finding is muted or unmuted.

expiration_date

int64

The expiration date of the mute or unmute action (Unix ms).

muted

boolean

Whether this finding is muted or unmuted.

reason

enum

The reason why this finding is muted or unmuted. Allowed enum values: PENDING_FIX,FALSE_POSITIVE,ACCEPTED_RISK,NO_PENDING_FIX,HUMAN_ERROR,NO_LONGER_ACCEPTED_RISK,OTHER

start_date

int64

The start of the mute period.

uuid

string

The ID of the user who muted or unmuted this finding.

resource

string

The resource name of this finding.

resource_discovery_date

int64

The date on which the resource was discovered (Unix ms).

resource_type

string

The resource type of this finding.

rule

object

The rule that triggered this finding.

id

string

The ID of the rule that triggered this finding.

name

string

The name of the rule that triggered this finding.

status

enum

The status of the finding. Allowed enum values: critical,high,medium,low,info

tags

[string]

The tags associated with this finding.

vulnerability_type

enum

The vulnerability type of the finding. Allowed enum values: misconfiguration,attack_path,identity_risk,api_security

id

string

The unique ID for this finding.

type

enum

The JSON:API type for findings. Allowed enum values: finding

default: finding

meta [required]

object

Metadata for pagination.

page

object

Pagination and findings count information.

cursor

string

The cursor used to paginate requests.

total_filtered_count

int64

The total count of findings after the filter has been applied.

snapshot_timestamp

int64

The point in time corresponding to the listed findings.

{
  "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
  }
}

Bad Request: The server cannot process the request due to invalid syntax in the request.

API error response.

Expand All

Champ

Type

Description

errors [required]

[object]

A list of errors.

detail

string

A human-readable explanation specific to this occurrence of the error.

meta

object

Non-standard meta-information about the error

source

object

References to the source of the error.

header

string

A string indicating the name of a single request header which caused the error.

parameter

string

A string indicating which URI query parameter caused the error.

pointer

string

A JSON pointer to the value in the request document that caused the error.

status

string

Status code of the response.

title

string

Short human-readable summary of the error.

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

Forbidden: Access denied

API error response.

Expand All

Champ

Type

Description

errors [required]

[object]

A list of errors.

detail

string

A human-readable explanation specific to this occurrence of the error.

meta

object

Non-standard meta-information about the error

source

object

References to the source of the error.

header

string

A string indicating the name of a single request header which caused the error.

parameter

string

A string indicating which URI query parameter caused the error.

pointer

string

A JSON pointer to the value in the request document that caused the error.

status

string

Status code of the response.

title

string

Short human-readable summary of the error.

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

Not Found: The requested finding cannot be found.

API error response.

Expand All

Champ

Type

Description

errors [required]

[object]

A list of errors.

detail

string

A human-readable explanation specific to this occurrence of the error.

meta

object

Non-standard meta-information about the error

source

object

References to the source of the error.

header

string

A string indicating the name of a single request header which caused the error.

parameter

string

A string indicating which URI query parameter caused the error.

pointer

string

A JSON pointer to the value in the request document that caused the error.

status

string

Status code of the response.

title

string

Short human-readable summary of the error.

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

Too many requests: The rate limit set by the API has been exceeded.

API error response.

Expand All

Champ

Type

Description

errors [required]

[object]

A list of errors.

detail

string

A human-readable explanation specific to this occurrence of the error.

meta

object

Non-standard meta-information about the error

source

object

References to the source of the error.

header

string

A string indicating the name of a single request header which caused the error.

parameter

string

A string indicating which URI query parameter caused the error.

pointer

string

A JSON pointer to the value in the request document that caused the error.

status

string

Status code of the response.

title

string

Short human-readable summary of the error.

{
  "errors": [
    {
      "detail": "Missing required attribute in body",
      "meta": {},
      "source": {
        "header": "Authorization",
        "parameter": "limit",
        "pointer": "/data/attributes/title"
      },
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

Exemple de code

                  # Curl command
curl -X GET "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.uk1.datadoghq.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/posture_management/findings" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
"""
List findings returns "OK" response
"""

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.security_monitoring_api import SecurityMonitoringApi

configuration = Configuration()
configuration.unstable_operations["list_findings"] = True
with ApiClient(configuration) as api_client:
    api_instance = SecurityMonitoringApi(api_client)
    response = api_instance.list_findings()

    print(response)

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"
# List findings returns "OK" response

require "datadog_api_client"
DatadogAPIClient.configure do |config|
  config.unstable_operations["v2.list_findings".to_sym] = true
end
api_instance = DatadogAPIClient::V2::SecurityMonitoringAPI.new
p api_instance.list_findings()

Instructions

First install the library and its dependencies and then save the example to example.rb and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"
// List findings returns "OK" response

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV2"
)

func main() {
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	configuration.SetUnstableOperationEnabled("v2.ListFindings", true)
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewSecurityMonitoringApi(apiClient)
	resp, r, err := api.ListFindings(ctx, *datadogV2.NewListFindingsOptionalParameters())

	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `SecurityMonitoringApi.ListFindings`: %v\n", err)
		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
	}

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `SecurityMonitoringApi.ListFindings`:\n%s\n", responseContent)
}

Instructions

First install the library and its dependencies and then save the example to main.go and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" go run "main.go"
// List findings returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.SecurityMonitoringApi;
import com.datadog.api.client.v2.model.ListFindingsResponse;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    defaultClient.setUnstableOperationEnabled("v2.listFindings", true);
    SecurityMonitoringApi apiInstance = new SecurityMonitoringApi(defaultClient);

    try {
      ListFindingsResponse result = apiInstance.listFindings();
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling SecurityMonitoringApi#listFindings");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Instructions

First install the library and its dependencies and then save the example to Example.java and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" java "Example.java"
// List findings returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_security_monitoring::ListFindingsOptionalParams;
use datadog_api_client::datadogV2::api_security_monitoring::SecurityMonitoringAPI;

#[tokio::main]
async fn main() {
    let mut configuration = datadog::Configuration::new();
    configuration.set_unstable_operation_enabled("v2.ListFindings", true);
    let api = SecurityMonitoringAPI::with_config(configuration);
    let resp = api
        .list_findings(ListFindingsOptionalParams::default())
        .await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}

Instructions

First install the library and its dependencies and then save the example to src/main.rs and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
/**
 * List findings returns "OK" response
 */

import { client, v2 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration();
configuration.unstableOperations["v2.listFindings"] = true;
const apiInstance = new v2.SecurityMonitoringApi(configuration);

apiInstance
  .listFindings()
  .then((data: v2.ListFindingsResponse) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  })
  .catch((error: any) => console.error(error));

Instructions

First install the library and its dependencies and then save the example to example.ts and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comuk1.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" tsc "example.ts"