ShadowLab: Building a Python C2 Prototype for Security Labs (V1.3)

I built ShadowLab: A modular, Python-based C2 framework designed for security research and offensive simulation.

Traditional cybersecurity study often stops at analyzing existing tools; I believe true expertise comes from building the architecture from scratch to understand the underlying mechanics of EDR evasion and network protocols. This is a technical retrospective on the engineering choices behind ShadowLab.

🏗️ Architectural Foundations: The "Clean" Approach

ShadowLab follows Clean Architecture principles, decoupling the server's core logic to ensure maintainability and scalability. Instead of a monolithic script, the framework is structured into specialized modules:

• Controller (C2 Server): The central hub responsible for command dispatching, cryptographic key management, and session monitoring.
• Agent (Implant): A lightweight binary designed for minimal footprint, supporting both Staged (bootstrap downloader) and Unstaged (monolithic) execution modes. ### 🏛️ Project Structure

ShadowLab/
├── Shadow.py                 # Main C2 Server Application
├── requirements.txt          # Python Package Dependencies
├── LICENSE                   # Project License File
├── SECURITY.md               # Security Policy
├── FAQS.md                   # Frequently Asked Questions
├── CONTRIBUTING.md           # Contribution Guidelines
├── README.md                 # Project Documentation
├── assets/                   # Media & Resources
├── confs/                    # Configuration Files
│   └── conf.json             # Encryption Keys & Server Settings
├── mainclass/                # Core Server Modules
│   ├── builder.py            # Agent/Payload Builder
│   ├── comm.py               # Network Communication Handler
│   ├── encrypter.py          # Encryption & Decryption Utilities
│   ├── pyi_progress.py       # PyInstaller Integration & Progress Display
│   ├── options.py            # Command-Line Options & Menus
│   ├── shell.py              # Remote Command Handlers
│   └── system.py             # System Utilities & Display
├── payloads/                 # Agent/Implant Code
│   ├── payload.py            # Unstaged Payload (Full-Featured)
│   └── payload_staged.py     # Staged Payload (Lightweight)
├── postexploits/             # Post-Exploitation Modules (Future)
│   └── keystroke.py          # (In Development — Pending Security Review)
├── photos/                   # Screenshot & Image Storage Directory
├── records/                  # Audio Recording Storage Directory
└── build/                    # PyInstaller Build Output Directory

🛡️ Hardened Communication & Network Layer

The network layer is the most critical component. To ensure confidentiality and stability, I implemented:

• End-to-End Encryption: All packets are secured using Fernet (AES-128) with dynamic key management.
• Length-Prefixed Protocols: To mitigate TCP streaming anomalies like packet fragmentation, I integrated a 4-byte length-prefixed protocol.
• Non-Blocking I/O: Using Python's native networking structures, the communication handler manages concurrent socket operations effectively.

📊 Deployment Modes Comparison

Mode	Use Case	Detection Risk
Staged	Bootstrap/Downloader	Low (Smaller footprint)
Unstaged	Self-contained binary	Moderate (Monolithic)

🔗 Code & Full Deep Dive

• GitHub Repository: ShadowLab Source Code
• Full Technical Paper: Read the deep dive on Medium

Check out the repository, and I would highly appreciate any backend architecture reviews or code quality feedback from the infosec community here!