Response API

The Response API provides endpoints for executing incident response actions on endpoints. You can kill processes, quarantine files, collect forensic artifacts, scan paths, create VSS snapshots, and perform ransomware remediation.

Endpoints Overview

Kill Process

Terminate a process on an endpoint by PID.

Endpoint: POST /api/v1/response/kill Request Body: Example Request:

curl -X POST "https://api.tamandua.io/api/v1/response/kill" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "pid": 1234
  }'

Example Response:

{
  "success": true,
  "message": "Process kill command sent"
}

Error Response:

{
  "success": false,
  "error": "Process not found or already terminated"
}

Kill Process Considerations

• The agent will attempt to terminate the process gracefully first
• If graceful termination fails, a forceful kill is attempted
• Killing system-critical processes may be blocked by the OS
• All kill actions are logged in the audit trail

Quarantine File

Move a file to a secure quarantine location where it cannot execute.

Endpoint: POST /api/v1/response/quarantine Request Body: Example Request:

curl -X POST "https://api.tamandua.io/api/v1/response/quarantine" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "path": "C:\\Users\\victim\\Downloads\\malware.exe"
  }'

Example Response:

{
  "success": true,
  "message": "File quarantine command sent"
}

Quarantine Behavior

• Files are encrypted and moved to a secure quarantine folder
• Original file permissions are preserved in metadata
• Files can be restored if determined to be false positive
• SHA256 hash is recorded for threat intelligence
• Quarantine location: C:\ProgramData\Tamandua\Quarantine\ (Windows) or /var/lib/tamandua/quarantine/ (Linux/macOS)

Collect Forensic Artifact

Collect a file or artifact from an endpoint for forensic analysis.

Endpoint: POST /api/v1/response/collect Request Body: Artifact Types:

• file - Single file
• directory - Directory (zipped)
• memory - Process memory dump
• registry - Registry hive export (Windows)
• logs - System log collection

Example Request:

curl -X POST "https://api.tamandua.io/api/v1/response/collect" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "path": "C:\\Users\\victim\\AppData\\Local\\Temp\\suspicious.dll",
    "type": "file"
  }'

Example Response:

{
  "success": true,
  "message": "Artifact collection command sent"
}

Collected Artifact Storage

Collected artifacts are:

• Compressed and encrypted in transit
• Stored in secure server-side storage
• Available for download via the dashboard
• Automatically deleted after configurable retention period

Scan Path

Initiate an on-demand YARA/ML scan of a path on an endpoint.

Endpoint: POST /api/v1/response/scan Request Body: Example Request:

curl -X POST "https://api.tamandua.io/api/v1/response/scan" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "path": "C:\\Users\\victim\\Downloads",
    "recursive": true,
    "max_depth": 3
  }'

Example Response (Immediate):

{
  "success": true,
  "message": "Scan command sent"
}

Example Response (With Results):

{
  "success": true,
  "message": "Scan completed",
  "files_scanned": 1520,
  "threats_found": 3,
  "threats": [
    {
      "path": "C:\\Users\\victim\\Downloads\\installer.exe",
      "threat_name": "Trojan.Generic",
      "detection_type": "yara",
      "rule_name": "generic_trojan_pattern",
      "sha256": "abc123...",
      "severity": "high"
    },
    {
      "path": "C:\\Users\\victim\\Downloads\\keygen.exe",
      "threat_name": "PUP.Keygen",
      "detection_type": "ml",
      "confidence": 0.92,
      "sha256": "def456...",
      "severity": "medium"
    }
  ]
}

Get Response Metrics

Get response action metrics and timeline.

Endpoint: GET /api/v1/response/metrics Query Parameters: Example Request:

curl -X GET "https://api.tamandua.io/api/v1/response/metrics?time_range=24h" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "success": true,
  "metrics": {
    "total_actions": 45,
    "successful": 42,
    "failed": 3,
    "by_type": {
      "kill_process": 20,
      "quarantine_file": 15,
      "collect_artifact": 5,
      "isolate_network": 3,
      "scan_path": 2
    },
    "average_duration_ms": 250,
    "automated_vs_manual": {
      "automated": 35,
      "manual": 10
    }
  },
  "timeline": [
    {
      "id": "resp_abc123def456",
      "type": "rapid_response",
      "agent_id": "agent-001",
      "agent_hostname": "WORKSTATION-01",
      "alert_id": "alert-789",
      "actions": [
        {"action": "kill_process", "result": "ok", "duration_ms": 45},
        {"action": "quarantine_file", "result": "ok", "duration_ms": 120},
        {"action": "isolate_network", "result": "ok", "duration_ms": 85}
      ],
      "duration_ms": 250,
      "success": true,
      "executed_at": "2024-01-15T14:30:00Z",
      "automated": true
    }
  ],
  "time_range": "24h"
}

Rollback Response Action

Rollback a previously executed response action when possible.

Endpoint: POST /api/v1/response/rollback/:response_id Example Request:

curl -X POST "https://api.tamandua.io/api/v1/response/rollback/resp_abc123def456" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "success": true,
  "message": "Rollback completed",
  "result": {
    "actions_reversed": 2,
    "details": [
      {"action": "quarantine_file", "status": "restored"},
      {"action": "isolate_network", "status": "disabled"}
    ]
  }
}

Rollback Limitations

Not all actions can be rolled back:

• kill_process - Cannot be reversed (process already terminated)
• quarantine_file - Can be restored
• isolate_network - Can be disabled
• collect_artifact - N/A (read-only operation)
• scan_path - N/A (read-only operation)

VSS Snapshot Operations

Volume Shadow Copy Service (VSS) snapshots enable file recovery after ransomware attacks.

Create Snapshot

Endpoint: POST /api/v1/agents/:id/snapshots Request Body: Example Request:

curl -X POST "https://api.tamandua.io/api/v1/agents/agent-001/snapshots" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "volume": "C:"
  }'

Example Response:

{
  "success": true,
  "message": "Snapshot created",
  "snapshot": {
    "id": "snap-001",
    "volume": "C:",
    "created_at": "2024-01-15T14:30:00Z",
    "size_bytes": 10737418240
  }
}

List Snapshots

Endpoint: GET /api/v1/agents/:id/snapshots Query Parameters: Example Request:

curl -X GET "https://api.tamandua.io/api/v1/agents/agent-001/snapshots?volume=C:" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "success": true,
  "snapshots": [
    {
      "id": "snap-001",
      "volume": "C:",
      "created_at": "2024-01-15T14:30:00Z",
      "size_bytes": 10737418240
    },
    {
      "id": "snap-002",
      "volume": "C:",
      "created_at": "2024-01-14T10:00:00Z",
      "size_bytes": 10500000000
    }
  ],
  "count": 2,
  "volume": "C:"
}

Delete Snapshot

Endpoint: DELETE /api/v1/agents/:id/snapshots/:snapshot_id Example Request:

curl -X DELETE "https://api.tamandua.io/api/v1/agents/agent-001/snapshots/snap-002" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "success": true,
  "message": "Snapshot deleted",
  "snapshot_id": "snap-002"
}

Restore Files from Snapshot

Endpoint: POST /api/v1/agents/:id/restore Request Body (Single File): Request Body (Multiple Files): Example Request (Single File):

curl -X POST "https://api.tamandua.io/api/v1/agents/agent-001/restore" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshot_id": "snap-001",
    "file_path": "C:\\Users\\victim\\Documents\\important.docx"
  }'

Example Response:

{
  "success": true,
  "message": "File restored",
  "file_path": "C:\\Users\\victim\\Documents\\important.docx",
  "result": {
    "original_size": 15420,
    "restored_at": "2024-01-15T14:35:00Z"
  }
}

Example Request (Multiple Files):

curl -X POST "https://api.tamandua.io/api/v1/agents/agent-001/restore" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshot_id": "snap-001",
    "file_paths": [
      "C:\\Users\\victim\\Documents\\file1.docx",
      "C:\\Users\\victim\\Documents\\file2.xlsx",
      "C:\\Users\\victim\\Documents\\file3.pdf"
    ]
  }'

Example Response:

{
  "success": true,
  "message": "Files restore completed",
  "restored_count": 3,
  "failed_count": 0,
  "result": {
    "restored": [
      "C:\\Users\\victim\\Documents\\file1.docx",
      "C:\\Users\\victim\\Documents\\file2.xlsx",
      "C:\\Users\\victim\\Documents\\file3.pdf"
    ],
    "failed": []
  }
}

Ransomware Remediation

Find Encrypted Files

Detect files that may have been encrypted by ransomware.

Endpoint: GET /api/v1/agents/:id/encrypted-files Query Parameters: Example Request:

curl -X GET "https://api.tamandua.io/api/v1/agents/agent-001/encrypted-files?path=C:\\Users" \
  -H "Authorization: Bearer tam_live_xxxxx"

Example Response:

{
  "success": true,
  "encrypted_files": [
    {
      "path": "C:\\Users\\victim\\Documents\\report.docx.locked",
      "original_extension": ".docx",
      "encrypted_extension": ".locked",
      "size_bytes": 15420,
      "modified_at": "2024-01-15T14:20:00Z",
      "entropy": 7.95
    },
    {
      "path": "C:\\Users\\victim\\Documents\\budget.xlsx.locked",
      "original_extension": ".xlsx",
      "encrypted_extension": ".locked",
      "size_bytes": 25600,
      "modified_at": "2024-01-15T14:20:05Z",
      "entropy": 7.92
    }
  ],
  "count": 150,
  "path": "C:\\Users"
}

Detection Indicators

Files are flagged as potentially encrypted based on:

• High entropy (> 7.5)
• Known ransomware extensions (.locked, .encrypted, .crypt, etc.)
• Recent mass modification timestamps
• Ransomware note files present

Perform Ransomware Remediation

Automatically restore encrypted files from VSS snapshots.

Endpoint: POST /api/v1/agents/:id/remediate Request Body: Example Request:

curl -X POST "https://api.tamandua.io/api/v1/agents/agent-001/remediate" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "C:\\Users\\victim\\Documents",
    "dry_run": false
  }'

Example Response:

{
  "success": true,
  "message": "Ransomware remediation completed",
  "restored_count": 145,
  "failed_count": 5,
  "bytes_restored": 524288000,
  "duration_ms": 45000,
  "result": {
    "snapshot_used": "snap-001",
    "snapshot_date": "2024-01-14T10:00:00Z",
    "restored_files": [
      {
        "original": "C:\\Users\\victim\\Documents\\report.docx.locked",
        "restored_to": "C:\\Users\\victim\\Documents\\report.docx"
      }
    ],
    "failed_files": [
      {
        "path": "C:\\Users\\victim\\Documents\\new_file.docx.locked",
        "reason": "No pre-encryption version found in snapshot"
      }
    ]
  }
}

Remediation Dry Run

Use dry_run: true to preview what would be restored:

curl -X POST "https://api.tamandua.io/api/v1/agents/agent-001/remediate" \
  -H "Authorization: Bearer tam_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "C:\\Users",
    "dry_run": true
  }'

Audit Trail

All response actions are logged in the audit trail:

Endpoint: GET /api/v1/response-audit

See the Response Audit API for detailed audit log queries.

Error Responses

Agent Not Connected

{
  "success": false,
  "error": "Agent is not connected"
}

HTTP Status: 404

Command Failed

{
  "success": false,
  "error": "Command execution failed: timeout"
}

HTTP Status: 400

Insufficient Permissions

{
  "error": "insufficient_permissions",
  "required": ["response:execute"]
}

HTTP Status: 403

Response Not Found

{
  "success": false,
  "error": "Response not found"
}

HTTP Status: 404

Snapshot Not Found

{
  "success": false,
  "error": "Snapshot not found or no longer available"
}

HTTP Status: 400