Technical Tutorial: AuditReplay API Integration

The AuditReplay API provides automated security audit replay functionality, allowing developers to recreate and analyze security events from audit logs. This tutorial covers implementation details, practical examples, and integration patterns.

What is AuditReplay?

AuditReplay processes security audit logs to recreate event sequences, enabling security teams to understand attack patterns, validate security controls, and investigate incidents. The API accepts audit log data and returns structured replay information including timeline reconstruction, event correlation, and security insights.

Getting Started

First, create an account and obtain your API key:

curl -X POST https://api.aaido.dev/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "organization": "YourCompany"
  }'

The signup response includes your API key:

{
  "status": "success",
  "api_key": "ar_1234567890abcdef",
  "message": "Account created successfully"
}

Basic API Usage

Submitting Audit Logs for Replay

The primary endpoint accepts audit log data in various formats:

curl -X POST https://api.aaido.dev/v1/products/auditreplay \
  -H "Authorization: Bearer ar_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "logs": [
      {
        "timestamp": "2024-01-15T10:30:00Z",
        "source_ip": "192.168.1.100",
        "event_type": "authentication",
        "user": "jdoe",
        "action": "login_attempt",
        "result": "success"
      },
      {
        "timestamp": "2024-01-15T10:31:15Z",
        "source_ip": "192.168.1.100", 
        "event_type": "file_access",
        "user": "jdoe",
        "resource": "/etc/passwd",
        "action": "read",
        "result": "success"
      }
    ],
    "replay_options": {
      "timeline_granularity": "minute",
      "correlation_window": "1h",
      "include_recommendations": true
    }
  }'

Understanding the Response

AuditReplay returns structured analysis of the submitted logs:

{
  "replay_id": "rp_abc123def456",
  "status": "completed",
  "timeline": [
    {
      "timestamp": "2024-01-15T10:30:00Z",
      "events": [
        {
          "id": "evt_001",
          "type": "authentication",
          "severity": "info",
          "details": "User jdoe successfully authenticated from 192.168.1.100"
        }
      ]
    },
    {
      "timestamp": "2024-01-15T10:31:15Z", 
      "events": [
        {
          "id": "evt_002",
          "type": "file_access",
          "severity": "medium",
          "details": "Sensitive file access detected",
          "correlated_events": ["evt_001"]
        }
      ]
    }
  ],
  "security_insights": {
    "risk_score": 6.2,
    "patterns_detected": ["privilege_escalation_attempt"],
    "recommendations": [
      "Monitor user jdoe for additional suspicious activity",
      "Review file access permissions for /etc/passwd"
    ]
  },
  "metadata": {
    "processing_time_ms": 245,
    "events_processed": 2,
    "correlations_found": 1
  }
}

Practical Use Cases

Use Case 1: Incident Response Investigation

Security teams can replay attack sequences to understand incident progression:

curl -X POST https://api.aaido.dev/v1/products/auditreplay \
  -H "Authorization: Bearer ar_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "logs": [
      {
        "timestamp": "2024-01-15T14:22:30Z",
        "source_ip": "10.0.1.55",
        "event_type": "network_connection", 
        "destination": "suspicious-domain.com",
        "protocol": "https"
      },
      {
        "timestamp": "2024-01-15T14:23:45Z",
        "source_ip": "10.0.1.55",
        "event_type": "process_execution",
        "command": "powershell.exe -enc <base64_payload>",
        "parent_process": "winword.exe"
      }
    ],
    "replay_options": {
      "focus": "security_events",
      "threat_hunting_mode": true
    }
  }'

This analysis helps identify malware execution chains and lateral movement patterns.

Use Case 2: Compliance Audit Trail Verification

Organizations can validate audit trail completeness for compliance requirements:

curl -X POST https://api.aaido.dev/v1/products/auditreplay \
  -H "Authorization: Bearer ar_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "logs": [
      {
        "timestamp": "2024-01-15T09:15:00Z",
        "user": "admin",
        "event_type": "privilege_change",
        "target_user": "contractor_user",
        "action": "grant_admin_rights"
      },
      {
        "timestamp": "2024-01-15T16:45:00Z", 
        "user": "admin",
        "event_type": "privilege_change",
        "target_user": "contractor_user",
        "action": "revoke_admin_rights"
      }
    ],
    "replay_options": {
      "compliance_framework": "sox",
      "validate_completeness": true
    }
  }'

Use Case 3: Security Control Validation

Test security control effectiveness by replaying known attack patterns:

curl -X POST https://api.aaido.dev/v1/products/auditreplay \
  -H "Authorization: Bearer ar_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "logs": [
      {
        "timestamp": "2024-01-15T11:00:00Z",
        "event_type": "authentication",
        "user": "testuser", 
        "result": "failed",
        "reason": "invalid_password"
      },
      {
        "timestamp": "2024-01-15T11:00:30Z",
        "event_type": "account_lockout",
        "user": "testuser",
        "lockout_duration": "30m"
      }
    ],
    "replay_options": {
      "control_validation": true,
      "expected_controls": ["account_lockout", "rate_limiting"]
    }
  }'

CI/CD Pipeline Integration

Integrate AuditReplay into your deployment pipeline to automatically validate security controls after changes:

# .github/workflows/security-audit.yml
name: Security Audit Validation

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  audit-replay:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Run Security Tests
        run: |
          # Generate test audit logs
          ./scripts/generate-test-logs.sh > test-audit.json

      - name: Validate with AuditReplay
        run: |
          RESPONSE=$(curl -s -X POST https://api.aaido.dev/v1/products/auditreplay \
            -H "Authorization: Bearer ${{ secrets.AUDITREPLAY_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d @test-audit.json)

          RISK_SCORE=$(echo $RESPONSE | jq '.security_insights.risk_score')

          if (( $(echo "$RISK_SCORE > 8.0" | bc -l) )); then
            echo "High risk score detected: $RISK_SCORE"
            exit 1
          fi

          echo "Security validation passed with risk score: $RISK_SCORE"

Error Handling

The API returns standard HTTP status codes with detailed error messages:

# Example error response
{
  "error": "invalid_log_format",
  "message": "Timestamp format must be ISO 8601",
  "details": {
    "line": 5,
    "field": "timestamp"
  }
}

Common error scenarios include malformed timestamps, missing required fields, and rate limit exceeded (429 status).

Best Practices

• Batch Processing: Submit logs in batches of 100-1000 events for optimal performance
• Rate Limiting: Respect the default limit of 60 requests per minute
• Data Privacy: Sanitize sensitive data before submission
• Caching: Store replay results for frequently analyzed log patterns

Conclusion

The AuditReplay API enables automated security audit analysis, supporting incident response, compliance validation, and security control testing. By integrating replay capabilities into your security workflows, you can improve threat detection and response times.

For complete API documentation and additional examples, visit the AuditReplay product page.