dd-audit

用途

本技能用于基于 Datadog Audit Trail 开展审计调查，覆盖用户活动、配置变更、访问模式与合规证据的查询。核心操作方式是使用命令行工具 pup 的 audit-logs 子命令。

主要能力（子技能）

security-investigation：适用于“谁改了 X？”“这个用户做了什么？”“显示过去 24 小时的删除操作”等场景。
key-compromise：适用于“这个 API key 是否被泄露？”“key XYZ 做了什么？”“调查可疑的 key 活动”。
cost-spike-investigation：适用于“为什么我的账单上涨了？”“什么造成了用量激增？”“调查 LLM 成本上升”。
compliance-report：适用于“生成 SOC 2 证据”“PCI 审计日志”“给审计员的用户配置报告”。
ai-activity-audit：适用于“AI 助手做了什么？”“审计 MCP 工具调用”“AI 治理报告”。

前置条件

pup auth login   # OAuth2（推荐）
# 或设置 DD_API_KEY + DD_APP_KEY，并具备 audit_logs_read 权限范围

使用方式（命令）

# 列出近期事件
pup audit-logs list --from 1h --limit 100

# 使用查询语句搜索
pup audit-logs search --query "@action:deleted" --from 24h

# 输出 JSON 以便通过管道传给 jq
pup audit-logs search --query "@usr.email:alice@example.com" --from 7d -o json | jq '.data[].attributes'

事件字段速查

@usr.email：操作者邮箱，例如 alice@example.com
@evt.actor.type：操作发起方式，例如 USER、API_KEY、SUPPORT_USER
@action：动作谓词，例如 created、modified、deleted、accessed、login
@evt.name：事件类别，例如 Dashboard、Monitor、Authentication、Access Management
@asset.type：资源类型，例如 dashboard、monitor、api_key、role、user
@asset.id：资源标识符，例如 abc-123
@metadata.api_key.id：使用的 API key（如适用），例如 key_abc123
@metadata.app_key.id：使用的 App key（如适用），例如 app_abc123
@network.client.ip：客户端 IP 地址，例如 1.2.3.4
@network.client.geoip.country.name：国家，例如 United States
@network.client.geoip.as.name：ASN 名称，例如 Amazon.com
@http.url_details.path：API 端点路径，例如 /api/v1/dashboard/xyz

搜索语法

与 Log Explorer 相同的 Lucene 风格语法：

@evt.name:Dashboard：字段精确匹配
@action:deleted：动作过滤
@usr.email:alice@example.com：指定用户
@evt.name:Monitor AND @action:modified：复合条件
-@action:deleted：取反
@usr.email:*：字段存在
@network.client.ip:1.2.3.4：IP 过滤

保留期

默认保留期为 90 天。若需查询超过 90 天的数据，必须已配置归档到 S3/GCS/Azure Blob。运行查询前应先确认所请求的时间窗口是否在保留期内。

故障排查

403 Forbidden：原因缺少 audit_logs_read 权限范围；修复方式为在 Datadog UI 中为 app key 添加该权限。
结果为空：原因时间窗口超出保留期；修复方式为检查归档配置，默认上限为 90 天。
超时：原因查询过于宽泛；修复方式为缩小时间窗口或增加更多过滤条件。
无 IP 数据：原因内部操作或尚未富化的事件；并非所有事件都有地理位置数据。

限制

依赖 Datadog Audit Trail 与 pup 工具；需要相应权限范围；受默认 90 天保留期约束，更长时间范围需具备已配置的归档。其他收费、价格、支持平台等信息资料暂未提供。

参考资料

Audit Trail API
Audit Trail documentation
Search syntax