Index of every page on this site: llms.txt
All skills
datadog-labs avatar

/security-investigation

@618fae3 official
Run it yourself

Answer "who did what" security questions from Audit Trail — deletions, config changes, login activity, permission changes, actions from a specific user or IP.

  • 1 file
  • 6.1 KB
  • Updated 7 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/datadog-labs/agent-skills/security-investigation

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈46 tokens for metadata: the name and description. ≈1.4k when used: this file.

Description uses 2.4% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈192 characters, or 2.4%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Audit Trail: Security Investigation

Answer common security investigation questions using pup audit-logs.

Prerequisites

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

Command Execution Order

  1. Clarify the investigation scope: who, what resource type, what time window.
  2. Run the most specific query first; broaden only if results are empty.
  3. If results are large, pipe to jq to group or summarize.
  4. Highlight anomalies: bulk operations, unusual geo, off-hours activity, support user actions.

Common Investigation Queries

Who deleted resources in a time window?

pup audit-logs search --query "@action:deleted" --from 24h -o json \
  | jq '[.data[] | {
      timestamp: .attributes.timestamp,
      user: .attributes.attributes.usr.email,
      actor_type: .attributes.attributes.evt.actor.type,
      resource_type: .attributes.attributes.asset.type,
      resource_id: .attributes.attributes.asset.id,
      country: .attributes.attributes.network.client.geoip.country.name
    }]'

Who modified a specific resource (by ID)?

pup audit-logs search --query "@asset.id:RESOURCE_ID" --from 7d -o json \
  | jq '[.data[] | {
      timestamp: .attributes.timestamp,
      user: .attributes.attributes.usr.email,
      action: .attributes.attributes.action,
      event: .attributes.attributes.evt.name
    }]'

What did a specific user do?

pup audit-logs search --query "@usr.email:user@example.com" --from 7d --limit 200 -o json \
  | jq '[.data[] | {
      timestamp: .attributes.timestamp,
      action: .attributes.attributes.action,
      event: .attributes.attributes.evt.name,
      resource_type: .attributes.attributes.asset.type,
      resource_id: .attributes.attributes.asset.id,
      ip: .attributes.attributes.network.client.ip,
      country: .attributes.attributes.network.client.geoip.country.name
    }]'

Login activity — all logins with geo

pup audit-logs search --query "@evt.name:Authentication @action:login" --from 7d --limit 200 -o json \
  | jq '[.data[] | {
      timestamp: .attributes.timestamp,
      user: .attributes.attributes.usr.email,
      status: .attributes.attributes.status,
      ip: .attributes.attributes.network.client.ip,
      city: .attributes.attributes.network.client.geoip.city.name,
      country: .attributes.attributes.network.client.geoip.country.name,
      asn: .attributes.attributes.network.client.geoip.as.name
    }]'

Failed logins only

pup audit-logs search --query "@evt.name:Authentication @action:login @status:error" --from 7d --limit 200 -o json \
  | jq '[.data[] | {
      timestamp: .attributes.timestamp,
      user: .attributes.attributes.usr.email,
      ip: .attributes.attributes.network.client.ip,
      country: .attributes.attributes.network.client.geoip.country.name
    }]'

Who changed roles or permissions?

pup audit-logs search --query "@evt.name:\"Access Management\"" --from 30d --limit 200 -o json \
  | jq '[.data[] | {
      timestamp: .attributes.timestamp,
      user: .attributes.attributes.usr.email,
      action: .attributes.attributes.action,
      resource_type: .attributes.attributes.asset.type,
      resource_id: .attributes.attributes.asset.id
    }]'

What actions came from a specific IP?

pup audit-logs search --query "@network.client.ip:1.2.3.4" --from 30d --limit 200 -o json \
  | jq '[.data[] | {
      timestamp: .attributes.timestamp,
      user: .attributes.attributes.usr.email,
      actor_type: .attributes.attributes.evt.actor.type,
      action: .attributes.attributes.action,
      event: .attributes.attributes.evt.name,
      resource_type: .attributes.attributes.asset.type
    }]'

Who created or deleted API keys?

pup audit-logs search --query "@evt.name:Authentication @asset.type:api_key" --from 90d --limit 200 -o json \
  | jq '[.data[] | {
      timestamp: .attributes.timestamp,
      user: .attributes.attributes.usr.email,
      action: .attributes.attributes.action,
      key_id: .attributes.attributes.asset.id,
      ip: .attributes.attributes.network.client.ip,
      country: .attributes.attributes.network.client.geoip.country.name
    }]'

Event Category Reference

Category (@evt.name) What it covers
Authentication Logins, API key create/delete/modify
Access Management Roles, user add/remove, restriction policies
Dashboard Create, modify, delete, share
Monitor Create, modify, delete, resolve
Log Management Pipelines, indexes, archives, exclusion filters
Integration Add/modify/delete integrations
Metrics Custom metric create/modify/delete
Organization Management Child org creation, org settings
Notebook Create, modify, delete
APM Retention filters, sampling config
Cloud Security Platform CWS rules, security signal state changes
Bits AI SRE MCP tool calls, AI investigations

Anomaly Flags to Surface

When presenting investigation results, call out:

  • Actor type SUPPORT_USER — Datadog support accessed the org
  • Bulk deletions — same user, same action, many resources in a short window
  • Unexpected geography — country not seen in prior logins for this user
  • Off-hours activity — actions at unusual times for the user's typical timezone
  • First-time ASN — action from a cloud provider or VPN not seen before (@network.client.geoip.as.name)

References

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 618fae3. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 7 months ago
Other metadata
metadata
{
  "version": "0.1.0",
  "author": "datadog-labs",
  "repository": "https://github.com/datadog-labs/agent-skills",
  "tags": "datadog,audit,security,investigation,dd-audit",
  "alwaysApply": "false"
}
  • Security
  • datadog
  • audit-logs
  • investigation
  • access-control
  • compliance
  • authentication
  • api-keys

README badge

README badge for datadog-labs/agent-skills/security-investigation

Queries Datadog Audit Trail to answer security investigation questions—who deleted resources, modified configs, logged in, changed permissions, or performed actions from a specific IP or user. Provides templated searches for common scenarios like failed logins, API key creation/deletion, and bulk operations, with guidance on flagging anomalies like support user access or off-hours activity.

Generated from the current SKILL.md.

What Datadog API credentials does this skill require?
The skill requires DD_API_KEY and DD_APP_KEY with audit_logs_read scope, or OAuth2 authentication via `pup auth login`. It uses the `pup` CLI to query the Datadog Audit Trail API.
Can I search for actions by a specific user or IP address?
Yes. The skill includes pre-built queries to search by user email (`@usr.email`), IP address (`@network.client.ip`), and resource ID. Results include geo, timestamp, and action details.
Does this skill detect suspicious activity?
No, the skill returns raw audit logs and documents anomaly flags to look for manually — bulk deletions, unexpected geography, support user access, off-hours activity, and new ASNs — but does not perform automated anomaly detection.
What event types can I investigate with this skill?
The skill covers Authentication (logins, API keys), Access Management (roles, permissions), Dashboards, Monitors, Log Management, Integrations, Metrics, Organization Management, Notebooks, APM, Cloud Security Platform, and Bits AI SRE events.
Can I filter audit logs by time window?
Yes. All queries support the `--from` flag to specify a time window — common examples are 24h, 7d, 30d, or 90d depending on the investigation scope.

Generated from the current SKILL.md. These answers refresh after source changes.