API Reference

REST & WebSocket API

Programmatically submit files for malware analysis and stream real-time threat telemetry.

POST /api/auth/token

Request (Headers)

Authorization: Basic <base64>

Response (200 OK)

{ "token": "jwt_token" }
POST /upload

Upload a malware sample for analysis. The backend streams the file to disk asynchronously, computes static hashes, creates a MongoDB job record, and triggers the full analysis pipeline.

Request (multipart/form-data)

curl -X POST http://api.aegis.io/upload \ -H "Authorization: Bearer $TOKEN" \ -F "file=@malware_sample.py"

Response (201 Created)

{ "file_id": "a8f3c2d1...", "filename": "suspicious.py", "sha256": "e3b0c442...", "task_id": "b1c2d3e4...", "status": "accepted" }
GET /analysis/{job_id}

Retrieve the complete analysis report for a given job. Includes static metadata, YARA matches, MITRE mappings, IOCs, Intelligence Layer results, attack timeline, and AI summary.

Response (200 OK)

{ "status": "completed", "metadata": { "sha256": "...", "size": 4096 }, "risk_score": 71, "risk_calculation": { "verdict": "Infostealer" }, "analyst_report": { "executive_summary": "...", "mitre_coverage": ["T1027", "T1059"] }, "yara_matches": ["MALWARE_CobaltStrike"], "iocs": [{ "type": "ip", "value": "185.11.23.4" }] }
WSS /ws/jobs/{job_id}/telemetry

Subscribes to the Redis PubSub channel and pushes live telemetry events as the sandbox executes.

Connection

const ws = new WebSocket("wss://api.aegis.io/ws/jobs/abc/telemetry"); ws.onmessage = (event) => console.log(event.data);

Payload Format

{ "type": "PROCESS_CREATE", "severity": "high", "data": { "executable": "cmd.exe", "cmdline": "cmd.exe /c start evil.bat" } }
GET /health
{ "status": "healthy", "version": "2.0.0" }
GET /metrics
// Prometheus text format containing: // jobs_processed_total // malware_detected_total

Error Codes

Status Code Description
401 UnauthorizedInvalid or missing authentication token.
403 ForbiddenInsufficient permissions to access this report.
404 Not FoundThe requested analysis ID does not exist.
429 Rate LimitedToo many analysis submissions. Back off and retry.
500 Internal ErrorAn unexpected engine or graph database failure occurred.