wa1kpcap 0.2.0

Efficient, extensible, out-of-the-box PCAP analysis library — extract flow-level features and multi-layer protocol fields from network traffic captures

wa1kpcap

中文文档

Efficient, extensible, out-of-the-box PCAP analysis library for Python. Extracts multi-level flow features and protocol fields across all layers from network traffic captures, powered by a C++ engine.

Installation

pip install wa1kpcap

Optional dependencies:

pip install wa1kpcap[export]    # pandas DataFrame export
pip install wa1kpcap[crypto]    # TLS certificate parsing
pip install wa1kpcap[dev]       # development (pytest, scapy, etc.)

Quick Start

from wa1kpcap import Wa1kPcap

analyzer = Wa1kPcap()
flows = analyzer.analyze_file('traffic.pcap')

for flow in flows:
    print(f"{flow.key}  packets={flow.packet_count}  duration={flow.duration:.3f}s")

Supported Protocols

Layer	Protocols
Link	Ethernet, VLAN (802.1Q), Linux SLL/SLL2, Raw IP, BSD Loopback, NFLOG
Network	IPv4, IPv6, ARP, ICMP, ICMPv6
Tunnel	GRE, VXLAN, MPLS
Transport	TCP, UDP
Application	TLS (SNI/ALPN/certs), DNS, HTTP, DHCP, DHCPv6, QUIC (Initial decryption, SNI/ALPN)

All protocols have C++ fast-path implementations. Tunnel protocols (GRE, VXLAN, MPLS) support recursive inner-packet dispatch.

Features

• Fast C++ native parsing engine with Python API
• Flow-level feature extraction with signed directional packet lengths
• 8 sequence features per flow: packet_lengths, ip_lengths, trans_lengths, app_lengths, timestamps, iats, tcp_flags, tcp_window_sizes
• Statistical aggregation: mean, std, var, min, max, range, median, skew, kurt, cv, plus up/down directional breakdowns
• Multi-layer protocol field extraction from link layer to application layer
• BPF filter with protocol-aware keywords (dhcp, dhcpv6, vlan, gre, vxlan, mpls)
• Cross-packet reassembly: IP fragments, TCP streams, TLS records, QUIC CRYPTO frames
• Export to DataFrame, CSV, JSON
• Custom incremental feature registration
• YAML-based protocol extension for adding new protocols without C++ code

Documentation

For detailed usage, API reference, and examples, see docs/README.md.

Roadmap

• More protocol support (QUIC 0-RTT/Handshake, HTTP/3, SSH, SMTP, SIP, etc.)
• Field masking in raw bytes (zero/random/fixed value) to prevent model overfitting on specific fields
• CLI tool for quick pcap inspection
• Multi-process parallel parsing for large captures

Test Coverage

License

MIT License

Author

1in_js