About dd-audit
dd-audit is a skill for investigating Datadog user activity, configuration changes, access patterns, and compliance records with pup audit-logs. It is intended for security, cost, and compliance reviews, with search guidance for actors, actions, assets, and network fields.
Key features
- 01List recent audit events
- 02Search events with query filters
- 03Investigate user and API key activity
- 04Review configuration and asset changes
- 05Collect compliance review evidence
Use cases
- 01Trace recent deletions or configuration changes
- 02Investigate suspicious API key activity
- 03Analyze an LLM cost or usage increase
- 04Compile SOC 2 or PCI audit records
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/dd-auditin Claude Code to confirm it loaded.
Bundled filescompliance-report/references/control-mapping.md
Details
From the project READMEDatadog 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:[email protected]" --from 7d -o json | jq '.data[].attributes'
Event Schema Quick Reference
| Field | Description | Example values |
|---|---|---|
@usr.email | Actor email | [email protected] |
@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:[email protected] | 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 |