Adversary Emulation & Replay Lab 🔬

A production-grade, deterministic platform designed to reconstruct, analyze, and replay real-world attacker sessions captured from honeypots or network taps.

🚀 Overview

The Adversary Lab is built for deep SOC investigations and red-team analysis. It ingests strict JSON logs, groups them into chronologically precise sessions, analyzes the behavior, and replays the exact commands in a secure Docker sandbox to observe the attacker's intent and output.

Key Capabilities:

• Strict Ingestion Engine: Validates input against a unified JSON schema.
• Fidelity Reconstruction: Rebuilds sessions preserving the exact timestamps and delays between attacker commands.
• Docker Replay Engine: Spawns an isolated alpine Linux container for each session. Replays commands step-by-step, capturing standard output to reverse-engineer attacker tools and payloads.
• Deterministic Behavioral Analysis: Categorizes sessions as scanner, bruteforce, or interactive using mathematical thresholds—no black-box AI guessing.
• MITRE ATT&CK® Mapping: Automatically maps detected commands to official MITRE techniques (e.g., T1003, T1033) for threat intelligence enrichment.
• Post-Mortem Forensics: Captures a "Snapshot & Diff" of the sandbox filesystem, showing all files created or modified by the adversary during the attack.
• SOC-Style Dashboard: A modern, single-page web application featuring live charts, a session explorer, and a web-based terminal for viewing the replay engine in real-time.

🏗 Architecture

[ JSON Attack Logs ] ---> ( Ingestion Engine ) ---> ( SQLite Database )
                                                           |
                                                           v
[ Web Dashboard ] <------- ( REST API ) <------- ( Reconstruction & Analysis )
       |
       +---> ( Replay Controls ) ---> ( Replay Engine ) ---> [ Docker Sandbox ]

🛠 Setup & Installation

Prerequisites

• Docker & Docker Compose
• Ensure the host user running Docker has access to /var/run/docker.sock

Deployment

1. Clone the repository and enter the directory.
2. Spin up the platform:

   docker-compose up -d

3. Access the dashboard: http://localhost:8000

🔗 API Design

• POST /api/ingest: Submit an array of JSON logs matching the unified schema.
• GET /api/sessions: Retrieve a list of all reconstructed sessions.
• GET /api/session/<id>: Retrieve detailed metadata and ordered commands for a specific session.
• POST /api/replay/start: Initialize a Docker sandbox and begin replay for a session_id.
• POST /api/replay/control: Send pause, resume, or step commands to an active replay.
• GET /api/replay/status/<id>: Poll the live output and completion status of a replay.

🛡️ Security

This system mounts the Docker socket to spawn replay sandboxes. Do not expose this platform to the public internet. The replay containers themselves run with network_mode: none and use a minimal read-only-style alpine image to prevent escape.