Educational TCP backdoor lab

A small Python client/server pair that exists to teach one thing: how a classic reverse-shell architecture works, end to end, in stdlib-only code you can read in one sitting.

It is NOT a real command-and-control framework. It has no stealth, no persistence, no evasion, and no anti-forensics. Multiple clients can connect and are managed manually with clients / use N, but there is no automated mass-deployment or beacon-style targeting. If you want to do real offensive work, go to the platforms listed in docs/LEARNING_RESOURCES.md. This project is a teaching lab and stops there on purpose.

What you learn by reading this code

• TCP socket programming: socket.socket, bind, listen, accept, recv short-read semantics.
• Binary framing: why a length-prefixed header with a magic number and a version field is better than line-oriented text, and how to build one with struct. See protocol.py and docs/PROTOCOL.md.
• HMAC authentication: how a shared-secret challenge-response works, why hmac.compare_digest is timing-safe, why every challenge must be fresh. See auth.py.
• TLS: ssl.SSLContext, minimum version selection, cert pinning, and why we still add an application-layer auth on top. See tls_utils.py.
• Threading: one operator REPL thread plus one accept-loop thread plus shared state protected by locks. See backdoor_server.py.
• Python tooling: argparse, logging, dataclasses, type hints, pytest with socket.socketpair.

Every module has a docstring that explains why it exists. Read them in this order:

1. README.md (this file)
2. docs/ARCHITECTURE.md
3. docs/PROTOCOL.md
4. protocol.py
5. auth.py
6. tls_utils.py
7. backdoor_server.py
8. backdoor_client.py
9. tests/

Quick start

git clone https://github.com/kingoftech-v01/Backdoor_Project.git
cd Backdoor_Project
python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt

# Generate a self-signed cert for the TLS lab
python scripts/gen_selfsigned_cert.py

# Run the tests
pytest

Start the operator-side server (terminal 1):

python backdoor_server.py \
  --host 127.0.0.1 \
  --port 32000 \
  --secret lab-secret \
  --tls --cert certs/server.crt --key certs/server.key

Start the client (terminal 2, same machine):

python backdoor_client.py \
  --host 127.0.0.1 \
  --port 32000 \
  --secret lab-secret \
  --tls --ca certs/server.crt

At the operator prompt, try:

[1] 127.0.0.1:40000 Linux-6.x.x /tmp > infos
[1] 127.0.0.1:40000 Linux-6.x.x /tmp > pwd
[1] 127.0.0.1:40000 Linux-6.x.x /tmp > ls
[1] 127.0.0.1:40000 Linux-6.x.x /tmp > cd /tmp
[1] 127.0.0.1:40000 Linux-6.x.x /tmp > dl /etc/hostname
[1] 127.0.0.1:40000 Linux-6.x.x /tmp > capture screenshot
[1] 127.0.0.1:40000 Linux-6.x.x /tmp > clients
[1] 127.0.0.1:40000 Linux-6.x.x /tmp > help
[1] 127.0.0.1:40000 Linux-6.x.x /tmp > quit

Downloaded files and screenshots land in downloads/ on the operator side. The shell-passthrough (any unrecognised verb) runs on the client with a 30-second timeout.

Non-TLS mode (smaller, easier to trace in Wireshark)

If you want to watch the wire bytes go by in Wireshark or tcpdump, drop --tls on both sides. The auth handshake still works in the clear; only the command stream becomes readable. This is the best way to understand the framing. Capture with:

sudo tcpdump -i lo -w /tmp/capture.pcap port 32000

Open the capture in Wireshark and you can literally see the EDUB magic bytes, the version byte, the type byte, and the length field on each frame.

Operator command reference

These run locally at the operator REPL and are not sent to the client:

Command	What it does
help	List operator and client-side commands
clients	List connected client sessions
use N	Select client session N
quit	Close all sessions and exit

Anything else typed at the prompt is forwarded to the active client. The client-side commands are:

Command	What the client does
infos	Returns <platform> <cwd>
cd <dir>	chdir on the client, returns the new cwd
dl <path>	Reads the file and returns its bytes
capture <name>	Grabs a screenshot via Pillow, returns PNG bytes
<anything else>	Runs the line through the client's shell

How to read the tests

pytest                          # run everything
pytest tests/test_protocol.py   # framing only
pytest -k "handshake"           # auth handshake tests
pytest -v --tb=long             # verbose output

Over a hundred tests covering every production module at 100% branch coverage. Tests use socket.socketpair for in-memory roundtrips, threading for concurrent sender/receiver scenarios, and unittest.mock for handler edge cases. Requires pytest (see requirements-dev.txt). No real network is ever touched.

Project history and scope boundary

This project started as a 200-line script to learn socket programming. It has since been refactored into a small teaching lab with tests, documentation, and a real wire protocol. The intent has not changed: it is still a learning tool.

Features that will NOT be added (and why):

• Anti-AV / packing / obfuscation: the point is to show how things work, not to hide them.
• Persistence (registry run keys, cron, systemd, launchd): the client is supposed to exit when the operator disconnects or the user kills it. A student can implement persistence themselves if they want to learn the concept, but it will not ship here.
• Credential or browser secret dumping: out of scope for a networking tutorial.
• Lateral movement, SMB exploitation, mimikatz-style primitives: out of scope and the legal liability is real.
• C2 traffic blending (HTTPS beaconing, domain fronting, DNS tunnelling): transport is TCP with optional TLS. That is enough to teach the cryptography without pretending to be a real C2.

If any of those topics interest you, the platforms listed in docs/LEARNING_RESOURCES.md cover them in a legal, structured way.

Legal and ethical notice

This code is provided strictly for educational use on systems you own or have explicit, written authorisation to test. Running a backdoor against any other machine is a criminal offence under, at minimum:

• United States: Computer Fraud and Abuse Act (18 USC 1030)
• United Kingdom: Computer Misuse Act 1990
• Canada: Criminal Code section 342.1
• France: Articles 323-1 et seq. of the French Penal Code
• European Union: NIS2 Directive obligations

If you want to do offensive security work legally and get paid for it, see docs/LEARNING_RESOURCES.md for the major lab platforms (TryHackMe, HackTheBox, PortSwigger Web Security Academy, OffSec) and the reputable bug bounty programs (HackerOne, Bugcrowd, Intigriti, YesWeHack).

The author of this repository, the maintainers, and the platform used to build it take no responsibility for misuse. Run it on your own lab machines, then go learn the real craft on platforms that exist for exactly that purpose.

License

Distributed under the MIT License. See LICENSE for the full text.