C2 Framework

A security-focused Command and Control (C2) framework built in Python for educational and security research purposes.

Overview

This C2 framework provides a complete red team infrastructure:

Component	Description
C2 Server	Flask HTTP server with SQLite storage, REST API, encryption, task queue, auth
C2 Agent	Lightweight Python beacon that registers, heartbeats, executes commands
Operator Dashboard	Interactive CLI for managing agents and dispatching tasks
Post-Exploitation Modules	Plugin system for file transfer, env enumeration, process listing

Features

• Agent Registration & Heartbeats - Agents beacon with jitter; server tracks active/inactive/dead
• E2E Encryption - AES-256-GCM per-agent keys; all traffic encrypted after registration
• Task Queue - Queue commands (shell, sysinfo, dirlist) for agents; view results
• Post-Exploitation - Built-in modules: download, upload, env, ps
• Operator Auth - Login required for dashboard; role-based access (admin/operator/viewer)
• Interactive Dashboard - Menu-driven CLI to list agents, send commands, view results
• Full Test Suite - 45 automated tests

Quick Start

1. Start the Server

cd /testbed/zed-base
python server/app.py

Server starts on http://0.0.0.0:8080. First run creates default admin user: admin / admin123

2. Deploy an Agent

# On target machine (or locally for testing)
python agent/agent.py --server http://localhost:8080 --beacon-interval 30 --jitter 0.2

The agent registers, receives an encryption key, and begins beaconing.

3. Use the Operator Dashboard

python -m c2operator.dashboard --server http://localhost:8080

1. Login with admin / admin123 (or your credentials)
2. List agents [1] - see all registered agents with status
3. Select agent [3] - pick by number or ID prefix
4. Send command [4] - shell, sysinfo, or dirlist
5. Run module [9] - post-exploitation: download, upload, env, ps
6. View results [5] - task history with full output

Project Structure

zed-base/
├── server/app.py          # Flask server (API, auth, tasks, encryption)
├── agent/agent.py         # Beacon agent (register, heartbeat, execute)
├── c2operator/dashboard.py # Interactive operator CLI
├── c2modules/             # Post-exploitation plugin system
│   ├── base.py            # C2Module base class + registry
│   ├── download.py        # File download (agent→operator)
│   ├── upload.py          # File upload (operator→agent)
│   ├── env.py             # Environment variables
│   └── ps.py              # Process listing
├── tests/                 # 45 automated tests
└── README.md

Authentication & RBAC

The server requires authentication for operator endpoints. Login via dashboard or API:

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'
# Returns: {token, role, expires_at}

Roles:

Role	Can
admin	Full control: manage agents, tasks, users
operator	View agents, create/view tasks
viewer	Read-only: list agents and tasks

API Endpoints

Method	Endpoint	Auth	Description
POST	/api/auth/login	No	Login → token
GET	/api/agents	Yes	List agents
GET	/api/agents/<id>	Yes	Agent details
DELETE	/api/agents/<id>	Yes (admin)	Remove agent
POST	/api/tasks	Yes	Queue task
GET	/api/tasks	Yes	List tasks
POST	/api/register	No	Agent beacon
POST	/api/tasks/<id>/result	No	Agent result

Post-Exploitation Modules

Modules register themselves and are available as command_type in tasks:

Module	Description
download	Download file from agent (base64)
upload	Upload file to agent (base64)
env	Enumerate environment variables
ps	List running processes

Add custom modules by creating c2modules/mymodule.py with @register_module decorated class.

Running Tests

python -m pytest tests/ -v
# 45 passed

Requirements

• Python 3.8+
• Flask
• Requests
• Cryptography (for encryption)

Security Notice

For authorized security research only. Users must have explicit permission before deploying agents. Default credentials (admin/admin123) must be changed in production. All traffic is encrypted; operators must authenticate. See SECURITY.md if present.

License

Educational use only. Use responsibly and ethically.