wa1kpcap 0.1.0__tar.gz

wa1kpcap-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,90 @@
+name: Build & Publish
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build-sdist:
+    name: Build sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build sdist
+        run: pipx run build --sdist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  build-wheels:
+    name: Build wheels (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.21
+        env:
+          CIBW_BUILD: "cp310-* cp311-* cp312-* cp313-*"
+          CIBW_SKIP: "*-musllinux_i686 *-manylinux_i686 *-win32"
+          CIBW_ARCHS_LINUX: "x86_64"
+          CIBW_ARCHS_MACOS: "x86_64 arm64"
+          CIBW_ARCHS_WINDOWS: "AMD64"
+          CIBW_BUILD_VERBOSITY: 1
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  publish:
+    name: Publish to PyPI
+    needs: [build-sdist, build-wheels]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: [publish]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+
+      - name: Extract latest release notes
+        run: |
+          awk '/^## v/{if(found) exit; found=1} found' CHANGELOG.md > RELEASE_NOTES.tmp
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          body_path: RELEASE_NOTES.tmp

wa1kpcap-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,49 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - '.github/workflows/**'
+      - '*.md'
+      - 'LICENSE'
+      - 'MANIFEST.in'
+      - 'examples/**'
+      - 'skills/**'
+      - 'docs/**'
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - '.github/workflows/**'
+      - '*.md'
+      - 'LICENSE'
+      - 'MANIFEST.in'
+      - 'examples/**'
+      - 'skills/**'
+      - 'docs/**'
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install build dependencies
+        run: pip install scikit-build-core pybind11 cmake ninja
+
+      - name: Install package with dev dependencies
+        run: pip install -e ".[dev,dpkt]"
+
+      - name: Run tests
+        run: python -m pytest tests/ -x -q

wa1kpcap-0.1.0/.gitignore

@@ -0,0 +1,82 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Native build artifacts
+*.pyd
+*.dll
+*.exe
+*.obj
+*.o
+*.a
+*.lib
+
+# CMake
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake
+Makefile
+
+# Misc
+*.log
+*.tmp
+.DS_Store
+Thumbs.db
+nul
+
+# Data files
+*.pcap
+*.pcapng
+*.npz
+!test/*.pcap
+
+# Scratch scripts & docs
+extract_*.py
+benchmark*
+docs/*
+!docs/README.md
+!docs/README_CN.md
+
+# Planning files
+task_plan.md
+findings.md
+progress.md
+
+# Internal-only skills (keep locally, don't commit)
+.claude/

wa1kpcap-0.1.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## v0.1.0 (2026-02-20)
+
+Initial release.
+
+### Features
+
+- Dual-engine architecture: native C++ engine (default) and dpkt fallback
+- Flow-level feature extraction with signed directional 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
+- BPF filter with protocol-aware keywords (dhcp, dhcpv6, vlan, gre, vxlan, mpls)
+- Application layer parsing control: full / port_only / none
+- IP fragment, TCP stream, and TLS record reassembly
+- Export to pandas DataFrame, CSV, JSON
+- Custom incremental feature registration via BaseIncrementalFeature
+- YAML-based protocol extension for the native engine
+
+### Supported 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
+
+### Supported Platforms
+
+- Python 3.10 - 3.13
+- Linux (x86_64, aarch64), macOS (x86_64, arm64), Windows (AMD64)

wa1kpcap-0.1.0/CLAUDE.md

@@ -0,0 +1,175 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Environment
+
+- Conda environment: `web` (Python 3.10).
+- Python executable: `D:/miniconda3/envs/web/python.exe`
+- Platform: Windows 11. Claude Code uses Git Bash (Unix syntax). All shell commands in this file use bash syntax.
+- In Git Bash, `conda activate` is typically unavailable. Use `python`/`pip` directly (they should already point to the conda env). If `python` is not in PATH or points to the wrong env, fall back to the full path: `"D:/miniconda3/envs/web/python.exe"` and `"D:/miniconda3/envs/web/python.exe" -m pip`.
+
+## Language
+
+  - Respond in Chinese (中文) for explanatory, discussion, or conversational replies.
+  - Internal thinking, code, comments, and commit messages can remain in English.
+
+## Build & Install
+
+The project uses scikit-build-core with CMake for the optional C++ native engine.
+
+```bash
+# Install Python package (dpkt engine only)
+pip install -e .
+
+# Install with native C++ engine
+rm -rf build/cp310-cp310-win_amd64/*
+pip install ".[native]" --force-reinstall --no-deps --no-cache-dir
+
+# After native build, copy .pyd into source tree (editable install loads from source tree, not site-packages)
+cp "/d/miniconda3/envs/web/Lib/site-packages/wa1kpcap/_wa1kpcap_native.cp310-win_amd64.pyd" "/d/MyProgram/wa1kpcap1/wa1kpcap/"
+```
+
+The C++ build requires CMake 3.15+, C++17, and fetches yaml-cpp 0.8.0 via FetchContent. pybind11 provides the Python bindings.
+
+### MSVC Build Quirks
+
+- `NOMINMAX` must be defined before any Windows headers to prevent `min`/`max` macro conflicts with STL and pybind11. `bindings.cpp` also `#undef`s leaked macros and provides `dabs()`/`dmax()` replacements.
+- Use `Py_ssize_t` instead of `ssize_t` (not available on MSVC).
+- `src/cpp/CMakeLists.txt` sets `CMAKE_POLICY_VERSION_MINIMUM 3.5` to allow yaml-cpp 0.8.0's old `cmake_minimum_required` to work under CMake 4.0+.
+
+## Tests
+
+```bash
+# Run all tests
+python -m pytest tests/ -x -q
+
+# Run a single test file
+python -m pytest tests/test_flow.py -x -q
+
+# Run a specific test
+python -m pytest tests/test_flow.py::TestFlowManager::test_add_packet -x -q
+
+# Benchmark dpkt vs native vs flowcontainer
+python benchmark.py              # full: consistency check + speed benchmark + report
+python benchmark.py consistency  # consistency check only (dpkt vs native vs flowcontainer on test/multi.pcap)
+python benchmark.py speed        # speed benchmark only (per-file dpkt vs native vs flowcontainer on datasets)
+python benchmark.py lite-speed   # quick dpkt vs native speed comparison on a few specific pcap files
+```
+
+Coverage is 68% (4958 statements, 1575 missed). There are 331 tests across 18 test files (329 passed, 2 skipped).
+
+`benchmark.py` compares wa1kpcap's dpkt engine, native C++ engine, and flowcontainer. It has four modes:
+- `all` (default): runs both consistency check and speed benchmark, writes a markdown report to `benchmark_report.md`.
+- `consistency`: compares flow extraction results (5-tuple matching, IAT comparison) between dpkt, native, and flowcontainer on `test/multi.pcap`.
+- `speed`: benchmarks per-file throughput (time, flows, MB/s, speedup) across datasets configured in `DATASETS`.
+- `lite-speed`: quick dpkt vs native comparison on a few hardcoded pcap files (no report file).
+
+## Architecture
+
+### Dual Engine Design
+
+The library has two independent parsing engines selected via `Wa1kPcap(engine="dpkt"|"native")`:
+
+- **dpkt engine** (default): Uses the dpkt library for protocol parsing. Code path: `analyzer.py:_process_reader()` → `_parse_protocols()` using handlers in `wa1kpcap/protocols/`.
+- **native engine**: C++ pybind11 module (`_wa1kpcap_native`) driven by YAML protocol configs. Code path: `analyzer.py:_process_native()` → `NativeEngine.read_and_parse()` → C++ `NativeParser.parse_to_dataclass()` which constructs Python dataclasses directly in C++ (bypasses dict + `converter.py`).
+
+Both engines feed into the same Python flow management pipeline: `FlowManager` groups packets into bidirectional `Flow` objects, `FeatureExtractor` computes sequence/statistical features, and exporters produce DataFrame/CSV/JSON output.
+
+### C++ Native Engine (`src/cpp/`)
+
+The C++ engine is YAML-configuration-driven with 10 parsing primitives: `fixed`, `bitfield`, `length_prefixed`, `computed`, `tlv`, `counted_list`, `rest`, `hardcoded`, `prefixed_list`, `repeat`. Protocol definitions live in `wa1kpcap/native/protocols/*.yaml`.
+
+Key mechanisms in `protocol_engine.cpp`:
+- `header_size_field`: After parsing fixed fields, adjusts `bytes_consumed` to the computed header size (handles IP/TCP options).
+- `total_length_field`: Bounds `remaining` bytes to IP total_length, excluding Ethernet padding.
+- Computed fields (type `COMPUTED`) must evaluate even when `offset >= len` — they consume 0 bytes but produce values like `flags` and `header_length` that downstream logic depends on.
+- `parse_packet()` chains layers via `next_protocol` mappings until no more protocols match or data runs out.
+- `prefixed_list` primitive: length-prefixed item list with optional TLV dispatch. Two modes: Mode A (typed items) reads `[total_len][type][len][data]...` and dispatches sub-protocols via `type_mapping`; Mode B (simple) reads `[total_len][item_len][data]...` with `item_format`. Sub-protocol fields are merged into the parent FieldMap with a prefix (e.g., `tls_ext_sni.server_name`). Used by `tls_client_hello.yaml` and `tls_server_hello.yaml` to parse TLS extensions via YAML instead of hardcoded C++.
+- TLS is NOT chained from TCP via `next_protocol` — TCP's YAML has no next_protocol to TLS. Instead, TLS is parsed via a separate reassembly path: Python buffers TCP payloads, extracts complete TLS records, then calls C++ `NativeParser.parse_tls_record()` which uses `parse_from_protocol_struct("tls_record", ...)` to parse starting from the TLS layer.
+
+#### Dispatch Tables
+
+The engine uses `unordered_map` dispatch tables (populated in the `ProtocolEngine` constructor) instead of if-else chains:
+
+- `fast_dispatch_` (`std::unordered_map<std::string, FastParseFn>`): maps protocol name → fast-path parser. Unified signature: `FastResult(const uint8_t* buf, size_t len, size_t remaining, NativeParsedPacket& pkt)`. Only Type A protocols register here.
+- `fill_dispatch_` (`std::unordered_map<std::string, std::function<void(SlowFillContext&)>>`): maps protocol name → fill function. Both Type A and Type B protocols register here. `SlowFillContext` carries `pkt`, `fields`, `cur`, `bytes_consumed`, `remaining`, `has_tls`, `tls_layers`, `proto_name`.
+
+New built-in protocols register by adding lambdas in the constructor. Some protocols have special fill logic (TCP/UDP compute `app_len`, TLS sub-layers store into `tls_layers` for deferred processing).
+
+#### Two Built-in Protocol Subtypes
+
+- **Type A: Fast-Path** — has both `fast_parse_xxx()` (raw byte parsing, registered in `fast_dispatch_`) and `fill_xxx()` (registered in `fill_dispatch_`). For simple fixed-layout wire formats. Current: Ethernet, IPv4, IPv6, TCP, UDP, ARP, ICMP, ICMPv6.
+- **Type B: Fill-Only** — has only `fill_xxx()` (registered in `fill_dispatch_`). YAML engine handles all parsing; fill copies fields into the C++ struct. For complex variable formats. Current: DNS, TLS series (tls_stream, tls_record, tls_handshake, tls_client_hello, tls_server_hello, tls_certificate).
+
+Rule of thumb: if you can parse with pointer arithmetic in < 50 lines of C++, use Type A. If parsing needs TLV, compression, counted lists — use Type B.
+
+#### Profiling Infrastructure
+
+Built-in timing instrumentation controlled by a global flag:
+
+- `g_profiling_enabled` (bool): global toggle, default `false`.
+- `g_prof` (`ProfilingStats`): atomic counters for `total_ns`, `parse_layer_ns`, `fill_struct_ns`, `next_proto_ns`, `fieldmap_insert_ns`, `total_packets`, `total_layers`, plus per-primitive counters (`fixed_ns`/`fixed_count`, `bitfield_ns`/`bitfield_count`, etc.).
+- `ScopedTimer`: RAII timer that accumulates nanoseconds into a target `std::atomic<uint64_t>` when `g_profiling_enabled` is true.
+- Python API (exposed in `bindings.cpp`): `profiling_enable()`, `profiling_disable()`, `profiling_reset()`, `profiling_get_stats()` → returns dict with all counters.
+
+The fast path (`parse_to_dataclass` in `bindings.cpp`) parses to a C++ `NativeParsedPacket` struct, then constructs Python dataclasses directly with positional args (cached class references, pre-cached constants like `py::none()` and `py::bytes("")`). The legacy path (`parse_packet` → `py::dict` → `converter.py`) is only used for fallback BPF app-layer filtering.
+
+`NativeParsedPacket` (`parsed_packet.h`) embeds all sub-structs (NativeIPInfo, NativeTCPInfo, etc.) directly — no heap allocation. Presence flags (`has_eth`, `has_ip`, etc.) replace nullptr checks. pybind11 bindings return `py::none()` when the flag is false. Unknown protocols parsed by YAML are stored in `extra_layers` (a `std::map<std::string, FieldMap>`), converted to Python dicts in `build_dataclass_from_struct`, and passed to `ParsedPacket.__init__` which wraps them in `ProtocolInfo` instances via `ProtocolRegistry`.
+
+### ProtocolInfo & Extensibility (`wa1kpcap/core/packet.py`)
+
+Protocol layer data uses a two-tier class hierarchy under a common `_ProtocolInfoBase`:
+
+- **Built-in protocols** (`EthernetInfo`, `IPInfo`, `TCPInfo`, `UDPInfo`, `TLSInfo`, `DNSInfo`, `HTTPInfo`, etc.) inherit from `_SlottedInfoBase(_ProtocolInfoBase)` and store fields as direct `__slots__` attributes for performance (~40% faster construction than dict-based). Each class defines `__slots__`, `_SLOT_NAMES`, and `_SLOT_DEFAULTS`. The `_fields` property returns a dict view of all slots for compatibility.
+- **Custom/user protocols** inherit from `ProtocolInfo(_ProtocolInfoBase)` and use a `_fields` dict as source of truth, with typed property accessors.
+
+`ParsedPacket.layers` is a `dict[str, _ProtocolInfoBase]` keyed by protocol name; legacy properties like `pkt.ip`, `pkt.tls` are aliases into this dict. The `isinstance` check in `_aggregate_flow_info()` uses `_ProtocolInfoBase` (the common ancestor).
+
+To add a new protocol without modifying C++:
+1. Create `<name>.yaml` in `wa1kpcap/native/protocols/` (or a custom directory).
+2. Write a `ProtocolInfo` subclass with typed properties and a `merge()` method.
+3. Register it: `ProtocolRegistry.get_instance().register('<name>', MyProtoInfo, yaml_path="/path/to/myproto.yaml", routing={"udp": {5000: "myproto"}})`.
+4. `NativeEngine` auto-loads `yaml_path` files and injects `routing` mappings at init time — no need to modify built-in YAML files.
+
+All fast-path parsers (ethernet, ipv4, ipv6, tcp, udp, vlan, sll, sll2) have YAML fallback: when the hardcoded switch doesn't match, they query `yaml_next_protocol_lookup()` against the YAML `next_protocol.mapping`. This means injected routing works for both fast-path and slow-path protocols. C++ also exposes `NativeParser.load_extra_file()` and `NativeParser.add_protocol_routing()` for direct use.
+
+To add a new built-in protocol (with C++ fast path):
+1. Follow the steps in `docs/add-builtin-protocol-guide.md` or use `/add-builtin-protocol`.
+2. The Python Info class must inherit `_SlottedInfoBase` with `__slots__` direct attributes (not `ProtocolInfo` with `_fields` dict).
+
+Known protocols use dispatch table lookups (`fast_dispatch_` / `fill_dispatch_`) for optimized C++ struct fill. Unknown protocols go through `extra_layers` → `ProtocolRegistry` lookup → `ProtocolInfo` construction. If no class is registered, a generic `ProtocolInfo(fields=dict)` is used as fallback.
+
+Flow-level aggregation in `analyzer.py:_aggregate_flow_info()` iterates `pkt.layers` generically: first packet's layer is `copy()`'d, subsequent packets' layers are `merge()`'d. The `copy()` is a selective shallow copy (one-level `list()`/`dict()` for mutables, direct reference for scalars) — not `deepcopy`.
+
+### Flow Management (`wa1kpcap/core/flow.py`)
+
+- `FlowKey`: 5-tuple (src_ip, dst_ip, src_port, dst_port, protocol), normalized so the same pair always maps to the same flow regardless of direction.
+- `Flow`: Bidirectional flow with TCP state machine (SYN_SENT → ESTABLISHED → FIN_WAIT → CLOSED etc.). First packet determines "up" direction.
+- Signed packet lengths: positive = client-to-server (up), negative = server-to-client (down).
+- TCP retransmission detection (`_check_retransmission` in analyzer.py) uses per-direction sequence number tracking.
+
+### Reassembly Pipeline
+
+`IPFragmentReassembler` → `TCPStreamReassembler` → `TLSRecordReassembler`. For the native engine, `FlowBuffer` bridges Python TCP reassembly with C++ application-layer parsing.
+
+### Feature Extraction (`wa1kpcap/features/`)
+
+Sequence features: `packet_lengths`, `ip_lengths`, `trans_lengths`, `app_lengths`, `timestamps`, `iats`, `tcp_flags`, `tcp_window_sizes`. Statistical features computed from sequences: mean, std, var, min, max, range, median, skew, kurtosis, cv — with directional (up/down) variants.
+
+`compute_array_stats` in `bindings.cpp` provides a C++ single-pass implementation (O(n) median via `nth_element`) that `_compute_array_stats()` in `extractor.py` calls when the native module is available, with a pure-Python fallback.
+
+## YAML Protocol Configs
+
+Located in `wa1kpcap/native/protocols/`. When adding a new protocol:
+1. Create `<name>.yaml` with `name`, `fields` (using the 10 primitives), and optionally `next_protocol`, `header_size_field`, `total_length_field`.
+2. Add the DLT or next_protocol mapping that routes to it.
+3. If the protocol has variable-length headers, declare `header_size_field` pointing to a computed field.
+4. If the protocol carries a total length (like IPv4/IPv6), declare `total_length_field` to prevent Ethernet padding from inflating payload sizes.
+
+## Conventions
+
+- All protocol parsing in the dpkt path goes through handler classes in `wa1kpcap/protocols/` registered via `ProtocolHandlerRegistry`.
+- `ParsedPacket` is the universal packet representation shared by both engines.
+- The `wa1kpcap/__init__.py` re-exports all public API symbols — new public classes should be added to `__all__` there.
+- Test pcap fixtures are referenced from `tests/conftest.py`.

wa1kpcap-0.1.0/CMakeLists.txt

@@ -0,0 +1,12 @@
+cmake_minimum_required(VERSION 3.15)
+project(wa1kpcap_native LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+option(BUILD_NATIVE "Build native C++ engine" ON)
+
+if(BUILD_NATIVE)
+    add_subdirectory(src/cpp)
+endif()

wa1kpcap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ljs_2002
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wa1kpcap-0.1.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include LICENSE
+include README.md
+include CMakeLists.txt
+
+# C++ source
+recursive-include src/cpp *.h *.hpp *.cpp *.c
+
+# YAML protocol definitions
+recursive-include wa1kpcap *.yaml
+
+# pybind11 build support
+include pyproject.toml

wa1kpcap-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: wa1kpcap
+Version: 0.1.0
+Summary: Dual-engine PCAP analysis library for flow-level feature extraction and protocol parsing
+Keywords: pcap,network,traffic,flow,packet,protocol,tls,dns,feature-extraction,nids
+Author-Email: 1in_js <ljs_2002@163.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: Topic :: Scientific/Engineering
+Project-URL: Homepage, https://github.com/ljs-2002/wa1kpcap
+Project-URL: Repository, https://github.com/ljs-2002/wa1kpcap
+Project-URL: Issues, https://github.com/ljs-2002/wa1kpcap/issues
+Requires-Python: >=3.10
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: numpy>=1.23
+Provides-Extra: dpkt
+Requires-Dist: dpkt>=1.9; extra == "dpkt"
+Provides-Extra: export
+Requires-Dist: pandas>=1.5; extra == "export"
+Provides-Extra: crypto
+Requires-Dist: cryptography>=41.0; extra == "crypto"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: scapy>=2.5; extra == "dev"
+Requires-Dist: pandas>=1.5; extra == "dev"
+Requires-Dist: cryptography>=41.0; extra == "dev"
+Description-Content-Type: text/markdown
+
+# wa1kpcap
+
+[中文文档](README_CN.md)
+
+Dual-engine PCAP analysis library for Python. Extracts flow-level features and protocol fields from network traffic captures using a native C++ engine (default) or dpkt as fallback.
+
+## Installation
+
+```bash
+pip install wa1kpcap
+```
+
+Optional dependencies:
+
+```bash
+pip install wa1kpcap[dpkt]      # dpkt engine support
+pip install wa1kpcap[export]    # pandas DataFrame export
+pip install wa1kpcap[crypto]    # TLS certificate parsing
+pip install wa1kpcap[dev]       # development (pytest, scapy, etc.)
+```
+
+## Quick Start
+
+```python
+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 |
+
+All protocols have C++ fast-path implementations. Tunnel protocols (GRE, VXLAN, MPLS) support recursive inner-packet dispatch.
+
+## Features
+
+- Dual engine: native C++ (default) or dpkt fallback
+- Flow-level feature extraction with signed directional 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 directional breakdowns
+- BPF filter with protocol-aware keywords (dhcp, dhcpv6, vlan, gre, vxlan, mpls)
+- Application layer parsing control: full / port_only / none
+- IP/TCP/TLS reassembly
+- Export to DataFrame, CSV, JSON
+- Custom incremental feature registration
+- YAML-based protocol extension
+
+## Documentation
+
+For detailed usage, API reference, and examples, see [docs/README.md](docs/README.md).
+
+## License
+
+MIT License
+
+## Author
+
+1in_js

wa1kpcap-0.1.0/README.md

@@ -0,0 +1,69 @@
+# wa1kpcap
+
+[中文文档](README_CN.md)
+
+Dual-engine PCAP analysis library for Python. Extracts flow-level features and protocol fields from network traffic captures using a native C++ engine (default) or dpkt as fallback.
+
+## Installation
+
+```bash
+pip install wa1kpcap
+```
+
+Optional dependencies:
+
+```bash
+pip install wa1kpcap[dpkt]      # dpkt engine support
+pip install wa1kpcap[export]    # pandas DataFrame export
+pip install wa1kpcap[crypto]    # TLS certificate parsing
+pip install wa1kpcap[dev]       # development (pytest, scapy, etc.)
+```
+
+## Quick Start
+
+```python
+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 |
+
+All protocols have C++ fast-path implementations. Tunnel protocols (GRE, VXLAN, MPLS) support recursive inner-packet dispatch.
+
+## Features
+
+- Dual engine: native C++ (default) or dpkt fallback
+- Flow-level feature extraction with signed directional 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 directional breakdowns
+- BPF filter with protocol-aware keywords (dhcp, dhcpv6, vlan, gre, vxlan, mpls)
+- Application layer parsing control: full / port_only / none
+- IP/TCP/TLS reassembly
+- Export to DataFrame, CSV, JSON
+- Custom incremental feature registration
+- YAML-based protocol extension
+
+## Documentation
+
+For detailed usage, API reference, and examples, see [docs/README.md](docs/README.md).
+
+## License
+
+MIT License
+
+## Author
+
+1in_js