Skip to content

Forensics and API

Jump to bottom
Stephen edited this page Mar 5, 2026 · 4 revisions

Forensics and API

LABYRINTH captures everything an agent does and structures it for analysis, SIEM integration, and forensic review.

JSONL Event Schema

Each session is stored as a JSONL file in /var/labyrinth/forensics/sessions/:

{"timestamp": "2026-02-26T14:32:00Z", "session_id": "LAB-001", "layer": 1, "event": "connection", "data": {"source_ip": "10.0.1.5", "service": "ssh"}}
{"timestamp": "2026-02-26T14:33:00Z", "session_id": "LAB-001", "layer": 2, "event": "enumerate", "data": {"path": "/etc"}}
{"timestamp": "2026-02-26T14:35:00Z", "session_id": "LAB-001", "layer": 3, "event": "blindfold_activated", "data": {}}
{"timestamp": "2026-02-26T14:41:55Z", "session_id": "LAB-001", "layer": 4, "event": "api_intercepted", "data": {"domain": "api.openai.com", "path": "/v1/chat/completions", "prompt_swapped": true}}

Event Fields

Field Type Description
timestamp string (ISO 8601) Event timestamp in UTC
session_id string Unique session ID (format: LAB-YYYYMMDD-###)
layer int (0-4) LABYRINTH layer that generated the event
event string Event type identifier
data object Event-specific payload

Event Types

Event Layer Description
connection 1 New SSH/HTTP connection
auth 1 Authentication attempt
http_access 1 HTTP request logged
enumerate 2 Agent enumeration activity
escalation_redirect 2 Privesc attempt redirected to new container
blindfold_activated 3 Encoding corruption triggered
api_intercepted 4 AI API call intercepted (enriched with key, model, tools)
api_response 4 AI API response captured (tool calls, token usage)
service_connection 4 TCP connection to phantom service (protocol, port)
service_auth 4 Authentication attempt on phantom service (credentials captured)
service_query 4 Query or command submitted to phantom service

Auth Events

Authentication events are separately logged to /var/labyrinth/forensics/auth_events.jsonl:

{
  "timestamp": "2026-02-26T14:32:00Z",
  "event": "auth",
  "service": "ssh",
  "src_ip": "10.0.1.5",
  "username": "<username>",
  "password": "<password>"
}

Captured Prompts

Intercepted AI agent system prompts are saved to /var/labyrinth/forensics/prompts/{session_id}.txt:

--- 2026-02-26T14:41:55Z | api.openai.com ---
You are an autonomous penetration testing agent. Your mission is to...

Session Reports

Full session data exports as structured JSON:

{
  "session_id": "LAB-2025-0226-001",
  "source_ip": "198.51.100.42",
  "duration_seconds": 2843,
  "max_layer_reached": 4,
  "final_status": "COGNITIVE_TAKEOVER",
  "captured_intelligence": {
    "system_prompt": "forensics/prompts/LAB-2025-0226-001.txt",
    "agent_framework": "AutoPT v2.1",
    "model_backend": "api.openai.com",
    "c2_callbacks": ["https://c2.attacker.example/report"],
    "auth_tokens": 2,
    "total_commands": 147,
    "contradictions_encountered": 23
  },
  "layer_transitions": [
    {"timestamp": "2026-02-26T14:32:00Z", "layer": 1, "event": "container_spawned"},
    {"timestamp": "2026-02-26T14:35:41Z", "layer": 2, "event": "escalation_redirect"},
    {"timestamp": "2026-02-26T14:38:12Z", "layer": 3, "event": "encoding_corruption"},
    {"timestamp": "2026-02-26T14:41:55Z", "layer": 4, "event": "prompt_intercepted"}
  ],
  "command_log": "forensics/sessions/LAB-2025-0226-001.jsonl"
}

Dashboard API

The Flask dashboard at :9000 exposes the following API endpoints:

GET /api/stats

Returns aggregate statistics:

{
  "active_sessions": 3,
  "captured_prompts": 7,
  "total_events": 142,
  "l4_interceptions": 15,
  "service_connections": 8,
  "service_auths": 3
}

GET /api/sessions

Returns a list of session files with event counts:

[
  {"file": "LAB-001.jsonl", "events": 42, "last": "{...}"},
  {"file": "LAB-002.jsonl", "events": 18, "last": "{...}"}
]

The last field contains the raw JSON string of the most recent event in the session.

GET /api/l4/mode

Returns the current L4 PUPPETEER mode:

{"mode": "passive", "valid_modes": ["counter_intel", "double_agent", "neutralize", "passive"]}

POST /api/l4/mode

Set the L4 mode at runtime. Body: {"mode": "double_agent"}. Returns 400 for invalid modes.

GET /api/l4/intel

Returns structured intelligence report summaries from L4 interception. See Layer-4-PUPPETEER for full schema.

GET /api/l4/services

Returns phantom service status and event counts:

{
  "services": [
    {"port": 5432, "protocol": "postgresql", "name": "Database"},
    {"port": 6379, "protocol": "redis", "name": "Cache"},
    {"port": 9200, "protocol": "elasticsearch", "name": "Search"},
    {"port": 8500, "protocol": "consul", "name": "Service catalog"},
    {"port": 8080, "protocol": "jenkins", "name": "CI/CD"},
    {"port": 10022, "protocol": "ssh", "name": "SSH relay"}
  ],
  "event_counts": {"service_connection": 12, "service_auth": 5, "service_query": 23},
  "protocol_breakdown": {"postgresql": 15, "redis": 10, "consul": 8, "elasticsearch": 5}
}

GET /api/health

Returns dashboard health status:

{"status": "ok", "uptime_seconds": 3600.5}

GET /api/sessions/{session_id}

Returns the full event timeline for a single session:

{
  "session_id": "LAB-abc123",
  "events": [...],
  "max_depth": 1,
  "l3_activated": false,
  "layers_triggered": [1, 2, 4],
  "first_seen": "2026-03-03T23:18:21Z",
  "last_seen": "2026-03-03T23:41:55Z",
  "has_prompts": false,
  "prompt_text": ""
}

GET /api/sessions/{session_id}/analysis

Returns post-mortem analysis including confusion score, phases, and key moments:

{
  "session_id": "LAB-abc123",
  "total_events": 148,
  "duration_seconds": 1419,
  "layers_reached": [1, 2, 4],
  "max_depth": 1,
  "confusion_score": 62,
  "l3_activated": false,
  "l4_active": true,
  "event_breakdown": {"command": 42, "service_query": 24, ...}
}

GET /api/auth

Returns captured authentication events:

{
  "auth_events": [
    {"timestamp": "...", "service": "ssh", "src_ip": "172.30.0.1", "username": "<bait-user>", "password": "<bait-password>"}
  ]
}

GET /api/bait-identity

Returns the currently loaded bait identity (planted credentials):

{
  "company": "<generated-company>",
  "domain": "<generated-domain>",
  "users": [{"email": "<user>@<domain>", "role": "admin", "uname": "<username>"}],
  "db_pass": "<generated>",
  "redis_token": "<generated>",
  "aws_key_id": "<generated>"
}

GET /api/layers

Returns the status of all 5 layers.

GET /api/containers

Returns infrastructure and session container status.

GET /api/prompts

Returns captured AI system prompts.

POST /api/reset

Kills session containers and clears forensic data. Returns counts of containers removed and files cleared.

TUI Data Consumption

The TUI dashboard consumes these endpoints:

  • Polls /api/stats and /api/sessions every 2 seconds
  • Falls back to reading JSONL files directly from /var/labyrinth/forensics/ if the API is unavailable
  • The Go forensics reader (cli/internal/forensics/reader.go) supports reading up to 50 recent session files

SIEM Integration

LABYRINTH can push events to an external SIEM endpoint in real-time:

siem:
  enabled: true
  endpoint: https://siem.internal/api/events
  alert_prefix: LABYRINTH

The SIEM integration (src/orchestrator/siem.py) uses fire-and-forget async threads to push events without blocking the main orchestrator loop. Events are prefixed with the configured alert_prefix.

File Locations

Path Content
/var/labyrinth/forensics/sessions/*.jsonl Per-session event logs
/var/labyrinth/forensics/auth_events.jsonl Authentication events
/var/labyrinth/forensics/prompts/*.txt Captured system prompts
/var/labyrinth/forensics/proxy_session_map.json IP → session ID mapping
/var/labyrinth/forensics/config.json Boot-time configuration data (identity, credentials)
/var/labyrinth/forensics/intel/*.json L4 per-session intelligence reports
/var/labyrinth/forensics/l4_mode.json Current L4 interceptor mode (runtime)

Forensic Report Generation

The CLI can generate structured forensic reports from captured session data:

labyrinth report                           # Latest session (ANSI terminal output)
labyrinth report <session-id>              # Specific session
labyrinth report --all                     # All sessions
labyrinth report --format md -o report.md  # Markdown with Mermaid attack graph
labyrinth report --format json             # JSON export

Reports include:

  • Executive summary — duration, attacker type classification (AI Agent / Scanner / Human), confusion score, risk level
  • MITRE ATT&CK timeline — every forensic event mapped to a tactic and technique ID
  • Credential analysis — planted bait vs captured attempts, hit rate
  • Service interaction log — phantom service engagement per protocol (connections, auth, queries)
  • Attack graph — Mermaid flowchart with layer-colored nodes showing attack progression
  • Effectiveness assessment — what deception worked, what didn't, intelligence captured

The report builder uses the dashboard API when available, falling back to direct JSONL file reading. The confusion score algorithm matches the dashboard's computation (repeated commands, auth loops, depth oscillation, repeated paths, blindfold activation, API interception, service credential use).

See CLI-Reference for full flag documentation.

Related Pages

Project LABYRINTH

Home

Getting Started

Architecture

Layers

Operations

Clone this wiki locally