This guide walks through installing the C2 Framework and all required dependencies on both the server (Ubuntu) and agent (Windows) systems.
This framework is designed exclusively for isolated lab environments. Never deploy on production networks or internet-facing systems.
Prerequisites
Ubuntu Server VM
- Ubuntu 22.04 LTS or later
- Python 3.11+
- Docker and Docker Compose (for containerized deployment)
- OpenSSL for certificate generation
- Git for source code management
Windows Agent VM
- Windows 10 or later
- Python 3.11+ (for agent execution)
- Administrator access (for hosts file modification)
Server Installation
Step 1: Clone the Repository
On the Ubuntu server VM:
cd ~
git clone <repository-url> c2-framework
cd c2-framework
Step 2: Install Python Dependencies
The framework requires the following key dependencies:
# Install pip if not present
sudo apt update
sudo apt install python3-pip python3-venv -y
# Create virtual environment
python3 -m venv venv
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
Step 3: Core Dependencies
The requirements.txt includes these essential packages:
| Package | Version | Purpose |
|---|
fastapi | 0.133.1 | Web framework for C2 server |
uvicorn | 0.41.0 | ASGI server for FastAPI |
aiosqlite | 0.22.1 | Async SQLite for session/task storage |
cryptography | 46.0.5 | TLS and encryption primitives |
pydantic | 2.12.5 | Data validation and serialization |
requests | 2.32.5 | HTTP client for agent |
scapy | 2.7.0 | Network packet manipulation |
httpx | 0.27.2 | Async HTTP client |
pytest | 9.0.2 | Testing framework |
pytest-asyncio | 1.3.0 | Async test support |
PyYAML | 6.0.3 | Configuration parsing |
Step 4: Install OpenSSL
Required for TLS certificate generation:
sudo apt install openssl -y
openssl version
Agent Installation
Step 1: Install Python on Windows
Run Installer
- Check “Add Python to PATH”
- Choose “Install Now”
- Verify: Open PowerShell and run
python --version
Install Dependencies
Copy the agent code and install required packages:cd C:\Users\<username>\c2-framework
python -m pip install requests cryptography pyyaml
Step 2: Copy Agent Files
Transfer the following directories from the Ubuntu VM to the Windows VM:
c2-framework/
├── agent/ # Agent execution engine
├── common/ # Shared crypto, message formats, config
├── transport/ # TLS wrapper and communication
└── evasion/ # Anti-analysis checks (optional)
Never copy certs/server.key to the Windows VM. Only the public certificate (certs/server.crt) should be transferred.
Verify Installation
Server Verification
# Activate virtual environment
source venv/bin/activate
# Test imports
python -c "import fastapi, uvicorn, aiosqlite; print('Server dependencies OK')"
# Check Docker (if using containerized deployment)
docker ps
Agent Verification
# Test imports
python -c "import requests, cryptography; print('Agent dependencies OK')"
# Verify agent module
python -c "from agent.agent_main import main; print('Agent module OK')"
Directory Structure
After installation, the project structure should look like this:
c2-framework/
├── agent/ # Agent components
│ ├── agent_main.py # Agent entry point
│ ├── beacon.py # Beacon logic
│ ├── executor.py # Command execution
│ ├── jitter.py # Timing jitter
│ └── environment_checks.py # Anti-analysis
├── server/ # Server components
│ ├── server_main.py # FastAPI server
│ ├── session_manager.py # Session tracking
│ ├── command_queue.py # Task queuing
│ └── storage.py # Database layer
├── common/ # Shared modules
│ ├── config.py # Configuration (create from example)
│ ├── config_example.py # Configuration template
│ ├── crypto.py # Encryption primitives
│ ├── message_format.py # Protocol definitions
│ └── logger.py # Logging utilities
├── transport/ # Communication layer
│ └── tls_wrapper.py # TLS/certificate pinning
├── redirector/ # Nginx frontend
│ ├── nginx_docker.conf # Docker Nginx config
│ ├── nginx_main.conf # Main Nginx config
│ └── Dockerfile.nginx # Nginx container
├── certs/ # TLS certificates (gitignored)
├── logs/ # Runtime logs and database
├── tests/ # Unit and integration tests
├── docker-compose.yml # Container orchestration
├── Dockerfile # Server container
└── requirements.txt # Python dependencies
Next Steps
After completing the installation:
- Lab Setup - Configure the lab network and generate certificates
- Quickstart - Run the server and connect your first agent
Troubleshooting
Python Version Mismatch
If you encounter module import errors, verify Python version:
python3 --version # Should be 3.11 or higher
Docker Permission Denied
If docker commands fail with permission errors:
sudo usermod -aG docker $USER
# Log out and log back in
Missing System Packages
On Ubuntu, install build essentials if cryptography fails:
sudo apt install build-essential libssl-dev libffi-dev python3-dev -y