C2-Over-HTTP: An Educational C2 Framework

This project provides a functional, simulated Command and Control (C2) framework developed in strictly for demonstration and educational purposes. It demonstrates the fundamental mechanics of a client-server architecture used in red-teaming and cybersecurity analysis, including data exfiltration, beaconing, and logging.

---

⚠️ DISCLAIMER: FOR EDUCATIONAL PURPOSES ONLY ⚠️

This implementation is intended to provide a hands-on understanding of how C2 communication works and how such threats can be detected. It is a simulation and should be treated as such.

Under no circumstances should this tool or its concepts be used on any system illegally (without explicit, written permission from the system owner). Unauthorized access to or monitoring of computer systems is illegal and unethical. The author is not responsible for any misuse of this software or the knowledge gained from it.

---

Project Overview

This project simulates a complete C2 infrastructure where a malware "implant" on a target machine captures keystrokes and sends them to a C2 server. The server logs the incoming data and displays it on a live web dashboard. To make the simulation interactive and safe, it includes an automated typing simulator that types into a local text editor, preventing any accidental interaction with live system terminals.

How It Works

1. The RUN_ME.py script orchestrates the entire simulation, providing a command-line menu to manage all components.
2. It starts the C2 server.py and the client.py implant in separate terminal windows.
3. It opens a local text editor (like Notepad or TextEdit) to serve as a safe, isolated target for typing.
4. The type_simulator.py script starts automatically, typing realistic but "defanged" text samples into the focused text editor.
5. The client.py keylogger captures these keystrokes in the background.
6. The client periodically beacons this captured data over HTTP to the C2 server, using randomized "jitter" to make the traffic less predictable. If no keys are pressed, it sends a [HEARTBEAT] message.
7. The server receives the data at its /report endpoint, logs it to c2_log.csv, and makes it available via a real-time API.
8. You can view the captured keystrokes on the web dashboard at http://127.0.0.1:5000.

---

Key Features

• Cross-Platform Compatibility: Manages process lifecycle and terminal launching across Windows, macOS, and Linux.
• Real-Time Dashboard: A clean web interface shows captured keystrokes as they arrive, fetching them from a live API.
• Jittered Beaconing: The client implant adds random delays to its communication schedule to avoid predictable network patterns, a common technique used by real malware.
• Safe Demonstration Environment: Uses an automated typing simulator with defanged samples (harmless text that looks like sensitive data) and a separate text editor to prevent accidental command execution.
• Automated Orchestration: The RUN_ME.py script handles the setup and teardown of all components for a smooth user experience.

---

Project Components

Core Components

• server.py: A Flask-based C2 server that listens for connections, receives data from the client at a /report endpoint, stores all received data in c2_log.csv, and serves the web dashboard.
• client.py: The simulated malware implant. It uses pynput to implement a sophisticated keylogger that captures keystrokes, handles special keys, and beacons the data to the server.
• type_simulator.py: An automated utility that simulates realistic human typing to provide sample data for the keylogger to capture safely.

Web Interface

• templates/dashboard.html: A clean, Bootstrap-based HTML file for the C2 dashboard.
• static/script.js: JavaScript that handles real-time log fetching from the /api/logs endpoint and safely escapes HTML to render the data correctly.

Orchestration & Storage

• RUN_ME.py: The master orchestration script. It uses the rich library to provide a user-friendly CLI menu for starting and stopping the entire simulation, managing all processes for a clean shutdown.
• c2_log.csv: A simple CSV file where the server logs all incoming data, including a timestamp, source IP, implant ID, and the keystroke data itself.

---

Security Considerations

This project is designed with safety and education at its core.

• Plaintext Data: Placeholder encryption functions are included to show where they would fit in a real-world tool, but data is sent in plaintext for educational clarity.
• Defanged Samples: The typing simulator uses harmless text samples that look like commands or sensitive data but cannot be executed accidentally.
• Clear Warnings: The tool provides explicit warnings about its keylogging functionality to ensure users are fully aware of its operation.

---

Setup & Usage

1. Clone the repository (if applicable).

2. Install dependencies:

It is highly recommended to use a virtual environment.

python -m venv .venv
source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
pip install -r requirements.txt

3. Run the Project Manager:

   python RUN_ME.py

4. Start the Simulation:

   • From the menu in your terminal, choose option 1 and press Enter.
   • This will open new terminal windows for the server and client, open a text editor, and start the typing simulator.
   • Important: The text editor window must remain in focus for the typing simulation to work correctly.

5. View the Dashboard:

   • Open your web browser and navigate to: http://127.0.0.1:5000
   • You will see the keystrokes from the simulator appear in the log.

6. Stop the Simulation:

   • Return to the original terminal where you ran RUN_ME.py.
   • Choose option 2 and press Enter to terminate all related processes.