Language

English Français 日本語 한국어 Español

Datadog Site

Site help
US1 US3 US5 EU AP1 AP2 US1-FED

Entity Risk Scores

Retrieves security risk scores for entities in your organization.

List Entity Risk Scores

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