List vulnerable assets

Note: This endpoint is a private preview. If you are interested in accessing this API, fill out this form.

GET https://api.ap1.datadoghq.com/api/v2/security/vulnerable-assetshttps://api.ap2.datadoghq.com/api/v2/security/vulnerable-assetshttps://api.datadoghq.eu/api/v2/security/vulnerable-assetshttps://api.ddog-gov.com/api/v2/security/vulnerable-assetshttps://api.us2.ddog-gov.com/api/v2/security/vulnerable-assetshttps://api.datadoghq.com/api/v2/security/vulnerable-assetshttps://api.us3.datadoghq.com/api/v2/security/vulnerable-assetshttps://api.us5.datadoghq.com/api/v2/security/vulnerable-assets

Overview

Get a list of vulnerable assets.

Pagination

Please review the Pagination section for the “List Vulnerabilities” endpoint.

Filtering

Please review the Filtering section for the “List Vulnerabilities” endpoint.

Metadata

Please review the Metadata section for the “List Vulnerabilities” endpoint.

This endpoint requires the appsec_vm_read permission.

Arguments

Query Strings

Name

Type

Description

page[token]

string

Its value must come from the links section of the response of the first request. Do not manually edit it.

page[number]

integer

The page number to be retrieved. It should be equal or greater than 1

filter[name]

string

Filter by name. This field supports the usage of wildcards (*).

filter[type]

enum

Filter by type.
Allowed enum values: Repository, Service, Host, HostImage, Image

filter[version.first]

string

Filter by the first version of the asset since it has been vulnerable.

filter[version.last]

string

Filter by the last detected version of the asset.

filter[repository_url]

string

Filter by the repository url associated to the asset.

filter[risks.in_production]

boolean

Filter whether the asset is in production or not.

filter[risks.under_attack]

boolean

Filter whether the asset (Service) is under attack or not.

filter[risks.is_publicly_accessible]

boolean

Filter whether the asset (Host) is publicly accessible or not.

filter[risks.has_privileged_access]

boolean

Filter whether the asset (Host) has privileged access or not.

filter[risks.has_access_to_sensitive_data]

boolean

Filter whether the asset (Host) has access to sensitive data or not.

filter[environments]

string

Filter by environment.

filter[teams]

string

Filter by teams.

filter[arch]

string

Filter by architecture.

filter[operating_system.name]

string

Filter by operating system name.

filter[operating_system.version]

string

Filter by operating system version.

Response

OK

The expected response schema when listing vulnerable assets.

Expand All

Field

Type

Description

data [required]

[object]

List of vulnerable assets.

attributes [required]

object

The JSON:API attributes of the asset.

arch

string

Asset architecture.

environments [required]

[string]

List of environments where the asset is deployed.

name [required]

string

Asset name.

operating_system

object

Asset operating system.

description

string

Operating system version.

name [required]

string

Operating system name.

risks [required]

object

Asset risks.

has_access_to_sensitive_data

boolean

Whether the asset has access to sensitive data or not.

has_privileged_access

boolean

Whether the asset has privileged access or not.

in_production [required]

boolean

Whether the asset is in production or not.

is_publicly_accessible

boolean

Whether the asset is publicly accessible or not.

under_attack

boolean

Whether the asset is under attack or not.

teams

[string]

List of teams that own the asset.

type [required]

enum

The asset type Allowed enum values: Repository,Service,Host,HostImage,Image

version

object

Asset version.

first

string

Asset first version.

last

string

Asset last version.

id [required]

string

The unique ID for this asset.

type [required]

enum

The JSON:API type. Allowed enum values: assets

links

object

The JSON:API links related to pagination.

first [required]

string

First page link.

last [required]

string

Last page link.

next

string

Next page link.

previous

string

Previous page link.

self [required]

string

Request link.

meta

object

The metadata related to this request.

count [required]

int64

Number of entities included in the response.

token [required]

string

The token that identifies the request.

total [required]

int64

Total number of entities across all pages.

{
  "data": [
    {
      "attributes": {
        "arch": "arm64",
        "environments": [
          "staging"
        ],
        "name": "github.com/DataDog/datadog-agent.git",
        "operating_system": {
          "description": "24.04",
          "name": "ubuntu"
        },
        "risks": {
          "has_access_to_sensitive_data": false,
          "has_privileged_access": false,
          "in_production": false,
          "is_publicly_accessible": false,
          "under_attack": false
        },
        "teams": [
          "compute"
        ],
        "type": "Repository",
        "version": {
          "first": "_latest",
          "last": "_latest"
        }
      },
      "id": "Repository|github.com/DataDog/datadog-agent.git",
      "type": "assets"
    }
  ],
  "links": {
    "first": "https://api.datadoghq.com/api/v2/security/vulnerabilities?page%5Bnumber%5D=1\u0026page%5Btoken%5D=b82cef018aab81ed1d4bb4xb35xxfc065da7efa685fbcecdbd338f3015e3afabbbfa3a911b4984_721ee28a-zecb-4e45-9960-c42065b574f4",
    "last": "https://api.datadoghq.com/api/v2/security/vulnerabilities?page%5Bnumber%5D=15\u0026page%5Btoken%5D=b82cef018aab81ed1d4bb4xb35xxfc065da7efa685fbcecdbd338f3015e3afabbbfa3a911b4984_721ee28a-zecb-4e45-9960-c42065b574f4",
    "next": "https://api.datadoghq.com/api/v2/security/vulnerabilities?page%5Bnumber%5D=16\u0026page%5Btoken%5D=b82cef018aab81ed1d4bb4xb35xxfc065da7efa685fbcecdbd338f3015e3afabbbfa3a911b4984_721ee28a-zecb-4e45-9960-c42065b574f4",
    "previous": "https://api.datadoghq.com/api/v2/security/vulnerabilities?page%5Bnumber%5D=14\u0026page%5Btoken%5D=b82cef018aab81ed1d4bb4xb35xxfc065da7efa685fbcecdbd338f3015e3afabbbfa3a911b4984_721ee28a-zecb-4e45-9960-c42065b574f4",
    "self": "https://api.datadoghq.com/api/v2/security/vulnerabilities?filter%5Btool%5D=Infra"
  },
  "meta": {
    "count": 150,
    "token": "b82cef018aab81ed1d4bb4xb35xxfc065da7efa685fbcecdbd338f3015e3afabbbfa3a911b4984_721ee28a-zecb-4e45-9960-c42065b574f4",
    "total": 152431
  }
}

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

API error response.

Expand All

Field

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

Field

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: There is no request associated with the provided token.

API error response.

Expand All

Field

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

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/vulnerable-assets" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
"""
List vulnerable assets 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.asset_type import AssetType

configuration = Configuration()
configuration.unstable_operations["list_vulnerable_assets"] = True
with ApiClient(configuration) as api_client:
    api_instance = SecurityMonitoringApi(api_client)
    response = api_instance.list_vulnerable_assets(
        filter_type=AssetType.HOST,
        filter_repository_url="github.com/datadog/dd-go",
        filter_risks_in_production=True,
    )

    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 vulnerable assets returns "OK" response

require "datadog_api_client"
DatadogAPIClient.configure do |config|
  config.unstable_operations["v2.list_vulnerable_assets".to_sym] = true
end
api_instance = DatadogAPIClient::V2::SecurityMonitoringAPI.new
opts = {
  filter_type: AssetType::HOST,
  filter_repository_url: "github.com/datadog/dd-go",
  filter_risks_in_production: true,
}
p api_instance.list_vulnerable_assets(opts)

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 vulnerable assets 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.ListVulnerableAssets", true)
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewSecurityMonitoringApi(apiClient)
	resp, r, err := api.ListVulnerableAssets(ctx, *datadogV2.NewListVulnerableAssetsOptionalParameters().WithFilterType(datadogV2.ASSETTYPE_HOST).WithFilterRepositoryUrl("github.com/datadog/dd-go").WithFilterRisksInProduction(true))

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

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `SecurityMonitoringApi.ListVulnerableAssets`:\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 vulnerable assets 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.api.SecurityMonitoringApi.ListVulnerableAssetsOptionalParameters;
import com.datadog.api.client.v2.model.AssetType;
import com.datadog.api.client.v2.model.ListVulnerableAssetsResponse;

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

    try {
      ListVulnerableAssetsResponse result =
          apiInstance.listVulnerableAssets(
              new ListVulnerableAssetsOptionalParameters()
                  .filterType(AssetType.HOST)
                  .filterRepositoryUrl("github.com/datadog/dd-go")
                  .filterRisksInProduction(true));
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling SecurityMonitoringApi#listVulnerableAssets");
      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 vulnerable assets returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_security_monitoring::ListVulnerableAssetsOptionalParams;
use datadog_api_client::datadogV2::api_security_monitoring::SecurityMonitoringAPI;
use datadog_api_client::datadogV2::model::AssetType;

#[tokio::main]
async fn main() {
    let mut configuration = datadog::Configuration::new();
    configuration.set_unstable_operation_enabled("v2.ListVulnerableAssets", true);
    let api = SecurityMonitoringAPI::with_config(configuration);
    let resp = api
        .list_vulnerable_assets(
            ListVulnerableAssetsOptionalParams::default()
                .filter_type(AssetType::HOST)
                .filter_repository_url("github.com/datadog/dd-go".to_string())
                .filter_risks_in_production(true),
        )
        .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 vulnerable assets returns "OK" response
 */

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

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

const params: v2.SecurityMonitoringApiListVulnerableAssetsRequest = {
  filterType: "Host",
  filterRepositoryUrl: "github.com/datadog/dd-go",
  filterRisksInProduction: true,
};

apiInstance
  .listVulnerableAssets(params)
  .then((data: v2.ListVulnerableAssetsResponse) => {
    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"