c2-beacon

 ██████╗██████╗     ██████╗ ███████╗ █████╗  ██████╗ ██████╗ ███╗   ██╗
██╔════╝╚════██╗    ██╔══██╗██╔════╝██╔══██╗██╔════╝██╔═══██╗████╗  ██║
██║      █████╔╝    ██████╔╝█████╗  ███████║██║     ██║   ██║██╔██╗ ██║
██║     ██╔═══╝     ██╔══██╗██╔══╝  ██╔══██║██║     ██║   ██║██║╚██╗██║
╚██████╗███████╗    ██████╔╝███████╗██║  ██║╚██████╗╚██████╔╝██║ ╚████║
 ╚═════╝╚══════╝    ╚═════╝ ╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝

Command and Control beacon and server with XOR-encoded WebSocket protocol, 10 MITRE ATT&CK mapped commands, and a real-time operator dashboard.

This is a quick overview — security theory, architecture, and full walkthroughs are in the learn modules.

What It Does

• WebSocket-based C2 protocol with XOR + Base64 encoding and shared-key authentication
• 10 beacon commands mapped to MITRE ATT&CK: shell, sysinfo, proclist, upload, download, screenshot, keylog, persist, sleep
• Real-time operator dashboard showing connected beacons with live heartbeat tracking
• Terminal-style session page with command history, tab autocomplete, and inline screenshot rendering
• Per-beacon async task queues with SQLite persistence and full task history
• Exponential backoff reconnection with configurable sleep interval and jitter

Quick Start

docker compose -f dev.compose.yml up -d

Visit http://localhost:47430 to open the operator dashboard.

Run a beacon in a separate terminal:

just beacon

Tip

This project uses just as a command runner. Type just to see all available commands.

Install: curl -sSf https://just.systems/install.sh | bash -s -- --to ~/.local/bin

Stack

Backend: FastAPI, aiosqlite, Pydantic, uvicorn

Frontend: React 19, TypeScript, Vite, Zustand, Zod

Beacon: asyncio, websockets, psutil, pynput, mss

Learn

This project includes step-by-step learning materials covering security theory, architecture, and implementation.

Module	Topic
00 - Overview	Prerequisites and quick start
01 - Concepts	C2 frameworks, MITRE ATT&CK, and detection
02 - Architecture	Protocol design and data flow
03 - Implementation	Code walkthrough
04 - Challenges	Extension ideas and exercises

License

AGPL 3.0