RootWire

Un monitor del traffico di rete per GNU/Linux — precedentemente noto come Packet-Sniffer. I frame vengono catturati da una o più interfacce di rete tramite un raw socket, con timestamp generato dal kernel stesso, decodificati strato per strato con la libreria NETProtocols, e visualizzati in tempo reale, scritti in un file pcap a precisione nanosecondo, oppure trasmessi in streaming come JSON:

[>] Frame #4 at 15:42:07 (wlan0, 74 bytes)
    [+] Ethernet 3c:7c:3f:1a:be:22 -> 9c:1e:95:aa:01:5f
        EtherType: IPv4
    [+] IPv4 192.168.1.96 -> 142.250.79.78
        TTL: 64 | Flags: Don't fragment (DF) | Total Length: 60 | ID: 39754
        Protocol: TCP | Checksum: 0x2b51
    [+] TCP 51888 -> 443
        Flags: 0x002 (SYN) | Seq: 3598801521 | Ack: 0
        Window: 64240 | Checksum: 0x2008
        Options: Maximum Segment Size (1460), SACK Permitted, Timestamps (3644437524, 0), No-Operation, Window Scale (7)

Il decoder copre Ethernet (tag VLAN 802.1Q, incluso il tagging QinQ annidato), ARP, IPv4 (opzioni decodificate e frammenti), IPv6 inclusi gli header di estensione (un report MLD mostra l'intera catena Hop-by-Hop) e Neighbor Discovery (una Router/Neighbor Solicitation o Advertisement mostra il suo indirizzo target e le opzioni di link-layer), ICMPv4/v6, TCP (offset del payload consapevoli delle opzioni, opzioni decodificate) e UDP. Ogni checksum IPv4/ICMPv4/ICMPv6/TCP/UDP viene verificato tramite ricalcolo, segnalando inline una mancata corrispondenza (Checksum: 0x0000 [!] mismatch (expected 0x1a2b)) — un segnale reale per traffico corrotto o falsificato, silenzioso per un frammento non riassemblato, dove il checksum sul filo copre un datagramma che RootWire non ricostruisce mai. I frame malformati o troncati vengono diagnosticati invece di far crashare la cattura, i protocolli sconosciuti terminano la catena in modo controllato, e un limite di 16 strati impedisce che stack di header di estensione artificiosi amplifichino — la cattura sopravvive a qualunque cosa la rete consegni.

Installazione

pipx install rootwire        # or: uv tool install rootwire

Oppure esegui da un clone con uv:

git clone https://github.com/EONRaider/RootWire.git
cd RootWire
uv sync

Utilizzo

rootwire [-h] [-i INTERFACE] [-r FILE] [-w FILE]
         [--filter NAME_OR_EXPR] [--json] [-d] [--version]

options:
  -i, --interface   interface to capture frames from; repeat to capture on
                    several interfaces concurrently (default: all interfaces)
  -r, --read FILE   replay frames from a pcap or pcapng file instead of live
                    capture (no privileges required; mutually exclusive
                    with -i)
  -w, --write FILE  also write every captured frame to a classic pcap file
  --filter NAME_OR_EXPR
                    attach a kernel-side capture filter so only matching
                    frames reach userspace: a canned name (arp, ip6, tcp,
                    udp) or a filter expression -- protocols tcp/udp/icmp/
                    arp/ip/ip6; host/port, each optionally prefixed with
                    src/dst; and/or/not; parentheses (e.g. "tcp and port
                    80"); live capture only
  --json            one NDJSON object per frame on stdout (banner and
                    statistics stay on stderr): pipe straight into jq
  -d, --data        also display each frame's raw payload (ignored with --json)

Le statistiche di cattura — frame, byte, frame/s, conteggi di malformati/troncati, conteggi per protocollo — vengono riportate su stderr al termine della cattura, che si tratti di Ctrl-C, SIGTERM, o (per -r) fine del file: tutti e tre attivano lo stesso arresto pulito. Alcune combinazioni preferite:

sudo rootwire -i eth0 -w session.pcap             # capture and keep the evidence
sudo rootwire -i eth0 --filter tcp                # drop non-TCP in the kernel
sudo rootwire -i eth0 --filter "tcp and port 80"  # kernel-side filter expression
sudo rootwire -i eth0 -i wlan0                    # merge two interfaces into one stream
rootwire -r session.pcap                          # inspect it later, no root
rootwire -r session.pcap --json | jq .            # machine-readable analysis

La cattura live richiede un raw socket, che su Linux significa root (sudo rootwire -i eth0) oppure concedere all'interprete la capability CAP_NET_RAW. La riproduzione di file con -r non richiede mai privilegi. Da un clone, eseguilo come sudo .venv/bin/python -m rootwire.

Come funziona

La funzione capture_async() di capture.py produce frame grezzi — uniti da un socket AF_PACKET per interfaccia, ciascuno con timestamp generato dal kernel stesso all'arrivo (SO_TIMESTAMPNS, non una lettura dell'orologio in userspace) — come triple (bytes, timestamp, interface); la riproduzione da file con -r adatta i frame di pcap.py in quella stessa forma prima che entrambe le sorgenti raggiungano decoder.py, che percorre la catena di protocolli di ogni frame in un immutabile DecodedFrame. Gli output — il renderer a schermo, lo stream NDJSON, il writer pcap, il collettore di statistiche — consumano ogni frame attraverso un'unica piccola interfaccia Output. Il tour completo, incluso il motivo per cui la memoria rimane stabile durante catture prolungate e come aggiungere un output, è in ARCHITECTURE.md.

Tutto tranne il raw socket funziona su qualsiasi OS, quindi la suite di test — che include un corpus di 65 frame di traffico reale catturato, riprodotto attraverso l'intera pipeline — non richiede né root né Linux:

uv run pytest

Contribuire

Segnalazioni di bug e pull request sono benvenute. CONTRIBUTING.md copre la configurazione di sviluppo, i controlli eseguiti dalla CI, e come appare una buona pull request qui.

Disclaimer Legale

L'uso del codice contenuto in questo repository, in parte o nella sua totalità, per attaccare target senza previo consenso reciproco è illegale. È responsabilità dell'utente finale rispettare tutte le leggi locali, statali e federali applicabili.

Gli sviluppatori non si assumono alcuna responsabilità e non sono responsabili per usi impropri o danni causati da qualsiasi codice contenuto in questo repository nel caso in cui, accidentalmente o altrimenti, esso venga utilizzato da un agente di minaccia o entità non autorizzata come mezzo per compromettere la sicurezza, la privacy, la riservatezza, l'integrità e/o la disponibilità di sistemi e delle loro risorse associate. In questo contesto il termine "compromettere" è da intendersi come l'utilizzo dello sfruttamento di vulnerabilità note o sconosciute presenti in detti sistemi, includendo, ma non limitandosi a, l'implementazione di controlli di sicurezza, di natura umana o elettronica.

Packet-Sniffer