Events API

The Events API provides endpoints for querying telemetry events collected from endpoint agents. You can list events, search with complex filters, explore related events, and manage event data.

Endpoints Overview

Event Types

Tamandua collects the following event types from agents:

List Events

Retrieve a paginated list of events with optional filters.

Endpoint: GET /api/v1/events Query Parameters: Example Request:

curl -X GET "https://api.tamandua.io/api/v1/events?agent_id=agent-001&event_type=process_create&limit=50" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "data": [
    {
      "id": "evt-550e8400-e29b-41d4-a716-446655440000",
      "agent_id": "agent-001",
      "agent_hostname": "WORKSTATION-01",
      "event_type": "process_create",
      "timestamp": "2024-01-15T14:30:00Z",
      "payload": {
        "name": "powershell.exe",
        "pid": 1234,
        "ppid": 5678,
        "path": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
        "cmdline": "powershell.exe -ExecutionPolicy Bypass -File script.ps1",
        "user": "DOMAIN\\user",
        "sha256": "abc123def456...",
        "is_elevated": false,
        "is_signed": true,
        "signer": "Microsoft Corporation"
      }
    },
    {
      "id": "evt-660e8400-e29b-41d4-a716-446655440001",
      "agent_id": "agent-001",
      "agent_hostname": "WORKSTATION-01",
      "event_type": "process_create",
      "timestamp": "2024-01-15T14:29:55Z",
      "payload": {
        "name": "cmd.exe",
        "pid": 5678,
        "ppid": 9012,
        "path": "C:\\Windows\\System32\\cmd.exe",
        "cmdline": "cmd.exe /c powershell.exe -File script.ps1",
        "user": "DOMAIN\\user",
        "is_elevated": false,
        "is_signed": true,
        "signer": "Microsoft Corporation"
      }
    }
  ]
}

Get Event Details

Retrieve full details for a specific event.

Endpoint: GET /api/v1/events/:id Example Request:

curl -X GET "https://api.tamandua.io/api/v1/events/evt-550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "data": {
    "id": "evt-550e8400-e29b-41d4-a716-446655440000",
    "agent_id": "agent-001",
    "agent_hostname": "WORKSTATION-01",
    "event_type": "process_create",
    "timestamp": "2024-01-15T14:30:00Z",
    "payload": {
      "name": "powershell.exe",
      "pid": 1234,
      "ppid": 5678,
      "path": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
      "cmdline": "powershell.exe -ExecutionPolicy Bypass -EncodedCommand ZQBjAGgAbwAgACIASABlAGwAbABvACIA",
      "user": "DOMAIN\\user",
      "sha256": "abc123def456789...",
      "md5": "def456abc123...",
      "is_elevated": true,
      "is_signed": true,
      "signer": "Microsoft Corporation",
      "integrity_level": "High",
      "parent_name": "cmd.exe",
      "parent_path": "C:\\Windows\\System32\\cmd.exe",
      "current_directory": "C:\\Users\\user\\Downloads",
      "environment": {
        "COMPUTERNAME": "WORKSTATION-01",
        "USERNAME": "user"
      }
    }
  }
}

Search Events

Search events with complex filtering, time ranges, and full-text search.

Endpoint: POST /api/v1/events/search Request Body: Example Request:

curl -X POST "https://api.tamandua.io/api/v1/events/search" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "powershell -EncodedCommand",
    "time_range": "24h",
    "event_type": ["process_create"],
    "limit": 100
  }'

Example Response:

{
  "data": [
    {
      "id": "evt-001",
      "agent_id": "agent-001",
      "event_type": "process_create",
      "timestamp": "2024-01-15T14:30:00Z",
      "payload": {
        "name": "powershell.exe",
        "cmdline": "powershell.exe -EncodedCommand ZQBjAGgAbwAgACIASABlAGwAbABvACIA"
      }
    }
  ],
  "meta": {
    "query": "powershell -EncodedCommand",
    "time_range": "24h"
  }
}

Search Query Syntax

The search query supports various operators:

Complex Query Example:

{
  "query": "process_name:powershell.exe AND cmdline:*-Enc* NOT cmdline:*legitimate*",
  "time_range": "7d",
  "event_type": "process_create"
}

Get Related Events

Retrieve events related to a source event using the correlation engine. Related events share common attributes like process ID, file path, network connection, or are part of the same attack chain.

Endpoint: GET /api/v1/events/:id/related Query Parameters: Example Request:

curl -X GET "https://api.tamandua.io/api/v1/events/evt-001/related?agent_id=agent-001&time_window=60" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "related_events": [
    {
      "event_id": "evt-002",
      "event_type": "file_create",
      "timestamp": "2024-01-15T14:30:05Z",
      "severity": "medium",
      "correlation_score": 0.95,
      "correlation_reason": "Same process ID (1234)",
      "pid": 1234,
      "process_name": "powershell.exe",
      "summary": "File operation: script.ps1",
      "payload": {
        "path": "C:\\Users\\user\\script.ps1",
        "pid": 1234
      }
    },
    {
      "event_id": "evt-003",
      "event_type": "network_connect",
      "timestamp": "2024-01-15T14:30:10Z",
      "severity": "high",
      "correlation_score": 0.88,
      "correlation_reason": "Child process of source event",
      "pid": 1234,
      "process_name": "powershell.exe",
      "summary": "Network connection to 10.0.0.50:443",
      "payload": {
        "remote_ip": "10.0.0.50",
        "remote_port": 443,
        "pid": 1234
      }
    },
    {
      "event_id": "evt-004",
      "event_type": "dns_query",
      "timestamp": "2024-01-15T14:30:08Z",
      "severity": "info",
      "correlation_score": 0.75,
      "correlation_reason": "Same time window, same process",
      "pid": 1234,
      "process_name": "powershell.exe",
      "summary": "DNS query: malicious-domain.com",
      "payload": {
        "query": "malicious-domain.com",
        "pid": 1234
      }
    }
  ],
  "meta": {
    "source_event_id": "evt-001",
    "agent_id": "agent-001",
    "time_window_minutes": 60,
    "count": 3
  }
}

Correlation Score

The correlation engine calculates a score (0-1) based on:

Purge Events

Delete events by type. Useful for cleaning up noisy event types or managing storage.

Endpoint: DELETE /api/v1/events/purge Query Parameters: Example Request:

curl -X DELETE "https://api.tamandua.io/api/v1/events/purge?event_type=image_load" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "deleted": 15420,
  "event_type": "image_load"
}

Warning: This operation is irreversible. Consider exporting events before purging.

Event Payload Schemas

Process Create Event

{
  "name": "powershell.exe",
  "pid": 1234,
  "ppid": 5678,
  "path": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
  "cmdline": "powershell.exe -ExecutionPolicy Bypass",
  "user": "DOMAIN\\user",
  "sha256": "abc123...",
  "md5": "def456...",
  "is_elevated": true,
  "is_signed": true,
  "signer": "Microsoft Corporation",
  "integrity_level": "High",
  "parent_name": "cmd.exe",
  "parent_path": "C:\\Windows\\System32\\cmd.exe",
  "current_directory": "C:\\Users\\user"
}

File Event

{
  "path": "C:\\Users\\user\\Documents\\file.docx",
  "operation": "create",
  "pid": 1234,
  "process_name": "WINWORD.EXE",
  "sha256": "abc123...",
  "size_bytes": 15420,
  "is_executable": false,
  "entropy": 4.5
}

Network Connect Event

{
  "pid": 1234,
  "process_name": "chrome.exe",
  "local_ip": "192.168.1.100",
  "local_port": 54321,
  "remote_ip": "142.250.185.46",
  "remote_port": 443,
  "protocol": "tcp",
  "direction": "outbound",
  "state": "established"
}

DNS Query Event

{
  "query": "www.example.com",
  "query_type": "A",
  "pid": 1234,
  "process_name": "chrome.exe",
  "response": ["93.184.216.34"],
  "response_code": "NOERROR",
  "cached": false
}

Registry Event (Windows)

{
  "key": "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Run",
  "value_name": "MyApp",
  "value_data": "C:\\path\\to\\app.exe",
  "value_type": "REG_SZ",
  "operation": "create",
  "pid": 1234,
  "process_name": "installer.exe"
}

Image Load Event

{
  "path": "C:\\Windows\\System32\\kernel32.dll",
  "sha256": "abc123...",
  "is_signed": true,
  "signer": "Microsoft Windows",
  "pid": 1234,
  "process_name": "notepad.exe",
  "image_base": "0x7FFF12340000",
  "image_size": 1572864
}

Real-Time Event Streaming

For real-time event consumption, use the streaming endpoints:

Server-Sent Events (SSE)

Endpoint: GET /api/v1/stream/events

curl -N "https://api.tamandua.io/api/v1/stream/events?agent_id=agent-001" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Accept: text/event-stream"

Event Stream:

event: event
data: {"id":"evt-001","event_type":"process_create","timestamp":"2024-01-15T14:30:00Z",...}

event: event
data: {"id":"evt-002","event_type":"file_create","timestamp":"2024-01-15T14:30:01Z",...}

event: heartbeat
data: {"timestamp":"2024-01-15T14:30:05Z"}

Long Polling

Endpoint: GET /api/v1/poll/events

curl -X GET "https://api.tamandua.io/api/v1/poll/events?since=2024-01-15T14:30:00Z" \
  -H "Authorization: Bearer tam_live_xxxxx"

Aggregations

While not a dedicated endpoint, the search endpoint supports aggregations:

Example Request:

curl -X POST "https://api.tamandua.io/api/v1/events/search" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "time_range": "24h",
    "event_type": "network_connect",
    "aggregations": {
      "by_destination": {
        "field": "payload.remote_ip",
        "size": 10
      },
      "by_port": {
        "field": "payload.remote_port",
        "size": 10
      }
    }
  }'

Error Responses

Event Not Found

{
  "error": "Event not found"
}

HTTP Status: 404

Missing Required Parameter

{
  "error": "agent_id parameter is required"
}

HTTP Status: 400

Invalid Event Type

{
  "error": "event_type parameter is required"
}

HTTP Status: 400