Entity Risk Scores

Retrieves security risk scores for entities in your organization.

Note: This endpoint is in public beta and it’s subject to change. If you have any feedback, contact Datadog support.

GET https://api.ap1.datadoghq.com/api/v2/security-entities/risk-scoreshttps://api.ap2.datadoghq.com/api/v2/security-entities/risk-scoreshttps://api.datadoghq.eu/api/v2/security-entities/risk-scoreshttps://api.ddog-gov.com/api/v2/security-entities/risk-scoreshttps://api.datadoghq.com/api/v2/security-entities/risk-scoreshttps://api.us3.datadoghq.com/api/v2/security-entities/risk-scoreshttps://api.us5.datadoghq.com/api/v2/security-entities/risk-scores

Overview

Get a list of entity risk scores for your organization. Entity risk scores provide security risk assessment for entities like cloud resources, identities, or services based on detected signals, misconfigurations, and identity risks.

Arguments

Query Strings

Name

Type

Description

from

integer

Start time for the query in Unix timestamp (milliseconds). Defaults to 2 weeks ago.

to

integer

End time for the query in Unix timestamp (milliseconds). Defaults to now.

page[size]

integer

Size of the page to return. Maximum is 1000.

page[number]

integer

Page number to return (1-indexed).

page[queryId]

string

Query ID for pagination consistency.

filter[sort]

string

Sort order for results. Format: field:direction where direction is asc or desc. Supported fields: riskScore, lastDetected, firstDetected, entityName, signalsDetected.

filter[query]

string

Supports filtering by entity attributes, risk scores, severity, and more. Example: severity:critical AND entityType:aws_iam_user

entityType

array

Filter by entity type(s). Can specify multiple values.

Response

OK

Response containing a list of entity risk scores

Expand All

Field

Type

Description

data [required]

[object]

attributes [required]

object

Attributes of an entity risk score

configRisks [required]

object

Configuration risks associated with the entity

hasIdentityRisk [required]

boolean

Whether the entity has identity risks

hasMisconfiguration [required]

boolean

Whether the entity has misconfigurations

hasPrivilegedRole [required]

boolean

Whether the entity has privileged roles

isPrivileged [required]

boolean

Whether the entity has privileged access

isProduction [required]

boolean

Whether the entity is in a production environment

isPubliclyAccessible [required]

boolean

Whether the entity is publicly accessible

entityID [required]

string

Unique identifier for the entity

entityMetadata [required]

object

Metadata about the entity from cloud providers

accountID

string

Cloud account ID (AWS)

environments [required]

[string]

Environment tags associated with the entity

mitreTactics [required]

[string]

MITRE ATT&CK tactics detected

mitreTechniques [required]

[string]

MITRE ATT&CK techniques detected

projectID

string

Cloud project ID (GCP)

services [required]

[string]

Services associated with the entity

sources [required]

[string]

Data sources that detected this entity

subscriptionID

string

Cloud subscription ID (Azure)

entityName

string

Human-readable name of the entity

entityProviders [required]

[string]

Cloud providers associated with the entity

entityRoles

[string]

Roles associated with the entity

entityType [required]

string

Type of the entity (e.g., aws_iam_user, aws_ec2_instance)

firstDetected [required]

int64

Timestamp when the entity was first detected (Unix milliseconds)

lastActivityTitle [required]

string

Title of the most recent signal detected for this entity

lastDetected [required]

int64

Timestamp when the entity was last detected (Unix milliseconds)

riskScore [required]

double

Current risk score for the entity

riskScoreEvolution [required]

double

Change in risk score compared to previous period

severity [required]

enum

Severity level based on risk score Allowed enum values: critical,high,medium,low,info

signalsDetected [required]

int64

Number of security signals detected for this entity

id [required]

string

Unique identifier for the entity

type [required]

enum

Resource type Allowed enum values: security_entity_risk_score

meta [required]

object

Metadata for pagination

pageNumber [required]

int64

Current page number (1-indexed)

pageSize [required]

int64

Number of items per page

queryId [required]

string

Query ID for pagination consistency

totalRowCount [required]

int64

Total number of entities matching the query

{
  "data": [
    {
      "attributes": {
        "configRisks": {
          "hasIdentityRisk": false,
          "hasMisconfiguration": true,
          "hasPrivilegedRole": true,
          "isPrivileged": false,
          "isProduction": true,
          "isPubliclyAccessible": true
        },
        "entityID": "arn:aws:iam::123456789012:user/john.doe",
        "entityMetadata": {
          "accountID": "123456789012",
          "environments": [
            "production",
            "us-east-1"
          ],
          "mitreTactics": [
            "Credential Access",
            "Privilege Escalation"
          ],
          "mitreTechniques": [
            "T1078",
            "T1098"
          ],
          "projectID": "my-gcp-project",
          "services": [
            "api-gateway",
            "lambda"
          ],
          "sources": [
            "cloudtrail",
            "cloud-security-posture-management"
          ],
          "subscriptionID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        },
        "entityName": "john.doe",
        "entityProviders": [
          "aws"
        ],
        "entityRoles": [
          "Admin",
          "Developer"
        ],
        "entityType": "aws_iam_user",
        "firstDetected": 1704067200000,
        "lastActivityTitle": "Suspicious API call detected",
        "lastDetected": 1705276800000,
        "riskScore": 85.5,
        "riskScoreEvolution": 12.3,
        "severity": "critical",
        "signalsDetected": 15
      },
      "id": "arn:aws:iam::123456789012:user/john.doe",
      "type": "security_entity_risk_score"
    }
  ],
  "meta": {
    "pageNumber": 1,
    "pageSize": 10,
    "queryId": "abc123def456",
    "totalRowCount": 150
  }
}

Bad 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"
    }
  ]
}

Unauthorized

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

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.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/security-entities/risk-scores" \ -H "Accept: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}"
"""
List Entity Risk Scores returns "OK" response
"""

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.entity_risk_scores_api import EntityRiskScoresApi

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

    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.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" python3 "example.py"
# List Entity Risk Scores returns "OK" response

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

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.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" rb "example.rb"
// List Entity Risk Scores 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.ListEntityRiskScores", true)
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewEntityRiskScoresApi(apiClient)
	resp, r, err := api.ListEntityRiskScores(ctx, *datadogV2.NewListEntityRiskScoresOptionalParameters())

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

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `EntityRiskScoresApi.ListEntityRiskScores`:\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.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" go run "main.go"
// List Entity Risk Scores returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.EntityRiskScoresApi;
import com.datadog.api.client.v2.model.SecurityEntityRiskScoresResponse;

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

    try {
      SecurityEntityRiskScoresResponse result = apiInstance.listEntityRiskScores();
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling EntityRiskScoresApi#listEntityRiskScores");
      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.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" java "Example.java"
// List Entity Risk Scores returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_entity_risk_scores::EntityRiskScoresAPI;
use datadog_api_client::datadogV2::api_entity_risk_scores::ListEntityRiskScoresOptionalParams;

#[tokio::main]
async fn main() {
    let mut configuration = datadog::Configuration::new();
    configuration.set_unstable_operation_enabled("v2.ListEntityRiskScores", true);
    let api = EntityRiskScoresAPI::with_config(configuration);
    let resp = api
        .list_entity_risk_scores(ListEntityRiskScoresOptionalParams::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.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" cargo run
/**
 * List Entity Risk Scores returns "OK" response
 */

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

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

apiInstance
  .listEntityRiskScores()
  .then((data: v2.SecurityEntityRiskScoresResponse) => {
    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.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" tsc "example.ts"