当需要用 Datadog Audit Trail…

需要基于 Datadog Audit Trail 排查用户/密钥/AI 活动、生成合规证据或定位费用突增根因时使用。

适用场景

解决思路

1. 使用 `pup audit-logs` 调查用户活动、配置变更、访问模式和合规证据。
2. 按调查目标选择并执行对应子技能：security-investigation 用于“谁更改了 X？”、“这个用户做了什么？”、“显示最近 24h 的删除操作”；key-compromise 用于“这个 API key 是否被泄露？”、“key XYZ 做了什么？”、“调查可疑密钥活动”；cost-spike-investigation 用于“为什么我的账单上涨？”、“什么导致这次用量突增？”、“调查 LLM 成本增加”；compliance-report 用于“生成 SOC 2 证据”、“PCI 审计日志”、“给审计员的用户开通报告”；ai-activity-audit 用于“AI 助手做了什么？”、“审计 MCP 工具调用”、“AI 治理报告”。
3. 执行 `pup auth login` 进行 OAuth2 认证（推荐），或设置 `DD_API_KEY` + `DD_APP_KEY` 并具备 `audit_logs_read` scope。
4. 列出最近事件：`pup audit-logs list --from 1h --limit 100`。
5. 用查询搜索：`pup audit-logs search --query "@action:deleted" --from 24h`。
6. 输出 JSON 供 jq 处理：`pup audit-logs search --query "@usr.email:alice@example.com" --from 7d -o json | jq '.data[].attributes'`。
7. 按事件 schema 读取 `@usr.email`：操作者邮箱，例如 `alice@example.com`。
8. 按事件 schema 读取 `@evt.actor.type`：操作执行方式，示例值 `USER`、`API_KEY`、`SUPPORT_USER`。
9. 按事件 schema 读取 `@action`：动作，示例值 `created`、`modified`、`deleted`、`accessed`、`login`。
10. 按事件 schema 读取 `@evt.name`：事件类别，示例值 `Dashboard`、`Monitor`、`Authentication`、`Access Management`。
11. 按事件 schema 读取 `@asset.type`：资源类型，示例值 `dashboard`、`monitor`、`api_key`、`role`、`user`。
12. 按事件 schema 读取 `@asset.id`：资源标识符，示例值 `abc-123`。
13. 按事件 schema 读取 `@metadata.api_key.id`：使用的 API key（如适用），示例值 `key_abc123`。
14. 按事件 schema 读取 `@metadata.app_key.id`：使用的 App key（如适用），示例值 `app_abc123`。
15. 按事件 schema 读取 `@network.client.ip`：客户端 IP 地址，示例值 `1.2.3.4`。
16. 按事件 schema 读取 `@network.client.geoip.country.name`：国家，示例值 `United States`。
17. 按事件 schema 读取 `@network.client.geoip.as.name`：ASN 名称，示例值 `Amazon.com`。
18. 按事件 schema 读取 `@http.url_details.path`：API 端点路径，示例值 `/api/v1/dashboard/xyz`。
19. 使用搜索语法 `@evt.name:Dashboard` 做精确字段匹配。
20. 使用搜索语法 `@action:deleted` 做动作过滤。
21. 使用搜索语法 `@usr.email:alice@example.com` 指定用户。
22. 使用搜索语法 `@evt.name:Monitor AND @action:modified` 做复合查询。
23. 使用搜索语法 `-@action:deleted` 做取反。
24. 使用搜索语法 `@usr.email:*` 检查字段存在。
25. 使用搜索语法 `@network.client.ip:1.2.3.4` 做 IP 过滤。
26. 记住默认保留期为 90 天；如果查询超过 90 天，必须已配置归档到 S3/GCS/Azure Blob；运行查询前始终检查请求时间窗口是否落在保留期内。
27. 遇到 403 Forbidden：原因是缺少 `audit_logs_read` scope；修复方法是在 Datadog UI 中给 app key 添加该 scope。
28. 遇到空结果：原因是时间窗口超出保留期；检查归档配置，默认最大为 90 天。
29. 遇到超时：原因是查询过宽；收窄时间窗口或增加更多过滤条件。
30. 没有 IP 数据：原因是内部操作或预富集事件；并非所有事件都有 geo 数据。
31. 查阅参考：`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/）。

适用边界 · 注意事项

• 没有 Datadog Audit Trail、`pup` CLI、OAuth2 或具备 `audit_logs_read` scope 的 API/App key 时。
• 查询时间超出默认 90 天且未配置 S3/GCS/Azure Blob 归档时。
• 需要审计非 Datadog 管理的系统，或所需事件本身没有 IP/地理信息时。