Alerts API

The Alerts API provides comprehensive endpoints for managing security alerts. You can list, filter, search, and update alerts, perform bulk operations, set analyst verdicts, manage exclusion rules, and export data.

Endpoints Overview

List Alerts

Retrieve a paginated list of alerts with optional filters.

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

curl -X GET "https://api.tamandua.io/api/v1/alerts?severity=critical&status=open&page=1&per_page=25" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "data": [
    {
      "id": "alert-550e8400-e29b-41d4-a716-446655440000",
      "agent_id": "agent-001",
      "severity": "critical",
      "title": "Ransomware behavior detected",
      "description": "Mass file encryption activity detected from suspicious process",
      "status": "open",
      "threat_score": 95,
      "mitre_tactics": ["impact"],
      "mitre_techniques": ["T1486"],
      "assigned_to_id": null,
      "resolution_notes": null,
      "source_event_id": "evt-001",
      "event_ids": ["evt-001", "evt-002", "evt-003"],
      "evidence": {
        "files_encrypted": 150,
        "process_name": "unknown.exe",
        "process_path": "C:\\Users\\victim\\Downloads\\unknown.exe"
      },
      "process_chain": ["explorer.exe", "cmd.exe", "unknown.exe"],
      "detection_metadata": {
        "rule_name": "ransomware_mass_encryption",
        "detection_source": "behavioral"
      },
      "verdict": "unconfirmed",
      "verdict_by_id": null,
      "verdict_at": null,
      "created_at": "2024-01-15T14:30:00Z",
      "updated_at": "2024-01-15T14:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 42,
    "total_pages": 2
  }
}

Get Alert Details

Retrieve full details for a specific alert.

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

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

Example Response:

{
  "data": {
    "id": "alert-550e8400-e29b-41d4-a716-446655440000",
    "agent_id": "agent-001",
    "severity": "critical",
    "title": "Ransomware behavior detected",
    "description": "Mass file encryption activity detected from suspicious process",
    "status": "investigating",
    "threat_score": 95,
    "mitre_tactics": ["impact"],
    "mitre_techniques": ["T1486"],
    "assigned_to_id": "user-123",
    "resolution_notes": null,
    "source_event_id": "evt-001",
    "event_ids": ["evt-001", "evt-002", "evt-003"],
    "evidence": {
      "files_encrypted": 150,
      "process_name": "unknown.exe",
      "process_path": "C:\\Users\\victim\\Downloads\\unknown.exe",
      "sha256": "abc123...",
      "parent_process": "cmd.exe"
    },
    "process_chain": ["explorer.exe", "cmd.exe", "unknown.exe"],
    "raw_event": { ... },
    "detection_metadata": {
      "rule_name": "ransomware_mass_encryption",
      "detection_source": "behavioral",
      "confidence": 0.98
    },
    "contributing_events": [
      {
        "event_id": "evt-001",
        "event_type": "file_modify",
        "timestamp": "2024-01-15T14:29:55Z"
      }
    ],
    "verdict": "true_positive",
    "verdict_by_id": "user-123",
    "verdict_at": "2024-01-15T15:00:00Z",
    "verdict_notes": "Confirmed ransomware - LockBit variant",
    "created_at": "2024-01-15T14:30:00Z",
    "updated_at": "2024-01-15T15:00:00Z"
  }
}

Update Alert

Update alert fields such as status, assigned user, or resolution notes.

Endpoint: PATCH /api/v1/alerts/:id Request Body: Example Request:

curl -X PATCH "https://api.tamandua.io/api/v1/alerts/alert-001" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "investigating",
    "assigned_to_id": "user-123"
  }'

Assign Alert

Assign an alert to a user and set status to investigating.

Endpoint: POST /api/v1/alerts/:id/assign Request Body: Example Request:

curl -X POST "https://api.tamandua.io/api/v1/alerts/alert-001/assign" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-123"
  }'

Example Response:

{
  "data": { ... },
  "message": "Alert assigned successfully"
}

Resolve Alert

Mark an alert as resolved with optional notes.

Endpoint: POST /api/v1/alerts/:id/resolve Request Body: Example Request:

curl -X POST "https://api.tamandua.io/api/v1/alerts/alert-001/resolve" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Threat contained and removed. No data exfiltration detected."
  }'

Mark as False Positive

Mark an alert as a false positive.

Endpoint: POST /api/v1/alerts/:id/false_positive Request Body: Example Request:

curl -X POST "https://api.tamandua.io/api/v1/alerts/alert-001/false_positive" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Legitimate admin tool - SysInternals PsExec"
  }'

Update Status

Update just the status of an alert.

Endpoint: PATCH /api/v1/alerts/:id/status Request Body: Valid Statuses: open, new, investigating, resolved, false_positive Example Request:

curl -X PATCH "https://api.tamandua.io/api/v1/alerts/alert-001/status" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "investigating"
  }'

Bulk Operations

Perform bulk updates on multiple alerts at once.

Endpoint: POST /api/v1/alerts/bulk Request Body: Available Actions: status, assign, resolve, false_positive, acknowledge, close Example Request:

curl -X POST "https://api.tamandua.io/api/v1/alerts/bulk" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_ids": ["alert-001", "alert-002", "alert-003"],
    "action": "resolve",
    "notes": "Bulk resolved after investigation"
  }'

Example Response:

{
  "success": true,
  "message": "Successfully updated 3 alert(s)",
  "updated_count": 3
}

Advanced Search

Search alerts with complex filtering criteria.

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

curl -X POST "https://api.tamandua.io/api/v1/alerts/search" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "severity": ["critical", "high"],
    "status": "open",
    "mitre_techniques": ["T1059", "T1486"],
    "date_from": "2024-01-01T00:00:00Z",
    "threat_score_min": 70,
    "sort_by": "threat_score",
    "sort_order": "desc",
    "limit": 50
  }'

Get Alert Summary

Get aggregated alert summary for dashboard widgets.

Endpoint: GET /api/v1/alerts/summary Query Parameters: Example Request:

curl -X GET "https://api.tamandua.io/api/v1/alerts/summary?range=7d" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "data": {
    "total": 156,
    "by_severity": {
      "critical": 5,
      "high": 23,
      "medium": 67,
      "low": 45,
      "info": 16
    },
    "by_status": {
      "open": 28,
      "investigating": 12,
      "resolved": 98,
      "false_positive": 18
    },
    "threat_level": "elevated",
    "active_threat_score": 78,
    "top_threats": [
      {
        "title": "Ransomware behavior detected",
        "count": 5,
        "severity": "critical"
      }
    ]
  }
}

Get Alert Trend

Get time-series trend data for alerts.

Endpoint: GET /api/v1/alerts/trend Query Parameters: Example Request:

curl -X GET "https://api.tamandua.io/api/v1/alerts/trend?period=7d" \
  -H "Authorization: Bearer tam_live_xxxxx"

Set Analyst Verdict

Set the analyst verdict on an alert, optionally creating a suppression rule.

Endpoint: POST /api/v1/alerts/:id/verdict Request Body: Example Request:

curl -X POST "https://api.tamandua.io/api/v1/alerts/alert-001/verdict" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "verdict": "false_positive",
    "notes": "Legitimate backup software behavior",
    "create_suppression_rule": true,
    "suppression_ttl_days": 90,
    "suppression_action": "suppress"
  }'

Example Response:

{
  "data": { ... },
  "suppression_rule": {
    "id": "rule-001",
    "name": "Auto: backup_software_behavior",
    "enabled": true,
    "expires_at": "2024-04-15T14:30:00Z"
  },
  "feedback_log": {
    "id": "log-001",
    "previous_verdict": "unconfirmed",
    "new_verdict": "false_positive",
    "notes": "Legitimate backup software behavior"
  },
  "message": "Verdict set to false_positive"
}

Bulk Set Verdict

Set verdict on multiple alerts at once.

Endpoint: POST /api/v1/alerts/bulk_verdict Request Body: Example Request:

curl -X POST "https://api.tamandua.io/api/v1/alerts/bulk_verdict" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "alert_ids": ["alert-001", "alert-002"],
    "verdict": "false_positive",
    "notes": "Known internal tool",
    "create_suppression_rule": true
  }'

Get Verdict Statistics

Get statistics about analyst verdicts and false positive rates.

Endpoint: GET /api/v1/alerts/verdict-stats Query Parameters: Example Response:

{
  "data": {
    "total_verdicts": 500,
    "by_verdict": {
      "true_positive": 320,
      "false_positive": 150,
      "benign": 20,
      "suspicious": 10
    },
    "false_positive_rate": 0.30,
    "by_detection_source": {
      "sigma": { "total": 200, "fp_rate": 0.25 },
      "yara": { "total": 150, "fp_rate": 0.15 },
      "behavioral": { "total": 150, "fp_rate": 0.45 }
    }
  }
}

Get Related Alerts

Get alerts related to a specific alert (same process, file, or attack chain).

Endpoint: GET /api/v1/alerts/:id/related Example Request:

curl -X GET "https://api.tamandua.io/api/v1/alerts/alert-001/related" \
  -H "Authorization: Bearer tam_live_xxxxx"

Get Alert History

Get historical occurrence data for similar alerts.

Endpoint: GET /api/v1/alerts/:id/history Query Parameters:

Export Alerts

Export alerts in JSON or CSV format.

Endpoint: POST /api/v1/alerts/export Request Body: Example Request:

curl -X POST "https://api.tamandua.io/api/v1/alerts/export" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "severity": ["critical", "high"],
    "date_from": "2024-01-01T00:00:00Z",
    "include_enrichment": true
  }'

Solana Attestation

Create tamper-evident proof metadata for incidents when attestation publishing is configured.

Attest Alert

Endpoint: POST /api/v1/alerts/:id/attest

Queues a Solana attestation for the alert when the deployment has attestation publishing enabled.

Example Request:

curl -X POST "https://api.tamandua.io/api/v1/alerts/alert-001/attest" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "status": "queued",
  "message": "Attestation job enqueued",
  "job_id": "job-123",
  "alert_id": "alert-001"
}

Get Attestation

Endpoint: GET /api/v1/alerts/:id/attestation Example Response:

{
  "data": {
    "attested": true,
    "alert_id": "alert-001",
    "tx_id": "5xYz...abc",
    "attested_at": "2024-01-15T15:00:00Z",
    "solscan_url": "https://solscan.io/tx/5xYz...abc",
    "bounty": {
      "tx_id": "6aBc...def",
      "amount_lamports": 1000000000,
      "amount_sol": 1.0,
      "paid_at": "2024-01-15T15:05:00Z"
    }
  }
}

Exclusion Rules

Manage alert exclusion rules to reduce noise.

List Exclusions

Endpoint: GET /api/v1/alerts/exclusions

Create Exclusion

Endpoint: POST /api/v1/alerts/exclusions

Create from Alert

Endpoint: POST /api/v1/alerts/:id/create-exclusion

Update Exclusion

Endpoint: PUT /api/v1/alerts/exclusions/:id

Delete Exclusion

Endpoint: DELETE /api/v1/alerts/exclusions/:id

Toggle Exclusion

Endpoint: POST /api/v1/alerts/exclusions/:id/toggle

Suppression Rules

Manage verdict-based suppression rules.

List Suppression Rules

Endpoint: GET /api/v1/alerts/suppression-rules

Create Suppression Rule

Endpoint: POST /api/v1/alerts/suppression-rules Request Body:

{
  "name": "Backup Software Alerts",
  "description": "Suppress alerts from known backup software",
  "rule_name_pattern": "file_mass_*",
  "process_name_pattern": "backup*.exe",
  "action": "suppress",
  "expires_at": "2024-06-01T00:00:00Z"
}

Get Suppression Stats

Endpoint: GET /api/v1/alerts/suppression-stats

Filter Presets

Manage saved filter presets for quick access.

List Presets

Endpoint: GET /api/v1/alerts/filter-presets

Save Preset

Endpoint: POST /api/v1/alerts/filter-presets

{
  "name": "Critical Unassigned",
  "filters": {
    "severity": "critical",
    "assigned_to_id": "unassigned"
  }
}

Get Assignable Users

Get list of users who can be assigned alerts.

Endpoint: GET /api/v1/alerts/assignable-users Example Response:

{
  "data": [
    {
      "id": "user-123",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "analyst"
    }
  ]
}