List security findings

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

Overview

Get a list of security findings that match a search query. See the schema for security findings.

Query Syntax

This endpoint uses the logs query syntax. Findings attributes (living in the attributes.attributes. namespace) are prefixed by @ when queried. Tags are queried without a prefix.

Example: @severity:(critical OR high) @status:open team:platform

This endpoint requires any of the following permissions:
  • security_monitoring_findings_read
  • appsec_vm_read

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

    Arguments

    Query Strings

    Name

    Type

    Description

    filter[query]

    string

    The search query following log search syntax.

    page[cursor]

    string

    Get the next page of results with a cursor provided in the previous query.

    page[limit]

    integer

    The maximum number of findings in the response.

    sort

    enum

    Sorts by @detection_changed_at.
    Allowed enum values: @detection_changed_at, -@detection_changed_at

    Response

    OK

    The expected response schema when listing security findings.

    Expand All

    Field

    Type

    Description

    data

    [object]

    Array of security findings matching the search query.

    attributes

    object

    The JSON object containing all attributes of the security finding.

    attributes

    object

    The custom attributes of the security finding.

    tags

    [string]

    List of tags associated with the security finding.

    timestamp

    int64

    The Unix timestamp at which the detection changed for the resource. Same value as @detection_changed_at.

    id

    string

    The unique ID of the security finding.

    type

    enum

    The type of the security finding resource. Allowed enum values: finding

    default: finding

    links

    object

    Links for pagination.

    next

    string

    Link for the next page of results. Note that paginated requests can also be made using the POST endpoint.

    meta

    object

    Metadata about the response.

    elapsed

    int64

    The time elapsed in milliseconds.

    page

    object

    Pagination information.

    after

    string

    The cursor used to get the next page of results.

    request_id

    string

    The identifier of the request.

    status

    enum

    The status of the response. Allowed enum values: done,timeout

    {
      "data": [
        {
          "attributes": {
            "attributes": {
              "severity": "high",
              "status": "open"
            },
            "tags": [
              "team:platform",
              "env:prod"
            ],
            "timestamp": 1765901760
          },
          "id": "ZGVmLTAwcC1pZXJ-aS0wZjhjNjMyZDNmMzRlZTgzNw==",
          "type": "finding"
        }
      ],
      "links": {
        "next": "https://app.datadoghq.com/api/v2/security/findings?page[cursor]=eyJhZnRlciI6IkF3QUFBWnPcm1pd0FBQUJbVlBQUKBa1pqRTVdZUzSTBNemN0YWiIsLTE3Mjk0MzYwMjFdfQ==\u0026page[limit]=25"
      },
      "meta": {
        "elapsed": 548,
        "page": {
          "after": "eyJhZnRlciI6IkFRQUFBWWJiaEJXQS1OY1dqUUFBQUFCQldXSmlhRUpYUVVGQlJFSktkbTlDTUdaWFRVbDNRVUUiLCJ2YWx1ZXMiOlsiY3JpdGljYWwiXX0="
        },
        "request_id": "pddv1ChZwVlMxMUdYRFRMQ1lyb3B4MGNYbFlnIi0KHQu35LDbucx",
        "status": "done"
      }
    }

    Bad Request

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
      "errors": [
        "Bad Request"
      ]
    }

    Forbidden

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
      "errors": [
        "Bad Request"
      ]
    }

    Too many requests

    API error response.

    Expand All

    Field

    Type

    Description

    errors [required]

    [string]

    A list of errors.

    {
      "errors": [
        "Bad Request"
      ]
    }

    Code Example

                      # 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.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/security/findings" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
    """
    List security findings returns "OK" response
    """
    
    from datadog_api_client import ApiClient, Configuration
    from datadog_api_client.v2.api.security_monitoring_api import SecurityMonitoringApi
    
    configuration = Configuration()
    with ApiClient(configuration) as api_client:
        api_instance = SecurityMonitoringApi(api_client)
        response = api_instance.list_security_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.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"
    # List security findings returns "OK" response
    
    require "datadog_api_client"
    api_instance = DatadogAPIClient::V2::SecurityMonitoringAPI.new
    p api_instance.list_security_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.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"
    // List security 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()
    	apiClient := datadog.NewAPIClient(configuration)
    	api := datadogV2.NewSecurityMonitoringApi(apiClient)
    	resp, r, err := api.ListSecurityFindings(ctx, *datadogV2.NewListSecurityFindingsOptionalParameters())
    
    	if err != nil {
    		fmt.Fprintf(os.Stderr, "Error when calling `SecurityMonitoringApi.ListSecurityFindings`: %v\n", err)
    		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
    	}
    
    	responseContent, _ := json.MarshalIndent(resp, "", "  ")
    	fmt.Fprintf(os.Stdout, "Response from `SecurityMonitoringApi.ListSecurityFindings`:\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.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" go run "main.go"
    // List security 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.ListSecurityFindingsResponse;
    
    public class Example {
      public static void main(String[] args) {
        ApiClient defaultClient = ApiClient.getDefaultApiClient();
        SecurityMonitoringApi apiInstance = new SecurityMonitoringApi(defaultClient);
    
        try {
          ListSecurityFindingsResponse result = apiInstance.listSecurityFindings();
          System.out.println(result);
        } catch (ApiException e) {
          System.err.println("Exception when calling SecurityMonitoringApi#listSecurityFindings");
          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.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" java "Example.java"
    // List security findings returns "OK" response
    use datadog_api_client::datadog;
    use datadog_api_client::datadogV2::api_security_monitoring::ListSecurityFindingsOptionalParams;
    use datadog_api_client::datadogV2::api_security_monitoring::SecurityMonitoringAPI;
    
    #[tokio::main]
    async fn main() {
        let configuration = datadog::Configuration::new();
        let api = SecurityMonitoringAPI::with_config(configuration);
        let resp = api
            .list_security_findings(ListSecurityFindingsOptionalParams::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.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
    /**
     * List security findings returns "OK" response
     */
    
    import { client, v2 } from "@datadog/datadog-api-client";
    
    const configuration = client.createConfiguration();
    const apiInstance = new v2.SecurityMonitoringApi(configuration);
    
    apiInstance
      .listSecurityFindings()
      .then((data: v2.ListSecurityFindingsResponse) => {
        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.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" tsc "example.ts"