Skip to content

README.md

Latest commit

 

History

History
174 lines (136 loc) · 5.93 KB

README.md

File metadata and controls

174 lines (136 loc) · 5.93 KB

QuicC2Py

Project Overview

QuicC2Py is an advanced, modular proof-of-concept implementation of a Command-and-Control (C2) system built using Python's asyncio framework over UDP. Designed primarily for educational purposes and authorized security testing, this project features an extensible client-server architecture secured with AES encryption, ideal for exploring network security, penetration testing, and protocol development.

Future Goal: Transition to QUIC Protocol

While QuicC2Py currently operates over UDP with manual AES-CBC encryption to provide a functional and educational Command-and-Control (C2) demonstration, the long-term goal is to transition to the QUIC protocol for enhanced performance and security. QUIC, built on UDP, offers built-in TLS 1.3 encryption, stream multiplexing, and features like 0-RTT connection establishment, making it a superior choice for modern network applications. Initial attempts to implement QUIC using Python's aioquic library faced challenges with certificate compatibility and stability, leading to the current UDP-based solution. Future development aims to leverage a stable QUIC implementation—potentially using Go's quic-go library—to fully realize these advanced capabilities, aligning QuicC2Py with cutting-edge networking standards while maintaining its educational focus.

Features

  • UDP-based Communication: Efficient, low-latency, connectionless communication.
  • AES Encryption: AES-CBC with 256-bit key (hardcoded for demo).
  • Interactive Command Interface: Real-time server-side interaction.
  • Supported Commands:
    • whoami: Get current username.
    • dir: Directory listing (Windows).
    • ls: Directory listing placeholder (Linux).
    • info: System info.
    • upload <filename>: Client uploads file (string-based).
    • download <filename>: Server file download (basic implementation).
    • help: List available commands.
    • exit: Graceful shutdown.
  • Modular Design: Modules include config, crypto, commands, protocol.
  • Logging: Actions logged to logs/udp_c2.log.
  • Configuration File: Settings in config.json.
  • Cross-Platform: Compatible with Windows/Linux.
  • Unit Tests: Preliminary tests (tests/) included.

Potential Use Cases

  • Security Research: Analyze C2 traffic patterns.
  • Traffic Obfuscation: Experiment with cloud-based obfuscation (Dropbox, AWS).
  • File Transfer Experiments: Enhance binary transfer capabilities.
  • Protocol Development: Simulate advanced protocol features (QUIC-like).
  • Penetration Testing Training: Implement persistence and stealth features.
  • Educational Tool: Teaching network security and cryptography.

Prerequisites

  • Python 3.8+
  • Dependencies:
    • cryptography
    • pytest (optional)
  • Network: UDP port 4433 (configurable in config.json).
  • Operating System: Tested on Windows/Linux; macOS may need adjustments.

Installation

  1. Clone the Repository:

    git clone https://github.com/KW-Soft/QuicC2Py.git
cd QuicC2Py

  2. Install Dependencies:

    pip install -r requirements.txt

    If not running tests, pip install cryptography is sufficient.

  3. Verify Configuration:

    • Check config.json for host, port, encryption settings.

Usage

Detailed usage in docs/usage.md.

Quick Start Guide

Start Server:

python src/server.py

Server example output:

[Server] QuicC2Py is running on 0.0.0.0:4433...
[Server] Enter command (type 'help' for list, 'exit' to quit):

Start Client:

python src/client.py

Client example output:

[Client] Connecting to localhost:4433...
[Client] Sent: Agent ready!

Interact with Clients (Server-side):

[Server] Enter command: whoami
[Server] Command sent to ('127.0.0.1', 54321): whoami
[Server] Received from ('127.0.0.1', 54321): desktop-XXX\xxxx

Run Tests (optional):

pytest tests/

Directory Structure

QuicC2Py/
├── src/
│   ├── server.py
│   ├── client.py
│   ├── config.py
│   ├── crypto.py
│   ├── protocol.py
│   └── commands.py
├── tests/
│   ├── test_crypto.py
│   └── test_commands.py
├── docs/
│   ├── architecture.md
│   └── usage.md
├── logs/ (created at runtime)
│   └── udp_c2.log
├── config.json
├── requirements.txt
└── README.md

Security Warning

Important: QuicC2Py is intended only for educational and authorized security testing within controlled, permissioned environments. Never use in unauthorized or production environments.

  • AES keys and IV are hardcoded (not secure).
  • No authentication or integrity protection.
  • Misuse can result in criminal liability.

Always:

  • Obtain explicit permission before testing.
  • Comply with local laws and ethical guidelines.
  • Consider secure enhancements (dynamic keys, DTLS).

Limitations

  • Encryption: Hardcoded AES keys.
  • File Transfers: Basic text-based handling.
  • Scalability: Single-threaded.
  • Platform Support: Some commands unimplemented.
  • Error Handling: Limited robustness.

Future Enhancements

  • DTLS Integration: Secure UDP.
  • Binary File Transfers: Improve file handling.
  • Dynamic Key Exchange: Diffie-Hellman implementation.
  • Client Authentication: Identity verification.
  • Multi-threading: Concurrent client management.
  • Cloud Integration: Enhanced obfuscation.

Contributing

Contributions welcome!

  1. Fork repository and create a feature branch.
  2. Follow PEP 8 guidelines.
  3. Update/add tests in tests/.
  4. Submit pull requests clearly describing changes.

Report bugs or request features by opening a GitHub issue.

License

MIT License (LICENSE).

Disclaimer

The software is provided "as is," without any warranty. Users assume full responsibility. Unauthorized or malicious use strictly prohibited.