Skip to content
Datadog Audit Trail

Datadog Audit Trail Skill

by Datadog datadog-labs/agent-skills dd-audit

Answer "who changed what" from Datadog Audit Trail — configuration-change forensics, API key compromise, cost-spike root cause, SOC 2/PCI evidence and AI activity audits.

GitHub Docs
DevOps & InfrastructureSecurity
Added to Onei
v0.1.0
MIT

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from datadog-labs/agent-skills.

$ npx skills add datadog-labs/agent-skills --skill dd-audit

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

Copy the whole skill folder — SKILL.md and any scripts or references beside it — into ~/.claude/skills/dd-audit/, where Claude Code picks it up in every project. Only git is needed.

tmp=$(mktemp -d) && \
  git clone --depth 1 --branch main https://github.com/datadog-labs/agent-skills.git "$tmp" && \
  mkdir -p ~/.claude/skills && \
  cp -R "$tmp"/dd-audit ~/.claude/skills/dd-audit

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/dd-audit/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/
Open folder on GitHub

About

  • Five routed workflows: security, key compromise, cost spike, compliance, AI activity
  • Full Audit Trail event-schema field reference
  • Lucene-style search syntax with negation and field-existence forms
  • Retention checking before querying beyond 90 days
  • Audits MCP tool calls and AI assistant activity for governance reporting
  • Maps the audit_logs_read scope 403 to its fix

When a dashboard vanishes, a bill jumps, or a key looks compromised, the answer is in Audit Trail — and the query is rarely obvious. This official Datadog skill turns those investigations into structured workflows over pup audit-logs, and it is the most security-flavoured entry in Datadog's skill collection.

Five investigation shapes

The skill routes to a sub-skill by the shape of the question. Security investigation handles "who changed X", "what did this user do", "show me deletions in the last 24 hours". Key compromise traces everything a specific API key did. Cost-spike investigation works backwards from a usage or LLM-cost increase to the configuration change that caused it. Compliance reporting produces SOC 2 and PCI evidence and user-provisioning reports in the form an auditor expects. AI activity audit is the newest of the five — auditing what an AI assistant did, including MCP tool calls, for AI governance reporting.

The field reference is the useful part

Audit Trail queries fail mostly because the field names are not guessable, so the skill tabulates them: @usr.email for the actor, @evt.actor.type to distinguish a human from an API key from Datadog support, @action for the verb, @evt.name for the event category, @asset.type and @asset.id for the resource, @metadata.api_key.id and @metadata.app_key.id for the credential used, and the @network.client.* family for IP, country and ASN. Search syntax is the same Lucene-style grammar as Log Explorer, with negation and field-existence forms documented.

Two constraints it makes you check first

Audit Trail retention defaults to 90 days, and the skill instructs the agent to verify the requested window falls inside retention before running anything — beyond that, an archive to S3, GCS or Azure Blob has to already be configured. Access needs the audit_logs_read scope; a 403 means that scope is missing from the app key, which is the single most common failure and is called out as such.

Authenticates via pup auth login (OAuth2, recommended) or DD_API_KEY plus DD_APP_KEY. MIT-licensed, published by Datadog Labs.

SKILL.md

The instructions your agent loads, as published by Datadog.

SKILL.md
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-skillUse 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
FieldDescriptionExample values
@usr.emailActor emailalice@example.com
@evt.actor.typeHow action was takenUSER, API_KEY, SUPPORT_USER
@actionVerbcreated, modified, deleted, accessed, login
@evt.nameEvent categoryDashboard, Monitor, Authentication, Access Management
@asset.typeResource typedashboard, monitor, api_key, role, user
@asset.idResource identifierabc-123
@metadata.api_key.idAPI key used (if applicable)key_abc123
@metadata.app_key.idApp key used (if applicable)app_abc123
@network.client.ipClient IP address1.2.3.4
@network.client.geoip.country.nameCountryUnited States
@network.client.geoip.as.nameASN nameAmazon.com
@http.url_details.pathAPI endpoint path/api/v1/dashboard/xyz
Search Syntax

Same Lucene-style syntax as Log Explorer:

QueryMeaning
@evt.name:DashboardExact field match
@action:deletedAction filter
@usr.email:alice@example.comSpecific user
@evt.name:Monitor AND @action:modifiedCompound
-@action:deletedNegation
@usr.email:*Field exists
@network.client.ip:1.2.3.4IP 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
ProblemCauseFix
403 ForbiddenMissing audit_logs_read scopeAdd scope to app key in Datadog UI
Empty resultsTime window outside retentionCheck archive config; default max is 90 days
TimeoutQuery too broadNarrow time window or add more filters
No IP dataInternal action or pre-enrichment eventNot all events have geo data
References
Install

Related Skills

See all Datadog Audit Trail alternatives

Skill: NVIDIA Skill Card Generator

by NVIDIA

Generates or refreshes an NVIDIA governance skill card for an existing agent skill — discovers assets, renders a deterministic markdown card, and blocks submission while human-review markers remain.

Development

Skill: SAIL — Secure AI Lifecycle

by Pillar Security

Pillar Security's SAIL V2 framework as an agent skill: a 91-risk catalogue across seven lifecycle phases, for AI security gap assessments, roadmaps, and ISO 42001 / EU AI Act compliance checklists.

Security

Skill: Supply Chain Risk Auditor

by Trail of Bits

Audits npm, PyPI and Go dependencies for advisories, abandoned upstreams, publisher concentration and install-time scripts — measured by scripts, not estimated.

Security
Browse all skills →