Search security findings

POST https://api.ap1.datadoghq.com/api/v2/security/findings/searchhttps://api.ap2.datadoghq.com/api/v2/security/findings/searchhttps://api.datadoghq.eu/api/v2/security/findings/searchhttps://api.ddog-gov.com/api/v2/security/findings/searchhttps://api.us2.ddog-gov.com/api/v2/security/findings/searchhttps://api.datadoghq.com/api/v2/security/findings/searchhttps://api.us3.datadoghq.com/api/v2/security/findings/searchhttps://api.us5.datadoghq.com/api/v2/security/findings/search

Overview

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

Query Syntax

The API 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.

    Request

    Body Data (required)

    Expand All

    Field

    Type

    Description

    data

    object

    Request data for searching security findings.

    attributes

    object

    Request attributes for searching security findings.

    filter

    string

    The search query following log search syntax.

    default: *

    page

    object

    Pagination attributes for the search request.

    cursor

    string

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

    limit

    int64

    The maximum number of security findings in the response.

    default: 10

    sort

    enum

    The sort parameters when querying security findings. Allowed enum values: @detection_changed_at,-@detection_changed_at

    default: -@detection_changed_at

    {
      "data": {
        "attributes": {
          "filter": "@severity:(critical OR high)"
        }
      }
    }
    {
      "data": {
        "attributes": {
          "filter": "@severity:(critical OR high)",
          "page": {
            "limit": 1
          }
        }
      }
    }

    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

                              ## default
    # 
    
    # Curl command
    curl -X POST "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/search" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "data": { "attributes": { "filter": "@severity:(critical OR high) @status:open team:platform", "page": { "cursor": "eyJhZnRlciI6IkF3QUFBWnPcm1pd0FBQUJbVlBQUKBa1pqRTVdZUzSTBNemN0YWiIsLTE3Mjk0MzYwMjFdfQ==", "limit": 25 }, "sort": "@detection_changed_at" } } } EOF
                              ## default
    # 
    
    # Curl command
    curl -X POST "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/search" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "data": { "attributes": { "filter": "@severity:(critical OR high) @status:open team:platform", "page": { "cursor": "eyJhZnRlciI6IkF3QUFBWnPcm1pd0FBQUJbVlBQUKBa1pqRTVdZUzSTBNemN0YWiIsLTE3Mjk0MzYwMjFdfQ==", "limit": 25 }, "sort": "@detection_changed_at" } } } EOF
    // Search 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() {
    	body := datadogV2.SecurityFindingsSearchRequest{
    		Data: &datadogV2.SecurityFindingsSearchRequestData{
    			Attributes: &datadogV2.SecurityFindingsSearchRequestDataAttributes{
    				Filter: datadog.PtrString("@severity:(critical OR high)"),
    			},
    		},
    	}
    	ctx := datadog.NewDefaultContext(context.Background())
    	configuration := datadog.NewConfiguration()
    	apiClient := datadog.NewAPIClient(configuration)
    	api := datadogV2.NewSecurityMonitoringApi(apiClient)
    	resp, r, err := api.SearchSecurityFindings(ctx, body)
    
    	if err != nil {
    		fmt.Fprintf(os.Stderr, "Error when calling `SecurityMonitoringApi.SearchSecurityFindings`: %v\n", err)
    		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
    	}
    
    	responseContent, _ := json.MarshalIndent(resp, "", "  ")
    	fmt.Fprintf(os.Stdout, "Response from `SecurityMonitoringApi.SearchSecurityFindings`:\n%s\n", responseContent)
    }
    
    // Search security findings returns "OK" response with pagination
    
    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() {
    	body := datadogV2.SecurityFindingsSearchRequest{
    		Data: &datadogV2.SecurityFindingsSearchRequestData{
    			Attributes: &datadogV2.SecurityFindingsSearchRequestDataAttributes{
    				Filter: datadog.PtrString("@severity:(critical OR high)"),
    				Page: &datadogV2.SecurityFindingsSearchRequestPage{
    					Limit: datadog.PtrInt64(1),
    				},
    			},
    		},
    	}
    	ctx := datadog.NewDefaultContext(context.Background())
    	configuration := datadog.NewConfiguration()
    	apiClient := datadog.NewAPIClient(configuration)
    	api := datadogV2.NewSecurityMonitoringApi(apiClient)
    	resp, r, err := api.SearchSecurityFindings(ctx, body)
    
    	if err != nil {
    		fmt.Fprintf(os.Stderr, "Error when calling `SecurityMonitoringApi.SearchSecurityFindings`: %v\n", err)
    		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
    	}
    
    	responseContent, _ := json.MarshalIndent(resp, "", "  ")
    	fmt.Fprintf(os.Stdout, "Response from `SecurityMonitoringApi.SearchSecurityFindings`:\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"
    // Search 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;
    import com.datadog.api.client.v2.model.SecurityFindingsSearchRequest;
    import com.datadog.api.client.v2.model.SecurityFindingsSearchRequestData;
    import com.datadog.api.client.v2.model.SecurityFindingsSearchRequestDataAttributes;
    
    public class Example {
      public static void main(String[] args) {
        ApiClient defaultClient = ApiClient.getDefaultApiClient();
        SecurityMonitoringApi apiInstance = new SecurityMonitoringApi(defaultClient);
    
        SecurityFindingsSearchRequest body =
            new SecurityFindingsSearchRequest()
                .data(
                    new SecurityFindingsSearchRequestData()
                        .attributes(
                            new SecurityFindingsSearchRequestDataAttributes()
                                .filter("@severity:(critical OR high)")));
    
        try {
          ListSecurityFindingsResponse result = apiInstance.searchSecurityFindings(body);
          System.out.println(result);
        } catch (ApiException e) {
          System.err.println("Exception when calling SecurityMonitoringApi#searchSecurityFindings");
          System.err.println("Status code: " + e.getCode());
          System.err.println("Reason: " + e.getResponseBody());
          System.err.println("Response headers: " + e.getResponseHeaders());
          e.printStackTrace();
        }
      }
    }
    
    // Search security findings returns "OK" response with pagination
    
    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;
    import com.datadog.api.client.v2.model.SecurityFindingsSearchRequest;
    import com.datadog.api.client.v2.model.SecurityFindingsSearchRequestData;
    import com.datadog.api.client.v2.model.SecurityFindingsSearchRequestDataAttributes;
    import com.datadog.api.client.v2.model.SecurityFindingsSearchRequestPage;
    
    public class Example {
      public static void main(String[] args) {
        ApiClient defaultClient = ApiClient.getDefaultApiClient();
        SecurityMonitoringApi apiInstance = new SecurityMonitoringApi(defaultClient);
    
        SecurityFindingsSearchRequest body =
            new SecurityFindingsSearchRequest()
                .data(
                    new SecurityFindingsSearchRequestData()
                        .attributes(
                            new SecurityFindingsSearchRequestDataAttributes()
                                .filter("@severity:(critical OR high)")
                                .page(new SecurityFindingsSearchRequestPage().limit(1L))));
    
        try {
          ListSecurityFindingsResponse result = apiInstance.searchSecurityFindings(body);
          System.out.println(result);
        } catch (ApiException e) {
          System.err.println("Exception when calling SecurityMonitoringApi#searchSecurityFindings");
          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"
    """
    Search security findings returns "OK" response
    """
    
    from datadog_api_client import ApiClient, Configuration
    from datadog_api_client.v2.api.security_monitoring_api import SecurityMonitoringApi
    from datadog_api_client.v2.model.security_findings_search_request import SecurityFindingsSearchRequest
    from datadog_api_client.v2.model.security_findings_search_request_data import SecurityFindingsSearchRequestData
    from datadog_api_client.v2.model.security_findings_search_request_data_attributes import (
        SecurityFindingsSearchRequestDataAttributes,
    )
    
    body = SecurityFindingsSearchRequest(
        data=SecurityFindingsSearchRequestData(
            attributes=SecurityFindingsSearchRequestDataAttributes(
                filter="@severity:(critical OR high)",
            ),
        ),
    )
    
    configuration = Configuration()
    with ApiClient(configuration) as api_client:
        api_instance = SecurityMonitoringApi(api_client)
        response = api_instance.search_security_findings(body=body)
    
        print(response)
    
    """
    Search security findings returns "OK" response with pagination
    """
    
    from datadog_api_client import ApiClient, Configuration
    from datadog_api_client.v2.api.security_monitoring_api import SecurityMonitoringApi
    from datadog_api_client.v2.model.security_findings_search_request import SecurityFindingsSearchRequest
    from datadog_api_client.v2.model.security_findings_search_request_data import SecurityFindingsSearchRequestData
    from datadog_api_client.v2.model.security_findings_search_request_data_attributes import (
        SecurityFindingsSearchRequestDataAttributes,
    )
    from datadog_api_client.v2.model.security_findings_search_request_page import SecurityFindingsSearchRequestPage
    
    body = SecurityFindingsSearchRequest(
        data=SecurityFindingsSearchRequestData(
            attributes=SecurityFindingsSearchRequestDataAttributes(
                filter="@severity:(critical OR high)",
                page=SecurityFindingsSearchRequestPage(
                    limit=1,
                ),
            ),
        ),
    )
    
    configuration = Configuration()
    with ApiClient(configuration) as api_client:
        api_instance = SecurityMonitoringApi(api_client)
        response = api_instance.search_security_findings(body=body)
    
        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"
    # Search security findings returns "OK" response
    
    require "datadog_api_client"
    api_instance = DatadogAPIClient::V2::SecurityMonitoringAPI.new
    
    body = DatadogAPIClient::V2::SecurityFindingsSearchRequest.new({
      data: DatadogAPIClient::V2::SecurityFindingsSearchRequestData.new({
        attributes: DatadogAPIClient::V2::SecurityFindingsSearchRequestDataAttributes.new({
          filter: "@severity:(critical OR high)",
        }),
      }),
    })
    p api_instance.search_security_findings(body)
    
    # Search security findings returns "OK" response with pagination
    
    require "datadog_api_client"
    api_instance = DatadogAPIClient::V2::SecurityMonitoringAPI.new
    
    body = DatadogAPIClient::V2::SecurityFindingsSearchRequest.new({
      data: DatadogAPIClient::V2::SecurityFindingsSearchRequestData.new({
        attributes: DatadogAPIClient::V2::SecurityFindingsSearchRequestDataAttributes.new({
          filter: "@severity:(critical OR high)",
          page: DatadogAPIClient::V2::SecurityFindingsSearchRequestPage.new({
            limit: 1,
          }),
        }),
      }),
    })
    p api_instance.search_security_findings(body)
    

    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"
    // Search security findings returns "OK" response
    use datadog_api_client::datadog;
    use datadog_api_client::datadogV2::api_security_monitoring::SecurityMonitoringAPI;
    use datadog_api_client::datadogV2::model::SecurityFindingsSearchRequest;
    use datadog_api_client::datadogV2::model::SecurityFindingsSearchRequestData;
    use datadog_api_client::datadogV2::model::SecurityFindingsSearchRequestDataAttributes;
    
    #[tokio::main]
    async fn main() {
        let body = SecurityFindingsSearchRequest::new().data(
            SecurityFindingsSearchRequestData::new().attributes(
                SecurityFindingsSearchRequestDataAttributes::new()
                    .filter("@severity:(critical OR high)".to_string()),
            ),
        );
        let configuration = datadog::Configuration::new();
        let api = SecurityMonitoringAPI::with_config(configuration);
        let resp = api.search_security_findings(body).await;
        if let Ok(value) = resp {
            println!("{:#?}", value);
        } else {
            println!("{:#?}", resp.unwrap_err());
        }
    }
    
    // Search security findings returns "OK" response with pagination
    use datadog_api_client::datadog;
    use datadog_api_client::datadogV2::api_security_monitoring::SecurityMonitoringAPI;
    use datadog_api_client::datadogV2::model::SecurityFindingsSearchRequest;
    use datadog_api_client::datadogV2::model::SecurityFindingsSearchRequestData;
    use datadog_api_client::datadogV2::model::SecurityFindingsSearchRequestDataAttributes;
    use datadog_api_client::datadogV2::model::SecurityFindingsSearchRequestPage;
    
    #[tokio::main]
    async fn main() {
        let body = SecurityFindingsSearchRequest::new().data(
            SecurityFindingsSearchRequestData::new().attributes(
                SecurityFindingsSearchRequestDataAttributes::new()
                    .filter("@severity:(critical OR high)".to_string())
                    .page(SecurityFindingsSearchRequestPage::new().limit(1)),
            ),
        );
        let configuration = datadog::Configuration::new();
        let api = SecurityMonitoringAPI::with_config(configuration);
        let resp = api.search_security_findings(body).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
    /**
     * Search security findings returns "OK" response
     */
    
    import { client, v2 } from "@datadog/datadog-api-client";
    
    const configuration = client.createConfiguration();
    const apiInstance = new v2.SecurityMonitoringApi(configuration);
    
    const params: v2.SecurityMonitoringApiSearchSecurityFindingsRequest = {
      body: {
        data: {
          attributes: {
            filter: "@severity:(critical OR high)",
          },
        },
      },
    };
    
    apiInstance
      .searchSecurityFindings(params)
      .then((data: v2.ListSecurityFindingsResponse) => {
        console.log(
          "API called successfully. Returned data: " + JSON.stringify(data)
        );
      })
      .catch((error: any) => console.error(error));
    
    /**
     * Search security findings returns "OK" response with pagination
     */
    
    import { client, v2 } from "@datadog/datadog-api-client";
    
    const configuration = client.createConfiguration();
    const apiInstance = new v2.SecurityMonitoringApi(configuration);
    
    const params: v2.SecurityMonitoringApiSearchSecurityFindingsRequest = {
      body: {
        data: {
          attributes: {
            filter: "@severity:(critical OR high)",
            page: {
              limit: 1,
            },
          },
        },
      },
    };
    
    apiInstance
      .searchSecurityFindings(params)
      .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"