Skip to content
BisaamPublic

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

packetlab

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.


Table of contents

  1. Installation
  2. Quick start: TCP
  3. Quick start: UDP
  4. Starting listeners
  5. Payload formats
  6. The Wireshark workflow
  7. TCP vs UDP
  8. Socket mode vs raw mode
  9. TLS/SSL experiments
  10. HTTP experiments
  11. Privileges
  12. Platform differences
  13. Limitations
  14. Project layout
  15. Testing

Installation

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 --help

Standalone binary (no Python required)

If you'd rather have a single executable file you can run directly (./packetlab ...) without a venv or Python on the target machine:

./build_binary.sh

This 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 S

Raw 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.

Quick start: TCP

In one terminal, start a listener:

packetlab tcp listen --port 9999

In 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.

Quick start: UDP

packetlab udp listen --port 9999
packetlab 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).

Starting listeners

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.

Payload formats

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).

The Wireshark workflow

A complete first exercise:

  1. Start a UDP listener:
    packetlab udp listen --port 9999
  2. Start Wireshark and capture the loopback interface (lo on Linux, lo0 on macOS -- packetlab interfaces lists what your OS calls it). Use the capture filter packetlab prints for you, e.g. udp port 9999.
  3. Send:
    packetlab udp send --host 127.0.0.1 --port 9999 --data "Hello"
  4. 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.
  5. Repeat with TCP: stop the UDP listener, run packetlab tcp listen --port 9999 and packetlab tcp send --host 127.0.0.1 --port 9999 --data "Hello" with a tcp port 9999 capture filter.
  6. 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".
  7. 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 vs UDP

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 5 deliberately calls send() 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 application send() 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 each recvfrom() 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 send to 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, which packetlab udp send --timeout <seconds> can sometimes observe (by connect()-ing the UDP socket first, which lets that ICMP error surface as ConnectionRefusedError on some platforms) -- but this is not guaranteed and is genuinely platform-dependent; see Platform differences.

Socket mode vs raw mode

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.

TLS/SSL experiments

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).

HTTP experiments

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.0

Compare 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.

Privileges

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

Platform differences

  • Linux: raw packet injection uses AF_PACKET (layer 2) or a raw IP socket (layer 3); both need CAP_NET_RAW, in practice root (or sudo setcap cap_net_raw+ep on 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 as ConnectionRefusedError (used by packetlab 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 interfaces uses socket.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; use ip addr (Linux) or ifconfig (macOS) for that detail.

Limitations

  • packetlab is a learning tool, not nmap/hping3/scapy itself. 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 or tcpdump for 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 N sends 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 --count loop.
  • --writes N demonstrates that TCP doesn't preserve send() 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 / ssl2 never completes a real handshake on modern systems -- OpenSSL has disabled or removed those versions entirely. It sends a hand-crafted ClientHello over a real TCP connection so you can see the bytes and the peer's rejection, nothing more; see TLS/SSL experiments.
  • packetlab tls generate-cert shells out to the system openssl CLI (stdlib has no X.509 generation); if it's not on PATH, supply your own --cert/--key to tls listen instead.
  • packetlab http gives you raw request-header control to construct ambiguous framing (e.g. conflicting Content-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.

Project layout

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/

Testing

pip install -e ".[dev]"
pytest

All 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.

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages