name: dd-audit
description: Audit Trail investigations - who changed what, key compromise, cost spike root cause, compliance evidence (SOC 2/PCI), and AI activity auditing.
metadata:
version: "0.1.0"
author: datadog-labs
repository: https://github.com/datadog-labs/agent-skills
tags: datadog,audit,audit-trail,security,compliance,dd-audit
alwaysApply: "false"
Datadog Audit Trail
Investigate user activity, configuration changes, access patterns, and compliance evidence using pup audit-logs.
Sub-Skills
| Sub-skill |
Use when |
| security-investigation |
"Who changed X?", "What did this user do?", "Show me deletions in the last 24h" |
| key-compromise |
"Was this API key compromised?", "What did key XYZ do?", "Investigate suspicious key activity" |
| cost-spike-investigation |
"Why did my bill go up?", "What caused this usage spike?", "Investigate LLM cost increase" |
| compliance-report |
"Generate SOC 2 evidence", "PCI audit log", "User provisioning report for auditor" |
| ai-activity-audit |
"What did the AI assistant do?", "Audit MCP tool calls", "AI governance report" |
Prerequisites
pup auth login # OAuth2 (recommended)
# or set DD_API_KEY + DD_APP_KEY with audit_logs_read scope
Commands
# List recent events
pup audit-logs list --from 1h --limit 100
# Search with a query
pup audit-logs search --query "@action:deleted" --from 24h
# JSON output for piping to jq
pup audit-logs search --query "@usr.email:alice@example.com" --from 7d -o json | jq '.data[].attributes'
Event Schema Quick Reference
| Field |
Description |
Example values |
@usr.email |
Actor email |
alice@example.com |
@evt.actor.type |
How action was taken |
USER, API_KEY, SUPPORT_USER |
@action |
Verb |
created, modified, deleted, accessed, login |
@evt.name |
Event category |
Dashboard, Monitor, Authentication, Access Management |
@asset.type |
Resource type |
dashboard, monitor, api_key, role, user |
@asset.id |
Resource identifier |
abc-123 |
@metadata.api_key.id |
API key used (if applicable) |
key_abc123 |
@metadata.app_key.id |
App key used (if applicable) |
app_abc123 |
@network.client.ip |
Client IP address |
1.2.3.4 |
@network.client.geoip.country.name |
Country |
United States |
@network.client.geoip.as.name |
ASN name |
Amazon.com |
@http.url_details.path |
API endpoint path |
/api/v1/dashboard/xyz |
Search Syntax
Same Lucene-style syntax as Log Explorer:
| Query |
Meaning |
@evt.name:Dashboard |
Exact field match |
@action:deleted |
Action filter |
@usr.email:alice@example.com |
Specific user |
@evt.name:Monitor AND @action:modified |
Compound |
-@action:deleted |
Negation |
@usr.email:* |
Field exists |
@network.client.ip:1.2.3.4 |
IP filter |
Retention
Default retention is 90 days. If querying beyond 90 days, archive to S3/GCS/Azure Blob must be configured. Always check whether the requested time window falls within retention before running a query.
Troubleshooting
| Problem |
Cause |
Fix |
| 403 Forbidden |
Missing audit_logs_read scope |
Add scope to app key in Datadog UI |
| Empty results |
Time window outside retention |
Check archive config; default max is 90 days |
| Timeout |
Query too broad |
Narrow time window or add more filters |
| No IP data |
Internal action or pre-enrichment event |
Not all events have geo data |
References
By