{"id":51568633,"url":"https://github.com/refraction-networking/quic-fingerprint-conformance","last_synced_at":"2026-07-10T17:32:47.095Z","repository":{"id":366509517,"uuid":"1275209127","full_name":"refraction-networking/quic-fingerprint-conformance","owner":"refraction-networking","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-22T06:24:42.000Z","size":857,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-22T07:24:10.433Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/refraction-networking.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-20T11:51:43.000Z","updated_at":"2026-06-22T06:24:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/refraction-networking/quic-fingerprint-conformance","commit_stats":null,"previous_names":["refraction-networking/quic-fingerprint-conformance"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/refraction-networking/quic-fingerprint-conformance","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refraction-networking%2Fquic-fingerprint-conformance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refraction-networking%2Fquic-fingerprint-conformance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refraction-networking%2Fquic-fingerprint-conformance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refraction-networking%2Fquic-fingerprint-conformance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/refraction-networking","download_url":"https://codeload.github.com/refraction-networking/quic-fingerprint-conformance/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/refraction-networking%2Fquic-fingerprint-conformance/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35338653,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-10T02:00:06.465Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-10T17:32:45.926Z","updated_at":"2026-07-10T17:32:47.070Z","avatar_url":"https://github.com/refraction-networking.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# quic-fingerprint-conformance\n\nConformance contract and differential-testing harness for the three independent\nQUIC/TLS fingerprinters, ensuring they never silently diverge:\n\n| Implementation | Language | Repo |\n|---|---|---|\n| pyquicfp | Python | [refraction-networking/pyquicfp](https://github.com/refraction-networking/pyquicfp) |\n| clienthellod | Go | [refraction-networking/clienthellod](https://github.com/refraction-networking/clienthellod) |\n| retina-quic-fp | Rust | [refraction-networking/retina-quic-fp](https://github.com/refraction-networking/retina-quic-fp) |\n\nAll three must produce **byte-identical** fingerprints (the four hashes —\n`quic_header_fp`, `tls_fp`, `qtp_fp`, `super_fp` — plus the parsed feature fields)\nfor the same input.\n\n## The contract: `corpus/`\n\nEach case is an input pcap plus its **golden** (the expected canonical-record\noutput), committed to git:\n\n```\ncorpus/\u003ccase\u003e/\n  input.pcap      minimized to the QUIC Initial(s) — a few KB\n  expected.json   the golden: canonical records the impls must reproduce\n  meta.json       provenance: source, reference impl, grease mode\n```\n\nThe golden encodes the **consensus**: a case is promoted only after all impls\nagree on it (`harness.run`). To change the algorithm you must regenerate the\ngoldens (`harness.gen_golden --refresh`), review the diff, and bump the contract\n— so divergence is always a deliberate, reviewed event, never an accident.\n\n## Two test layers\n\n1. **Per-repo self-test (every PR, fast).** Each implementation's CI runs\n   `harness.check --impl \u003cimpl\u003e` against the pinned corpus. No cross-language\n   toolchain needed; catches that repo drifting from the contract.\n2. **Differential run (periodic, DPDK host).** `harness.run` executes all\n   available impls over the corpus and verifies they agree with each other —\n   catching anything a frozen golden might miss, and flagging real captures the\n   impls disagree on.\n\n`known_issues.py` registers *understood* divergences (e.g. retina keys\nconnections by 5-tuple, py/go by DCID) so those stay green while anything new\nstands out.\n\n## Usage\n\n```bash\npip install -r requirements.txt        # installs the reference impl (pyquicfp)\n\npython -m harness.check                # pyquicfp self-consistency (default impl)\npython -m harness.check --impl go      # clienthellod vs the goldens\npython -m harness.run                  # full differential, all available impls\npython -m harness.gen_golden foo.pcap  # add/refresh a corpus case (review the diff!)\n```\n\nDiscovering the other impls:\n- **clienthellod**: set `QUICFP_CLIENTHELLOD=/path/to/clienthellod`, or place a\n  checkout beside this repo / in `$HOME`. The Go runner wires it via a generated\n  `go.work` (the committed go.mod is left alone).\n- **retina-quic-fp**: needs DPDK. Build the binary on a DPDK host (or the\n  `docker/` image) and set `QUICFP_RETINA_BIN` / `QUICFP_RETINA_CONFIG`. Absent,\n  the retina runner reports unavailable and is skipped.\n\n## Consuming the corpus from a fingerprinter repo\n\nPin this repo as a submodule and self-test in CI:\n\n```bash\ngit submodule update --init testdata/conformance   # pulls the corpus contract\npython -m harness.check --impl \u003cimpl\u003e\n```\n\nThe submodule commit you pin *is* the contract version your repo conforms to;\nbumping it is an explicit, reviewed change.\n\n## Versioning\n\nThe contract is released as git tags **`vMAJOR.MINOR`** (pre-1.0 while it\nstabilizes). Each tag is a deliberate, reviewed snapshot of the corpus, goldens,\nand comparison semantics that consumers test against; the GitHub Release for each\ntag records what changed and whether consumers must re-verify.\n\n- **MAJOR** — the fingerprint algorithm or goldens changed; every consumer must\n  update and re-run its self-test (breaking).\n- **MINOR** — corpus cases added, or a known-issue added/removed (additive\n  coverage; a consumer may newly diverge — which is the point).\n- Harness-internal, docker, or docs-only changes that can't affect pass/fail\n  don't get a tag.\n\nA consumer pins the tag's commit as its submodule (the recorded SHA is the exact\ncontract version). To adopt a new contract, check out the tag and commit the bump:\n\n```bash\ngit -C testdata/conformance fetch --tags\ngit -C testdata/conformance checkout v0.1.0\ngit add testdata/conformance\ngit commit -m \"Bump conformance contract to v0.1.0\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frefraction-networking%2Fquic-fingerprint-conformance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frefraction-networking%2Fquic-fingerprint-conformance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frefraction-networking%2Fquic-fingerprint-conformance/lists"}