Skip to content

Add risk-scores entityID spec #3617

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
api-clients-generation-pipeline merged 1 commit into from
Jun 2, 2026
Merged

Add risk-scores entityID spec #3617

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
191 changes: 159 additions & 32 deletions .generator/schemas/v2/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76116,73 +76116,90 @@ components:
- attributes
type: object
SecurityEntityRiskScoreAttributes:
description: Attributes of an entity risk score
description: Attributes of an entity risk score.
properties:
accountIds:
description: Cloud account IDs associated with the entity.
example: ["222233334444", "3333333555555"]
items:
description: A cloud account ID.
type: string
type: array
configRisks:
$ref: "#/components/schemas/SecurityEntityConfigRisks"
entityID:
description: Unique identifier for the entity
example: "arn:aws:iam::123456789012:user/john.doe"
type: string
entityMetadata:
$ref: "#/components/schemas/SecurityEntityMetadata"
entityName:
description: Human-readable name of the entity
description: Human-readable name of the entity.
example: "john.doe"
type: string
entityProviders:
description: Cloud providers associated with the entity
example: ["aws"]
description: Cloud providers associated with the entity.
example: ["AWS"]
items:
description: A cloud provider name.
type: string
type: array
entityRoles:
description: Roles associated with the entity
example: ["Admin", "Developer"]
description: Roles associated with the entity.
example: []
items:
description: A role assigned to the entity.
type: string
type: array
entitySubTypes:
description: Sub-types associated with the entity.
example: ["Root"]
items:
description: An entity sub-type label.
type: string
type: array
entityType:
description: Type of the entity (e.g., aws_iam_user, aws_ec2_instance)
description: Type of the entity (for example, aws_iam_user, aws_ec2_instance).
example: "aws_iam_user"
type: string
entityTypes:
description: All types associated with the entity.
example: ["Root", "User Name"]
items:
description: An entity type label.
type: string
type: array
firstDetected:
description: Timestamp when the entity was first detected (Unix milliseconds)
example: 1704067200000
description: Timestamp when the entity was first detected (Unix milliseconds).
example: 1778876604661
format: int64
type: integer
lastActivityTitle:
description: Title of the most recent signal detected for this entity
description: Title of the most recent signal detected for this entity.
example: "Suspicious API call detected"
type: string
lastDetected:
description: Timestamp when the entity was last detected (Unix milliseconds)
example: 1705276800000
description: Timestamp when the entity was last detected (Unix milliseconds).
example: 1780064607093
format: int64
type: integer
riskScore:
description: Current risk score for the entity
description: Current risk score for the entity.
example: 85
format: int64
type: integer
riskScoreEvolution:
description: Change in risk score compared to previous period
description: Change in risk score compared to previous period.
example: 12
format: int64
type: integer
severity:
$ref: "#/components/schemas/SecurityEntityRiskScoreAttributesSeverity"
signalsDetected:
description: Number of security signals detected for this entity
description: Number of security signals detected for this entity.
example: 15
format: int64
type: integer
required:
- entityID
- entityType
- entityProviders
- entitySubTypes
- accountIds
- riskScore
- riskScoreEvolution
- severity
Expand All @@ -76209,11 +76226,19 @@ components:
- MEDIUM
- LOW
- INFO
SecurityEntityRiskScoreResponse:
description: Response containing a single entity risk score
properties:
data:
$ref: "#/components/schemas/SecurityEntityRiskScore"
required:
- data
type: object
SecurityEntityRiskScoreType:
description: Resource type
description: Resource type.
enum:
- security_entity_risk_score
example: security_entity_risk_score
- SecurityEntityRiskScore
example: SecurityEntityRiskScore
type: string
x-enum-varnames:
- SECURITY_ENTITY_RISK_SCORE
Expand Down Expand Up @@ -153097,28 +153122,34 @@ paths:
value:
data:
- attributes:
accountIds:
- "123456789012"
configRisks:
hasIdentityRisk: false
hasMisconfiguration: true
hasPrivilegedRole: false
isPrivileged: false
isProduction: true
isPubliclyAccessible: true
entityID: "arn:aws:iam::123456789012:user/test-user"
entityMetadata:
environments:
- production
mitreTactics: []
mitreTechniques: []
mitreTactics:
- ta0006-credential-access
mitreTechniques:
- t1078-valid-accounts
services:
- api-gateway
sources:
- cloudtrail
entityName: test-user
entityProviders:
- aws
- AWS
entityRoles: []
entityType: aws_iam_user
entitySubTypes:
- "IAM User"
entityTypes:
- "IAMUser"
firstDetected: 1704067200000
lastActivityTitle: "Suspicious API call detected"
lastDetected: 1705276800000
Expand All @@ -153127,10 +153158,12 @@ paths:
severity: critical
signalsDetected: 15
id: "arn:aws:iam::123456789012:user/test-user"
type: security_entity_risk_score
type: SecurityEntityRiskScore
meta:
page:
total: 1
pageNumber: 1
pageSize: 10
queryId: "abc123def456"
totalRowCount: 1
schema:
$ref: "#/components/schemas/SecurityEntityRiskScoresResponse"
description: OK
Expand Down Expand Up @@ -153160,6 +153193,100 @@ paths:
x-unstable: |-
**Note**: This endpoint is in public beta and it's subject to change.
If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
/api/v2/security-entities/risk-scores/{entity_id}:
get:
description: |-
Get the risk score for a specific entity by its ID. Returns security risk assessment including risk score, severity, detected signals, misconfigurations, and identity risks.
operationId: GetEntityRiskScore
parameters:
- description: The URL-encoded unique identifier for the entity.
in: path
name: entity_id
required: true
schema:
example: "arn:aws:iam::123456789012:user/john.doe"
type: string
responses:
"200":
content:
application/json:
examples:
default:
value:
data:
attributes:
accountIds:
- "123456789012"
configRisks:
hasIdentityRisk: false
hasMisconfiguration: true
hasPrivilegedRole: false
isPrivileged: false
isProduction: true
isPubliclyAccessible: true
entityMetadata:
environments:
- production
mitreTactics:
- ta0006-credential-access
mitreTechniques:
- t1078-valid-accounts
services:
- api-gateway
sources:
- cloudtrail
entityName: "test-user"
entityProviders:
- AWS
entityRoles: []
entitySubTypes:
- "IAM User"
entityTypes:
- "IAMUser"
firstDetected: 1704067200000
lastActivityTitle: "Suspicious API call detected"
lastDetected: 1705276800000
riskScore: 85
riskScoreEvolution: 12
severity: critical
signalsDetected: 15
id: "arn:aws:iam::123456789012:user/test-user"
type: SecurityEntityRiskScore
schema:
$ref: "#/components/schemas/SecurityEntityRiskScoreResponse"
description: OK
"400":
content:
application/json:
schema:
$ref: "#/components/schemas/JSONAPIErrorResponse"
description: Bad Request
"401":
content:
application/json:
schema:
$ref: "#/components/schemas/JSONAPIErrorResponse"
description: Unauthorized
"403":
content:
application/json:
schema:
$ref: "#/components/schemas/JSONAPIErrorResponse"
description: Forbidden
"404":
content:
application/json:
schema:
$ref: "#/components/schemas/JSONAPIErrorResponse"
description: Not Found
"429":
$ref: "#/components/responses/TooManyRequestsResponse"
summary: Get Entity Risk Score
tags:
- Entity Risk Scores
x-unstable: |-
**Note**: This endpoint is in public beta and it's subject to change.
If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
/api/v2/security/cloud_workload/policy/download:
get:
description: |-
Expand Down
7 changes: 7 additions & 0 deletions docs/datadog_api_client.v2.model.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32946,6 +32946,13 @@ datadog\_api\_client.v2.model.security\_entity\_risk\_score\_attributes\_severit
:members:
:show-inheritance:

datadog\_api\_client.v2.model.security\_entity\_risk\_score\_response module
----------------------------------------------------------------------------

.. automodule:: datadog_api_client.v2.model.security_entity_risk_score_response
:members:
:show-inheritance:

datadog\_api\_client.v2.model.security\_entity\_risk\_score\_type module
------------------------------------------------------------------------

Expand Down
16 changes: 16 additions & 0 deletions examples/v2/entity-risk-scores/GetEntityRiskScore.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
"""
Get Entity Risk Score 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["get_entity_risk_score"] = True
with ApiClient(configuration) as api_client:
api_instance = EntityRiskScoresApi(api_client)
response = api_instance.get_entity_risk_score(
entity_id="arn:aws:iam::123456789012:user/john.doe",
)

print(response)
1 change: 1 addition & 0 deletions src/datadog_api_client/configuration.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -629,6 +629,7 @@ def __init__(
"v2.query_aggregated_signals_problems": False,
"v2.query_aggregated_waterfall": False,
"v2.create_scorecard_outcomes_batch": False,
"v2.get_entity_risk_score": False,
"v2.list_entity_risk_scores": False,
"v2.create_incident_service": False,
"v2.delete_incident_service": False,
Expand Down
41 changes: 41 additions & 0 deletions src/datadog_api_client/v2/api/entity_risk_scores_api.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
unset,
)
from datadog_api_client.v2.model.security_entity_risk_scores_response import SecurityEntityRiskScoresResponse
from datadog_api_client.v2.model.security_entity_risk_score_response import SecurityEntityRiskScoreResponse


class EntityRiskScoresApi:
Expand All @@ -24,6 +25,29 @@ def __init__(self, api_client=None):
api_client = ApiClient(Configuration())
self.api_client = api_client

self._get_entity_risk_score_endpoint = _Endpoint(
settings={
"response_type": (SecurityEntityRiskScoreResponse,),
"auth": ["apiKeyAuth", "appKeyAuth"],
"endpoint_path": "/api/v2/security-entities/risk-scores/{entity_id}",
"operation_id": "get_entity_risk_score",
"http_method": "GET",
"version": "v2",
},
params_map={
"entity_id": {
"required": True,
"openapi_types": (str,),
"attribute": "entity_id",
"location": "path",
},
},
headers_map={
"accept": ["application/json"],
},
api_client=api_client,
)

self._list_entity_risk_scores_endpoint = _Endpoint(
settings={
"response_type": (SecurityEntityRiskScoresResponse,),
Expand Down Expand Up @@ -82,6 +106,23 @@ def __init__(self, api_client=None):
api_client=api_client,
)

def get_entity_risk_score(
self,
entity_id: str,
) -> SecurityEntityRiskScoreResponse:
"""Get Entity Risk Score.

Get the risk score for a specific entity by its ID. Returns security risk assessment including risk score, severity, detected signals, misconfigurations, and identity risks.

:param entity_id: The URL-encoded unique identifier for the entity.
:type entity_id: str
:rtype: SecurityEntityRiskScoreResponse
"""
kwargs: Dict[str, Any] = {}
kwargs["entity_id"] = entity_id

return self._get_entity_risk_score_endpoint.call_with_http_info(**kwargs)

def list_entity_risk_scores(
self,
*,
Expand Down
Loading
Loading