Skip to content
Datadog Audit Trail

Datadog Audit Trail

by Datadog
v0.1.0
MIT
Repository Docs
markdown Development
datadogaudit-trailsecuritycompliancesoc2forensicsai-governance

Summary

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.

Features

  • 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

Install This Skill

Add this skill to your favorite AI agent in a few steps.

Any AI agent

This skill is plain instructions — it works with any assistant that accepts custom instructions or system prompts.

  1. Copy the skill content with the button below.
  2. Paste it into your agent's instruction file or system prompt (for example AGENTS.md, .cursorrules, or a custom instructions field).
  3. Ask the agent to apply the skill whenever the task matches.

Skill Content

Markdown Content

Copy this content and use it with your preferred AI agent

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

```bash
pup auth login   # OAuth2 (recommended)
# or set DD_API_KEY + DD_APP_KEY with audit_logs_read scope
```

## Commands

```bash
# 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

- [Audit Trail API](https://docs.datadoghq.com/api/latest/audit/)
- [Audit Trail documentation](https://docs.datadoghq.com/account_management/audit_trail/)
- [Search syntax](https://docs.datadoghq.com/logs/explorer/search_syntax/)

Usage Instructions

Learn how to use this skill with different AI agents.

Generic Instructions

Install the pup CLI, authenticate, then add the skill:

brew tap datadog-labs/pack
brew install datadog-labs/pack/pup
pup auth login

npx skills add datadog-labs/agent-skills --skill dd-audit --full-depth -y

dd-pup is the base skill the others assume; add it alongside any of them:

npx skills add datadog-labs/agent-skills --skill dd-pup --skill dd-audit --full-depth -y

Description

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.

Related Skills

Skill: Auth0 Agent Skill

by Auth0

New

Auth0's official agent skill: a router that detects your framework and intent, then loads the right Auth0 guidance for login, MFA, Organizations, tenant audits, debugging or provider migration.

Development

Skill: Redis Search

by Redis, Inc.

New

Redis' own guidance for FT.CREATE schema design, FT.SEARCH / FT.AGGREGATE / FT.HYBRID, HNSW vector similarity and RAG retrieval pipelines.

Development

Skill: Supabase

by Supabase

New

Supabase's official skill covering Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron and Queues — with a hard rule to verify against the live changelog before writing code.

Development

Skill: GSAP ScrollTrigger

by GreenSock

New

GreenSock's official ScrollTrigger skill — scroll-linked animation, pinning, scrub and trigger positioning, with the exact start/end syntax agents get wrong.

DevelopmentDesign & Creative
1 views
Browse all skills →