{"id":27494720,"url":"https://github.com/kw-soft/quicc2py","last_synced_at":"2025-07-26T23:33:01.227Z","repository":{"id":283106253,"uuid":"950699725","full_name":"kw-soft/QuicC2Py","owner":"kw-soft","description":"QuicC2Py is an advanced, modular proof-of-concept implementation of a Command-and-Control (C2) system over UDP","archived":false,"fork":false,"pushed_at":"2025-03-18T15:43:20.000Z","size":14,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-17T14:16:58.896Z","etag":null,"topics":["aes-encryption","c2","commandandcontrol","pentest","pentesting","python","quic","remote-code-execution","remote-control","udp-protocol","udp-server"],"latest_commit_sha":null,"homepage":"https://github.com/kw-soft/QuicC2Py","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kw-soft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-18T14:57:59.000Z","updated_at":"2025-03-25T09:29:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"6d239c95-3949-465e-bc97-0e5ffac9cf29","html_url":"https://github.com/kw-soft/QuicC2Py","commit_stats":null,"previous_names":["kw-soft/quicc2py"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kw-soft/QuicC2Py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kw-soft%2FQuicC2Py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kw-soft%2FQuicC2Py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kw-soft%2FQuicC2Py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kw-soft%2FQuicC2Py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kw-soft","download_url":"https://codeload.github.com/kw-soft/QuicC2Py/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kw-soft%2FQuicC2Py/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267264756,"owners_count":24061423,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-26T02:00:08.937Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aes-encryption","c2","commandandcontrol","pentest","pentesting","python","quic","remote-code-execution","remote-control","udp-protocol","udp-server"],"created_at":"2025-04-17T02:11:20.448Z","updated_at":"2025-07-26T23:33:01.221Z","avatar_url":"https://github.com/kw-soft.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# QuicC2Py\n\n## Project Overview\n**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.\n\n## Future Goal: Transition to QUIC Protocol\nWhile 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.\n\n## Features\n\n- **UDP-based Communication**: Efficient, low-latency, connectionless communication.\n- **AES Encryption**: AES-CBC with 256-bit key (hardcoded for demo).\n- **Interactive Command Interface**: Real-time server-side interaction.\n- **Supported Commands**:\n  - `whoami`: Get current username.\n  - `dir`: Directory listing (Windows).\n  - `ls`: Directory listing placeholder (Linux).\n  - `info`: System info.\n  - `upload \u003cfilename\u003e`: Client uploads file (string-based).\n  - `download \u003cfilename\u003e`: Server file download (basic implementation).\n  - `help`: List available commands.\n  - `exit`: Graceful shutdown.\n- **Modular Design**: Modules include `config`, `crypto`, `commands`, `protocol`.\n- **Logging**: Actions logged to `logs/udp_c2.log`.\n- **Configuration File**: Settings in `config.json`.\n- **Cross-Platform**: Compatible with Windows/Linux.\n- **Unit Tests**: Preliminary tests (`tests/`) included.\n\n## Potential Use Cases\n\n- **Security Research**: Analyze C2 traffic patterns.\n- **Traffic Obfuscation**: Experiment with cloud-based obfuscation (Dropbox, AWS).\n- **File Transfer Experiments**: Enhance binary transfer capabilities.\n- **Protocol Development**: Simulate advanced protocol features (QUIC-like).\n- **Penetration Testing Training**: Implement persistence and stealth features.\n- **Educational Tool**: Teaching network security and cryptography.\n\n## Prerequisites\n\n- **Python 3.8+**\n- **Dependencies**:\n  - `cryptography`\n  - `pytest` (optional)\n- **Network**: UDP port 4433 (configurable in `config.json`).\n- **Operating System**: Tested on Windows/Linux; macOS may need adjustments.\n\n## Installation\n\n1. **Clone the Repository**:\n   ```bash\n   git clone https://github.com/KW-Soft/QuicC2Py.git\n   cd QuicC2Py\n   ```\n\n2. **Install Dependencies**:\n   ```bash\n   pip install -r requirements.txt\n   ```\n   \u003e _If not running tests, `pip install cryptography` is sufficient._\n\n3. **Verify Configuration**:\n   - Check `config.json` for host, port, encryption settings.\n\n## Usage\n\nDetailed usage in [`docs/usage.md`](docs/usage.md).\n\n### Quick Start Guide\n\n**Start Server**:\n```bash\npython src/server.py\n```\nServer example output:\n```\n[Server] QuicC2Py is running on 0.0.0.0:4433...\n[Server] Enter command (type 'help' for list, 'exit' to quit):\n```\n\n**Start Client**:\n```bash\npython src/client.py\n```\nClient example output:\n```\n[Client] Connecting to localhost:4433...\n[Client] Sent: Agent ready!\n```\n\n**Interact with Clients** (Server-side):\n```\n[Server] Enter command: whoami\n[Server] Command sent to ('127.0.0.1', 54321): whoami\n[Server] Received from ('127.0.0.1', 54321): desktop-XXX\\xxxx\n```\n\n**Run Tests (optional)**:\n```bash\npytest tests/\n```\n\n## Directory Structure\n```\nQuicC2Py/\n├── src/\n│   ├── server.py\n│   ├── client.py\n│   ├── config.py\n│   ├── crypto.py\n│   ├── protocol.py\n│   └── commands.py\n├── tests/\n│   ├── test_crypto.py\n│   └── test_commands.py\n├── docs/\n│   ├── architecture.md\n│   └── usage.md\n├── logs/ (created at runtime)\n│   └── udp_c2.log\n├── config.json\n├── requirements.txt\n└── README.md\n```\n\n## Security Warning\n\n\u003e **Important**: **QuicC2Py** is intended **only** for educational and authorized security testing within controlled, permissioned environments. **Never** use in unauthorized or production environments.\n\n- AES keys and IV are hardcoded (not secure).\n- No authentication or integrity protection.\n- Misuse can result in criminal liability.\n\nAlways:\n\n- Obtain explicit permission before testing.\n- Comply with local laws and ethical guidelines.\n- Consider secure enhancements (dynamic keys, DTLS).\n\n## Limitations\n\n- **Encryption**: Hardcoded AES keys.\n- **File Transfers**: Basic text-based handling.\n- **Scalability**: Single-threaded.\n- **Platform Support**: Some commands unimplemented.\n- **Error Handling**: Limited robustness.\n\n## Future Enhancements\n\n- **DTLS Integration**: Secure UDP.\n- **Binary File Transfers**: Improve file handling.\n- **Dynamic Key Exchange**: Diffie-Hellman implementation.\n- **Client Authentication**: Identity verification.\n- **Multi-threading**: Concurrent client management.\n- **Cloud Integration**: Enhanced obfuscation.\n\n## Contributing\n\nContributions welcome!\n\n1. Fork repository and create a feature branch.\n2. Follow PEP 8 guidelines.\n3. Update/add tests in `tests/`.\n4. Submit pull requests clearly describing changes.\n\nReport bugs or request features by opening a GitHub issue.\n\n## License\n\nMIT License ([LICENSE](LICENSE)).\n\n## Disclaimer\n\nThe software is provided \"as is,\" without any warranty. Users assume full responsibility. Unauthorized or malicious use strictly prohibited.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkw-soft%2Fquicc2py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkw-soft%2Fquicc2py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkw-soft%2Fquicc2py/lists"}