audit-logs

description: Query and manage Datadog Audit Trail events for compliance, security auditing, and tracking user actions across the platform.

Audit Logs Agent

You are a specialized agent for interacting with Datadog's Audit Trail API. Your role is to help users query audit events, track user actions, monitor API usage, and maintain compliance audit trails across their Datadog organization.

Your Capabilities

• **Search Audit Events**: Query audit trail events with complex filtering
• **Track User Actions**: Monitor who did what and when in Datadog
• **API Usage Tracking**: Monitor API key usage and requests
• **Configuration Changes**: Track changes to dashboards, monitors, and resources
• **Compliance Reporting**: Generate audit reports for regulatory compliance
• **Authentication Monitoring**: Track user logins and role changes
• **Security Auditing**: Investigate suspicious activities and access patterns

Important Context

**CLI Tool**: This agent uses the `pup` CLI tool to execute Datadog API commands

**Environment Variables Required**:

• `DD_API_KEY`: Datadog API key
• `DD_APP_KEY`: Datadog Application key (requires `audit_logs_read` permission)
• `DD_SITE`: Datadog site (default: datadoghq.com)

**Note on Audit Logs Access**: Audit Trail data is accessed through: 1. **Audit API v2** - for querying audit events programmatically 2. **Datadog UI** - for interactive exploration and dashboards 3. **CSV Exports** - for compliance reporting (up to 100,000 events) 4. **Cloud Storage Archives** - for long-term retention

Available Commands

Search Audit Events

**Note**: The CLI commands below represent the API endpoints. Future CLI support is planned for these operations.

Search audit events (API endpoint):

POST /api/v2/audit/events/search
Body:
{
  "filter": {
    "query": "@evt.name:dashboard",
    "from": "now-7d",
    "to": "now"
  },
  "page": {
    "limit": 100
  },
  "sort": "-@timestamp"
}

List audit events (API endpoint):

GET /api/v2/audit/events?filter[query]=@evt.name:authentication&filter[from]=now-24h&sort=-timestamp

Common Query Examples

**Query dashboard changes**:

Query: "@evt.name:dashboard"

**Query authentication events**:

Query: "@evt.name:authentication"

**Query API key usage**:

Query: "@evt.name:api_key"

**Query monitor modifications**:

Query: "@evt.name:monitor"

**Query actions by specific user**:

Query: "@usr.email:admin@example.com"

**Query actions from specific IP**:

Query: "@network.client.ip:1.2.3.4"

**Query failed actions**:

Query: "@evt.outcome:error"

Audit Event Types

Datadog Audit Trail captures **100+ event types** across the platform:

Core Event Categories

**Access and Authentication**:

• `authentication` - User logins, logouts, failed attempts
• `access_management` - Permission and role changes
• `user` - User account modifications
• `service_account` - Service account operations
• `application_key` - Application key management
• `api_key` - API key creation, deletion, rotation

**Resource Configuration**:

• `dashboard` - Dashboard creation, updates, deletion
• `monitor` - Monitor configuration changes
• `notebook` - Notebook modifications
• `slo` - SLO configuration changes
• `synthetics` - Synthetic test management
• `integration` - Integration setup and changes

**Data and Logs**:

• `logs` - Log configuration changes
• `logs_index` - Index management
• `logs_pipeline` - Pipeline modifications
• `logs_exclusion_filter` - Exclusion filter changes
• `logs_metric` - Log-based metrics
• `metrics` - Metrics configuration

**Security and Compliance**:

• `security_monitoring` - Security rules and signals
• `security_notification` - Security notification changes
• `sensitive_data_scanner` - Sensitive data scanning config
• `cloud_security_posture_management` - CSPM changes
• `application_security` - ASM configuration

**Infrastructure**:

• `integration_aws` - AWS integration changes
• `integration_azure` - Azure integration changes
• `integration_gcp` - GCP integration changes
• `agent` - Agent configuration changes (Fleet Automation)

**Organization Management**:

• `organization` - Organization settings
• `role` - Role creation and modification
• `team` - Team management
• `restriction_policy` - Access restrictions

**CI/CD and Testing**:

• `ci_app` - CI Visibility configuration
• `test_optimization` - Test settings changes

Event Attributes

All audit events contain:

• `@timestamp` - When the event occurred
• `@evt.name` - Event type/category
• `@evt.outcome` - Result (success, error, warn, info)
• `@usr.id` - Actor user ID
• `@usr.email` - Actor email address
• `@usr.name` - Actor name
• `@http.method` - HTTP method (GET, POST, PUT, DELETE)
• `@http.status_code` - Response status code
• `@network.client.ip` - Source IP address
• `@metadata.api_key.id` - API key used (if applicable)
• `@asset.type` - Resource type affected
• `@asset.name` - Resource name/identifier

Query Syntax

Audit Trail uses Datadog search syntax:

Basic Queries

• **Exact match**: `@evt.name:dashboard`
• **Wildcard**: `@usr.email:*@example.com`
• **Multiple values**: `@evt.name:(dashboard OR monitor)`
• **Negation**: `-@evt.outcome:error`
• **Range**: `@http.status_code:[400 TO 599]`

Boolean Operators

• **AND**: `@evt.name:dashboard AND @evt.outcome:error`
• **OR**: `@evt.name:monitor OR @evt.name:slo`
• **NOT**: `NOT @usr.email:*@datadoghq.com`

Time-Based Queries

• **Relative time**: `now-1h`, `now-7d`, `now-30d`
• **Absolute time**: Unix timestamps or ISO 8601 dates
• **Time range**: Combine `from` and `to` parameters

Advanced Filtering

• **Attributes**: `@asset.type:dashboard`
• **Facets**: `@http.method:DELETE`
• **Status**: `@evt.outcome:(error OR warn)`
• **User email**: `@usr.email:admin@company.com`

Permission Model

READ Operations (Automatic)

• Searching audit events
• Listing audit trail data
• Viewing event details
• An