ja4plus 1.0

Make the JA4+ fingerprints provably correct, make the library safe to run for a week, then publish version 1.0.0 with documentation that is true.

status: approved approved 2026-08-06 branch model: dev-and-live repo: Crank-Git/ja4plus 10 epics

Executive summary

ja4plus is a Python library and command-line program that reads network packets and produces JA4+ fingerprints. Version 0.6.0 is on PyPI. The codebase is 5,413 lines with 7,382 lines of tests, and 582 of its 584 tests pass today.

The problem is not that the project is unfinished. The problem is that its central claim — that a fingerprint matches the FoxIO reference — is not checked anywhere that can fail. The conformance suite exists, reads vectors that are downloaded on demand and excluded from version control, and never runs in continuous integration. Reading the code against the published FoxIO material found one method that is knowingly wrong, and a set of defects that only appear on traffic the vectors do not cover.

The plan sequences the work so each epic can fail loudly. Epic 0 builds the gates. Epic 1 makes the vectors pass. Epic 2 fixes what the vectors cannot see. Epic 3 bounds memory and states the concurrency contract. Epics 4 to 7 settle the interface. Epics 8 and 9 make the documentation true and publish version 1.0.0.

Goals

1. Every method matches the FoxIO reference on all 37 FoxIO vectors.
2. The conformance suite runs on every pull request and blocks a merge on failure.
3. The library holds bounded memory under a continuous packet stream.
4. The library states one thread-safety contract, and tests prove that contract.
5. No packet input crashes the library, including truncated and corrupt packets.
6. Test coverage is 90 percent or higher, measured by line.
7. The public interface carries type annotations, and mypy --strict passes.
8. Version 1.0.0 is on PyPI, with documentation published on GitHub Pages.
9. This project and the Go port emit the same fingerprint for every vector.

Non-goals

• JA4TScan. It is an active scanner and this project reads traffic only.
• Windows live capture. The monitor targets Linux and macOS.
• A fingerprint database service. The project reads FoxIO's mapping file.
• A throughput target. The project measures and reports; it sets no number.
• An asynchronous interface. The library stays synchronous.

Users

Architecture

A pure Python package with two runtime dependencies. A packet enters Processor.process_packet. The processor calls ten fingerprinters in a fixed order. Each reads the packet, updates its state table, and emits a fingerprint or nothing. The processor returns the collected results.

Verified against https://github.com/FoxIO-LLC/ja4 (retrieved 2026-08-06, upstream default branch at a commit dated 2026-07-21). Upstream PRs #297 and #299 since May 2026 change the Wireshark plugin and the README, not the fingerprint semantics — so the May 2026 baseline this project targets is still current.

Parity with ja4plus-go

A Go port exists at Crank-Git/ja4plus-go, worked in a separate session. processor.py:3 already states that this project mirrors it. Three rules govern the relationship.

1. FoxIO decides behavior. Where FoxIO specifies the output, the vectors decide, and this rule outranks the port.
2. The port decides interface. Where FoxIO specifies nothing — a field name, a subcommand, a default — the port has shipped a choice and this project adopts it rather than inventing a second one.
3. The gate is the shared vector set. Both repositories read the same 37 vectors at the same pinned commit. No test here builds, runs or imports the port; that would couple two repositories moving at different speeds and fail for reasons unrelated to the change under test.

This spec plans changes to this repository only. It records what the port should change and files nothing there.

Verified against https://github.com/Crank-Git/ja4plus-go (types.go, processor.go, lookup.go, ja4ssh.go, retrieved 2026-08-06, master at 2026-05-09).

Cross-cutting concerns

Epics

1. Foundation — Build the gates before any behavior changes, so every later epic has something that can fail. Vendor the 37 vectors, run conformance in CI, add ruff/mypy/coverage, raise the Python floor to 3.10, create dev.
2. Spec conformance — Make all 37 vectors pass. Fix the JA4SSH 200-packet window, expose JA4_o, use FoxIO's propagation-factor table, replace the surface-area parity tests.
3. Correctness audit — Fix the 14 registered defects the vectors cannot see: TCP sequence wraparound, quadratic reassembly, repeated JA4L client emission, duplicate cookie names, retained packet objects. Add the malformed-input suite.
4. Concurrency and resource safety — State the contract and prove it. Per-fingerprinter locks, bounded state tables with age and count limits, eviction on packet arrival, processor statistics.
5. Typed public interface — Frozen FingerprintResult matching the port's fields, mypy --strict, py.typed in the wheel, remove the collector.py module deprecated since 0.3.0.
6. Structured output — Separate address and port fields, a versioned JSON Lines and CSV schema, a fixed CSV header, results on stdout and diagnostics on stderr.
7. Live capture — Make the monitor a supported mode: ja4plus watch with connection eviction, signal handling, a clean flush on exit, and statistics.
8. Database enrichment — No network request without opt-in. Bulk lookup, a bounded cache, a recorded source per result.
9. Documentation — Correct the method-coverage claim, state the concurrency contract, run every code sample in CI, publish the mkdocs site.
10. Release — Verify the built wheel in a clean environment before publishing. Ship 1.0.0.

Milestones

Feature sets

00 — Foundation

17 requirements. Vendor the vectors with a NOTICE recording the upstream commit and FoxIO License 1.1 attribution; un-ignore them; run conformance, ruff, ruff format, mypy and coverage on every pull request; raise the floor to Python 3.10; pin every action to a commit; add Dependabot; fix the two tests that shell out to a bare python instead of sys.executable.

Key criteria: the conformance suite passes with no network access, and fails when it collects zero vectors — a silent skip is indistinguishable from a pass, which is how this gap survived.

01 — Spec conformance

12 requirements. All 37 vectors pass. JA4SSH emits every 200 SSH packets. JA4 and JA4S expose JA4_o. calculate_distance reads the propagation factor from FoxIO's hop-count table instead of hardcoding 1.6.

Key criteria: ssh.pcapng produces exactly one JA4SSH fingerprint equal to c36s36_c76s124_c0s0; tls12.pcap produces JA4_o = t13d1715h2_5b234860e130_014157ec0da2.

Eleven of the twelve FoxIO methods carry no complete text specification, and JA4 is the one method that holds one. Where a reader reads the image and finds it ambiguous, the expected-output files decide and the reading goes in docs/implementation_notes.md. An image nobody read reaches no fallback. docs/specs/foxio/README.md holds the inventory.

02 — Correctness audit

13 requirements over a 14-row audit register, each row citing a file and line. The register covers: 32-bit sequence wraparound in tcp_stream.py:53; the quadratic duplicate scan at :37; unbounded per-stream segment storage at :41; JA4L re-emitting a client fingerprint on every later ACK (ja4l.py:223); JA4H building its two cookie hashes from different cookie sets (ja4h.py:163); the dead identical branch at ja4.py:268; packet retention at base.py:38.

Key criteria: 10,000 segments on one stream complete in under a second; 100 post-handshake ACKs produce exactly one JA4L-C; every FoxIO malformed and crash capture, and a truncated copy of every capture, raise nothing.

03 — Concurrency and resource safety

15 requirements. One RLock per fingerprinter rather than one global lock, so ten threads can work on different methods at once. Eviction runs on packet arrival using the packet timestamp, not the wall clock — a capture replaying an hour in ten seconds would otherwise evict state it still needs. The library starts no thread.

Key criteria: eight threads on one processor for 60 seconds produce the same fingerprint set as one thread; a test that replaces the lock with an object which fails when acquired proves thread_safe=False acquires nothing.

04 — Typed public interface

13 requirements. A frozen FingerprintResult whose field names are the snake-case form of the port's struct — including type rather than method, because the port calls it Type. Item access survives one major version behind a DeprecationWarning.

Key criteria: mypy --strict clean; py.typed present in the wheel; import ja4plus.collector fails.

05 — Structured output

13 requirements. Addresses and ports as separate fields instead of one packed source string; a schema_version on every output line; a CSV header that is identical whatever flags were passed. The table format explicitly carries no stability promise; JSON Lines and CSV do.

Key criteria: the CSV header is byte-identical with and without --lookup; piping into head -1 produces no traceback.

06 — Live capture

14 requirements. ja4plus watch owns a connection table and calls cleanup_connection on eviction — today's ja4plus live never does. The privilege check attempts a capture rather than reading os.geteuid, because Linux can grant CAP_NET_RAW without granting user zero.

Key criteria: 100,000 packets across 50,000 connections hold the tracked count at or below the limit; SIGTERM exits zero with a complete output file.

07 — Database enrichment

15 requirements. --lookup becomes local-only; --lookup-remote opts into ja4db.com and prints a one-time notice naming the service. db update writes to the platform cache directory, never inside the installed package.

Key criteria: a test that fails on any outbound socket passes while the default client looks up 1,000 fingerprints.

08 — Documentation

15 requirements. The README states which of FoxIO's twelve methods are implemented and which are not, states the concurrency contract and the memory defaults, and every code sample in the README, docs/ and examples/ runs in CI. mkdocs build --strict fails on a broken link.

09 — Release

14 requirements. The version lives in one place. The publish workflow installs the built wheel into a clean environment, runs the CLI and the conformance suite against it, and publishes only if both pass — a partial publish to PyPI cannot be undone.

Mockups

Referenced by features/05-structured-output.md. Mockups are guidance, not a contract: they convey intent and roughly what a user sees. An implementer may diverge where the requirements and acceptance criteria are still met. The parts that are a contract — the CSV column order and the JSON field set — live in the feature file. If the frame below is blank, use the link above; a local file is an opaque origin and may not render in an iframe.

Assumptions

Open questions