packetlab is a small command-line laboratory for learning how TCP and UDP actually behave, by sending real traffic on your own machine and watching it in Wireshark.
It is not a network scanner, not a stress-testing tool, and not a production networking library. It exists to make specific experiments easy:
- Send
"Hello"over TCP. Send the exact same bytes over UDP. Compare. - Send arbitrary hex bytes, binary files, or generated payloads.
- Watch what a TCP three-way handshake looks like, and what UDP's absence of one looks like.
- Split one payload into many
send()calls and see that TCP doesn't preserve message boundaries. - Generate payloads bigger than one Ethernet frame and watch fragmentation.
- Once you understand sockets, drop down a level: hand-craft Ethernet/IP/ TCP/UDP headers yourself with Scapy and see what changes (and what a crafted packet can't do that a real connection can).
- Encrypt a connection with TLS, then pick an old, deprecated version (SSLv3, TLS 1.0/1.1) and see how a modern peer reacts to it.
- Send HTTP/0.9, HTTP/1.0, and HTTP/1.1 requests with their exact historical wire formats and compare what each one exposes in plaintext versus over TLS.
Every default targets 127.0.0.1. This is a lab, not a scanner: only
point it at hosts you own or are explicitly authorized to test.
- Installation
- Quick start: TCP
- Quick start: UDP
- Starting listeners
- Payload formats
- The Wireshark workflow
- TCP vs UDP
- Socket mode vs raw mode
- TLS/SSL experiments
- HTTP experiments
- Privileges
- Platform differences
- Limitations
- Project layout
- Testing
Requires Python 3.10+.
python3 -m venv .venv
source .venv/bin/activate
pip install -e .Socket-mode experiments (packetlab tcp, packetlab udp) need nothing
beyond the standard library. Raw packet crafting (packetlab raw) needs
Scapy, installed as an optional extra so the
beginner workflow stays dependency-free:
pip install -e ".[raw]"Verify it's on your PATH:
packetlab --helpIf you'd rather have a single executable file you can run directly
(./packetlab ...) without a venv or Python on the target machine:
./build_binary.shThis uses PyInstaller to bundle the
interpreter, packetlab, and Scapy into dist/packetlab (dist/packetlab.exe
on Windows). Copy that one file anywhere and run it:
./dist/packetlab --help
./dist/packetlab tcp send --port 9999 --data "Hello"
sudo ./dist/packetlab raw tcp send --dst-ip 127.0.0.1 --dst-port 9999 --flags SRaw mode inside the binary still needs root/Administrator at run time -- bundling the interpreter doesn't change OS-level privilege requirements. The binary is platform-specific: build it on (or for) the OS you intend to run it on.
In one terminal, start a listener:
packetlab tcp listen --port 9999In another terminal:
packetlab tcp send --host 127.0.0.1 --port 9999 --data "Hello"The listener prints the connecting address, how many bytes it received,
and the payload as ASCII and hex. packetlab tcp send opens a real TCP
connection (three-way handshake included), sends the bytes, waits
briefly for a reply, then closes the connection.
packetlab udp listen --port 9999packetlab udp send --host 127.0.0.1 --port 9999 --data "Hello"Same payload, same ports-style command -- but there's no handshake, and
if nothing is listening, packetlab udp send doesn't necessarily know
that (see TCP vs UDP).
packetlab tcp listen --port 9999 [--host 0.0.0.0] [--count N]
packetlab udp listen --port 9999 [--host 0.0.0.0] [--count N]--count stops the listener after N connections/datagrams; omit it to
run until you press Ctrl+C. Every accepted TCP connection or received UDP
datagram is printed as:
Connection received (or "Datagram received" for UDP)
Source:
127.0.0.1:54321
Destination:
127.0.0.1:9999
Received:
5 bytes
ASCII:
Hello
Hex:
48 65 6c 6c 6f
The TCP listener reads until the peer closes the connection and reports everything received as one block -- see TCP vs UDP for why.
Every send (and packetlab inspect) command accepts exactly one of:
--data "Hello" # text string (see --encoding)
--hex "48 65 6c 6c 6f" # or "48656c6c6f" -- spaces/colons/commas all fine
--file ./payload.bin # raw bytes from a file
--stdin # raw bytes from stdin: cat payload.bin | packetlab udp send --stdin ...
--size 1400 [--pattern AA] # generated payload: incrementing counter by default, or a repeated byte pattern--data is encoded as UTF-8 by default; --encoding ascii and
--encoding latin-1 are also accepted (both map bytes 0-255 one-to-one,
which is handy when you want precise control over byte values via text).
Inspect any payload without sending anything:
packetlab inspect --data "Hello"Payload
-------
Length: 5 bytes
ASCII:
Hello
Hex:
48 65 6c 6c 6f
Binary:
01001000 01100101 01101100 01101100 01101111
Add --show-payload to any send command to print this same block
before transmitting. Large payloads are truncated to --preview-size
bytes (default 64; inspect defaults to 256; <=0 disables truncation).
A complete first exercise:
- Start a UDP listener:
packetlab udp listen --port 9999
- Start Wireshark and capture the loopback interface (
loon Linux,lo0on macOS --packetlab interfaceslists what your OS calls it). Use the capture filter packetlab prints for you, e.g.udp port 9999. - Send:
packetlab udp send --host 127.0.0.1 --port 9999 --data "Hello" - Inspect the packet in Wireshark. On loopback you'll see a Linux "cooked capture" or loopback pseudo-header instead of a real Ethernet frame, then IPv4, then UDP, then your 5 bytes of data. Click through each layer in the packet details pane.
- Repeat with TCP: stop the UDP listener, run
packetlab tcp listen --port 9999andpacketlab tcp send --host 127.0.0.1 --port 9999 --data "Hello"with atcp port 9999capture filter. - Compare the headers. UDP: source port, destination port, length, checksum -- 8 bytes, that's it. TCP: sequence number, acknowledgment number, flags, window size, options -- and multiple packets (SYN, SYN-ACK, ACK, your data, FIN/ACK...) for one logical "send".
- Right-click a TCP packet → Follow → TCP Stream. Wireshark reassembles the whole byte stream for you, because TCP itself doesn't mark message boundaries -- Wireshark can only show you bytes in order, not where one "message" ended and the next began. Try the same right-click on a UDP packet: there's no "UDP Stream" reconstruction in the same sense, because each datagram already is a discrete message; Wireshark's UDP stream view just lists the individual datagrams.
Run packetlab experiment compare --tcp-port 9001 --udp-port 9002 --data "Hello" to send the same bytes over both protocols in one shot, with a
combined capture filter printed for you.
TCP is like an ongoing phone call: you dial, the other side picks up, and then you have a continuous conversation where both sides know what's been said. UDP is like sending postcards: each one is independent, none of them are guaranteed to arrive, and nothing tells you if one gets lost.
Technically:
- TCP establishes a connection (three-way handshake: SYN, SYN-ACK,
ACK) before any application data flows, and closes it explicitly when
done. It exposes a byte stream to the application, not a sequence
of messages:
packetlab tcp send --writes 5deliberately callssend()five times, but the OS is free to combine those calls into fewer TCP segments, split them into more, or delay them (Nagle's algorithm) -- there is no guaranteed 1:1 relationship between applicationsend()calls and TCP segments on the wire. TCP guarantees reliable, ordered delivery of that byte stream to the receiving application -- not delivery of any particular packet. - UDP has no handshake and no connection state. Each
sendto()call produces exactly one datagram, and eachrecvfrom()on the other end returns exactly one datagram (or none) -- datagram boundaries are preserved end-to-end. What UDP does not provide is reliability, ordering, or retransmission: a datagram can be dropped, duplicated, or reordered, and neither side is told. (A UDP datagram larger than the path MTU can still be fragmented at the IP layer into multiple IP packets -- that's IP fragmentation, a lower-layer concern, not UDP losing its own boundary semantics.) - Because UDP has no handshake,
packetlab udp sendto a port nobody is listening on will often appear to "succeed" -- the datagram left your machine. Some OSes will send back an ICMP "port unreachable" message, whichpacketlab udp send --timeout <seconds>can sometimes observe (byconnect()-ing the UDP socket first, which lets that ICMP error surface asConnectionRefusedErroron some platforms) -- but this is not guaranteed and is genuinely platform-dependent; see Platform differences.
packetlab has two completely separate code paths, and it always tells you which one you're using:
Application
|
TCP / UDP <- packetlab tcp / packetlab udp: you hand the OS bytes,
| the OS handles the rest.
IP
|
Network interface
Application data
|
TCP / UDP header <- packetlab raw: you construct every header field
| yourself and hand the finished packet to the
IP header interface. Nothing here is a real TCP connection --
| see the printed warning every time you run it.
Ethernet header
|
Network interface
packetlab tcp / packetlab udp use Python's standard socket module.
You control the payload, the ports, and a handful of options the OS
exposes (SO_KEEPALIVE, SO_BROADCAST, source port binding). You do
not control individual header bits -- there is no --ttl on
packetlab tcp send, because a normal TCP socket doesn't expose one.
packetlab raw tcp send / packetlab raw udp send use
Scapy to build an Ethernet/IP/TCP-or-UDP packet
field-by-field and inject it directly. You can set the TTL, IP
identification, TCP sequence/ack numbers, flags, window size, checksums
-- almost everything. This is not a TCP connection. A crafted SYN
packet has the SYN bit set and nothing else: no state is tracked, no
SYN-ACK is handled, no handshake completes. If a real reply does come
back, your own OS kernel's TCP stack will likely see it, fail to
recognize it as belonging to any connection it knows about, and send a
RST -- a common and confusing artifact when experimenting with crafted
SYNs on a machine that's also running a normal network stack. For an
actual TCP conversation, use packetlab tcp send.
Checksums and lengths are computed automatically by default in raw mode
(they depend on the IP layer via a pseudo-header, so Scapy computes them
at send time). You can override them explicitly (--tcp-checksum,
--udp-checksum, --ip-checksum, --udp-length) to build a
deliberately invalid packet and see how the receiving OS / Wireshark
reacts -- most stacks silently discard a bad-checksum packet.
packetlab tls speaks TLS/SSL at an explicitly chosen version, over a real
TCP connection. Unlike raw mode, it needs no elevated privileges --
it's never forging IP/Ethernet headers, only the application-visible TLS
layer.
Two tiers, selected automatically by --tls-version:
| Version | Tier | What actually happens |
|---|---|---|
tls1.3, tls1.2 |
real | A genuine handshake via Python's stdlib ssl (OpenSSL). Works out of the box on virtually any modern system. |
tls1.1, tls1.0 |
real | Genuine handshake, but deprecated by browsers/IETF since 2020 (RFC 8996) -- may be refused by strict peers or a hardened local OpenSSL policy. |
ssl3 |
crafted | OpenSSL has disabled SSLv3 by default since POODLE (2015, RFC 7568), so a real handshake essentially cannot happen. packetlab instead hand-builds an SSLv3-format ClientHello (via struct, no extra dependency) and sends it as the payload of a real TCP connection. |
ssl2 |
crafted | SSLv2 has been formally prohibited since 2011 (RFC 6176) and removed entirely from modern OpenSSL/Python. packetlab hand-builds it in SSLv2's own historical (pre-TLS-record) wire format. |
Quick start:
# Generate a throwaway self-signed lab certificate (needs system `openssl`)
packetlab tls generate-cert --out-dir ./certs
# Terminal 1: a real TLS server
packetlab tls listen --port 9443 --cert ./certs/cert.pem --key ./certs/key.pem
# Terminal 2: a real TLS1.3 handshake
packetlab tls send --host 127.0.0.1 --port 9443 --tls-version tls1.3 --data "Hello"
# Now try a version the server (and OpenSSL) won't really negotiate
packetlab tls send --host 127.0.0.1 --port 9443 --tls-version ssl3 --data "Hello"The ssl3/ssl2 send prints CRAFTED_TLS_NOTE every time so it's never
mistaken for a completed handshake -- watch Wireshark: you'll see a normal
TCP three-way handshake, then a ClientHello with the legacy version
field, then (almost always) the peer immediately sending a TLS alert
(commonly protocol_version) or resetting the connection.
Certificate verification is off by default (--verify to turn it on,
--ca-file to point at a CA), because the point of tls listen is a
throwaway self-signed lab certificate. Never disable verification against
a real service. --ciphers lets you force a specific OpenSSL cipher list
for weak-cipher experiments (RC4/NULL/export-grade suites are often
compiled out of modern OpenSSL entirely -- that itself is worth observing).
packetlab http send builds the exact wire bytes for a chosen HTTP
version -- not just a version string, the actual historical framing:
| Version | What's different | Why it matters |
|---|---|---|
0.9 |
Bare request line only: GET /\r\n. No headers, no version token, no status line in the response. Only GET was ever defined. |
No way to send Host, cookies, or auth at all -- the original 1991 protocol. |
1.0 |
Adds headers/version/status line, but Host is optional. |
A server hosting multiple sites on one IP can't reliably tell which one was requested -- the ambiguity behind virtual-host confusion. packetlab http send --http-version 1.0 does not add a Host header for you, on purpose. |
1.1 |
Host is mandatory (added automatically); persistent connections; chunked Transfer-Encoding. |
Supplying conflicting Content-Length and Transfer-Encoding headers yourself (via --header, repeatable) recreates the ambiguous framing behind HTTP request-smuggling bug classes -- observe how your own listener parses it. packetlab doesn't ship a canned "attack," just the raw header control. |
# Plaintext HTTP/1.1
packetlab http send --host 127.0.0.1 --port 8000 --path / --http-version 1.1
# The same request over TLS (reuse the `packetlab tls listen --port 9443`
# from the TLS/SSL experiments section above)
packetlab http send --host 127.0.0.1 --port 9443 --path / --tls --tls-version tls1.3
# HTTP/0.9: watch how little information even leaves the machine
packetlab http send --host 127.0.0.1 --port 8000 --http-version 0.9
# HTTP/1.0 without a Host header, against a multi-site-capable server
packetlab http send --host 127.0.0.1 --port 8000 --http-version 1.0Compare the same request as plain HTTP and as HTTPS in Wireshark: the HTTPS capture shows only opaque encrypted TLS records, while the plaintext capture shows the full request and response text, headers included -- a direct, visual argument for why HTTPS matters.
| Operation | Needs elevated privileges? |
|---|---|
packetlab tcp send / udp send to a port >= 1024 |
No |
packetlab tcp listen / udp listen on a port >= 1024 |
No |
Binding to a port < 1024 (--source-port, listen --port) |
Yes, on Linux/macOS |
packetlab raw tcp send / raw udp send (any port) |
Yes, on every supported platform |
packetlab raw ... --interface ... (Ethernet layer) |
Yes, plus a valid interface |
packetlab raw ... --dry-run |
No -- dry-run never touches the network or requires Scapy's privileged codepath |
packetlab raw ... --pcap FILE (writing the .pcap) |
No -- writing a file needs no special privileges, only sending does |
packetlab tls send / tls listen / http send (any version, any port >= 1024) |
No -- these only touch application-layer bytes over a normal TCP connection, never raw IP/Ethernet |
packetlab tls generate-cert |
No, but requires the system openssl CLI on PATH |
When a privileged operation is attempted without the right permissions,
packetlab explains what's missing and how to fix it instead of leaking a
bare OSError traceback:
[!] Raw packet injection requires elevated privileges on Linux.
This operation is unavailable through the current user's privileges. Try
re-running with elevated privileges, e.g.:
sudo packetlab raw tcp send --dst-ip 127.0.0.1 --dst-port 9999 --flags S
- Linux: raw packet injection uses
AF_PACKET(layer 2) or a raw IP socket (layer 3); both needCAP_NET_RAW, in practice root (orsudo setcap cap_net_raw+epon the interpreter). Loopback captures show a Linux "cooked capture" pseudo-header instead of a real Ethernet frame. - macOS: raw sockets go through BPF (
/dev/bpfN) for layer 2 and a raw IP socket for layer 3; both need root. Loopback traffic uses a 4-byte loopback header, not Ethernet. - Windows: raw TCP/UDP socket construction has been deliberately restricted by Microsoft since Windows XP SP2. Scapy's Windows support goes through Npcap and needs Administrator privileges, and even then some raw operations are unreliable. packetlab detects Windows and surfaces this as an explicit limitation rather than pretending raw mode works the same way it does on Linux/macOS.
- UDP "connection refused" via ICMP: whether a
connect()-ed UDP socket surfaces an ICMP port-unreachable error asConnectionRefusedError(used bypacketlab udp send --timeout) depends on the OS and its ICMP rate-limiting/filtering behavior. Don't rely on it as a reliability mechanism -- it's an experiment, not a guarantee. - Interface enumeration:
packetlab interfacesusessocket.if_nameindex(), which works cross-platform for interface names. It deliberately does not attempt to list IP/MAC addresses per interface, since that requires different, platform-specific code on each OS; useip addr(Linux) orifconfig(macOS) for that detail.
- packetlab is a learning tool, not
nmap/hping3/scapyitself. Raw mode is intentionally scoped to constructing and sending individual packets -- there's no port scanning, no TCP state machine, no evasion techniques, and no sniffing/receive path for raw mode (use Wireshark ortcpdumpfor capture). For pentest engagements or CTFs, the analyzing-network-packets-with-scapy and analyzing-network-traffic-with-wireshark skills go further. packetlab udp send --count Nsends the same payload bytes N times; it doesn't currently vary the payload per datagram.- Repeated TCP sends (
--count N) open N separate connections; packetlab does not keep one connection open across a--countloop. --writes Ndemonstrates that TCP doesn't preservesend()boundaries -- it is not, and does not claim to be, a way to control segmentation.- Nothing in this tool will make a raw crafted packet behave like a real connection; see Socket mode vs raw mode.
packetlab tls send --tls-version ssl3/ssl2never completes a real handshake on modern systems -- OpenSSL has disabled or removed those versions entirely. It sends a hand-craftedClientHelloover a real TCP connection so you can see the bytes and the peer's rejection, nothing more; see TLS/SSL experiments.packetlab tls generate-certshells out to the systemopensslCLI (stdlib has no X.509 generation); if it's not onPATH, supply your own--cert/--keytotls listeninstead.packetlab httpgives you raw request-header control to construct ambiguous framing (e.g. conflictingContent-Length/Transfer-Encoding) for observation against your own listener -- it does not ship a request-smuggling "attack" against arbitrary targets.- This is an educational lab, not a hardened network tool: don't point it at systems you don't own or have explicit authorization to test, and it is not designed for stealth, IDS/IPS evasion, credential interception, or exploitation of third-party systems.
packetlab/
├── pyproject.toml
├── README.md
├── SPEC.md
├── LICENSE
├── src/packetlab/
│ ├── cli.py argparse wiring for every subcommand
│ ├── payload.py payload sourcing (data/hex/file/stdin/size) + formatting
│ ├── tcp.py socket-mode TCP sender/listener
│ ├── udp.py socket-mode UDP sender/listener
│ ├── tls.py TLS/SSL sender/listener: real handshake (TLS1.0-1.3) + crafted legacy ClientHello (SSLv3/SSLv2)
│ ├── http.py HTTP/0.9-1.1 request building, delegates transport to tcp.py/tls.py
│ ├── display.py payload inspection, dry-run rendering, Wireshark hints
│ ├── interfaces.py network interface enumeration
│ ├── experiments.py higher-level commands (e.g. `experiment compare`)
│ ├── errors.py shared error types + OSError/ssl.SSLError -> friendly message translation
│ └── raw/ Scapy-based raw packet crafting, isolated from tcp.py/udp.py
│ ├── common.py privilege checks, scapy import, transmit, pcap writing
│ ├── ethernet.py
│ ├── ip.py
│ ├── tcp.py
│ └── udp.py
├── tests/
│ ├── test_payload.py
│ ├── test_tcp.py (127.0.0.1 only)
│ ├── test_udp.py (127.0.0.1 only)
│ ├── test_tls.py (127.0.0.1 only; real-handshake tests skip without system openssl)
│ ├── test_http.py (127.0.0.1 only)
│ ├── test_cli.py
│ └── test_raw.py packet construction always runs; transmission skipped without root+scapy
└── docs/experiments/
pip install -e ".[dev]"
pytestAll tests run against 127.0.0.1 only -- no public internet access is
required or used. Raw-packet transmission tests are skipped
automatically unless both Scapy is installed and the test is run as
root/Administrator; packet construction (building the header fields)
is still tested unconditionally whenever Scapy is available. TLS
real-handshake round-trip tests are skipped automatically if the system
openssl CLI isn't on PATH (needed to generate a throwaway test
certificate); the crafted-ClientHello byte-layout tests always run, since
they touch neither openssl nor the network stack in any special way.