pqscan v0.0.2-alpha

pqscan v0.0.2-alpha — TLS/QUIC cipher-configuration and PQC readiness scanner

pqscan is a small, fast, chainable TLS/QUIC cipher-configuration and
post-quantum readiness scanner shipped as a single static binary (the
PD-ecosystem contract in
docs/spec.md#5-feature-set).
v0.0.2-alpha is the first development cut; the 2026.01-rc1 name is
reserved for the release that follows completion of the current
milestone set (M1-M5). It packages the engine state
that closed the M0 gate
together with the tooling needed to verify it. Artifacts are verifiable
before they are run — that is the governance contract of this tool.

What is included

• Both-plane engine proven live. Forced-group probing negotiates the
  PQC hybrid group X25519MLKEM768 (4588) on both transport planes:
  on the TCP plane (internal/tlsx) — TLS 1.3, TLS_AES_128_GCM_SHA256
  (version 772) — and inside QUIC v1 with ALPN h3
  (internal/quicx). Measured against a live hybrid edge, evidence
  verbatim on issue #8
  (TCP) and issue #9
  (QUIC). Rejections are results, not errors: UDP failures are
  classified (refused / blocked) and recorded; on-the-wire HRR
  observation (RFC 8446 §4.1.3) extracts the group a server demands,
  including the obsolete Kyber draft 25497 still honoured by some
  edges — the finding that seeds the compat-oracle ladder.
• -debug / -debug-out diagnostics. Every engine decision point
  (ladder step, QUIC handshake, refusal classification) emits a
  diagnostics event: a human stream on stderr under -debug, and a
  schema-1 machine report via -debug-out diag.json
  (USAGE.md,
  issue #29).
• Single-target fast mode (-u). The binary scans a single target
  (host, host:port, ip:port) in fast mode: both planes probed
  (QUIC skippable via -quic-off), jsonl/text output via -jsonl /
  -o — live on the proven engines (PQ-30,
  PR #55).
• Measured benchmarks. The M0 gate measured the single-target fast
  path end to end on the loopback fixture: 2,952 handshakes/s at
  W=8 (re-run 3,026) against the ≥ 2,500 target
  (issue #10). The
  latency decomposition holds on live hosts: connect ≈ 1 RTT
  (18.94 ms), handshake 23.44 ms, total ≈ 2 RTT + server compute
  (42.4 ms, cloudflare seq×20); QUIC per-conn cost 22.5 ms avg
  handshake, goroutine delta 3, heap 665 KB. Full SLO cells in
  docs/m0-report.md.
• SLSA provenance on every artifact. Every binary in this release
  is built in Actions and attested in the same job that produces it
  (actions/attest-build-provenance, no post-hoc wrapping):
  Sigstore-signed SLSA build provenance bound to the repository/OID
  issuer
  (ADR-0003: SLSA provenance via GitHub Artifact Attestations).

Verify before running

Every artifact carries SLSA build provenance; verify it — the digests
must match the artifacts for this repository. With the gh CLI:

gh attestation verify <artifact> -R shsingh/pqscan

A verified run exits 0; a non-TTY invocation of the CLI may print
nothing on success — for the structured proof (subject digest, signer
identity, Rekor timestamp, build invocation) use:

gh attestation verify <artifact> -R shsingh/pqscan --format json

The Sigstore bundle is also retrievable offline per artifact with
gh attestation download <artifact> -R shsingh/pqscan.

Each release also carries CHECKSUMS-sha256.txt (sha256 over every
binary). From the directory holding the artifacts:

sha256sum --check CHECKSUMS-sha256.txt

Limitations

2026.01-rc1 is an engine-gate release candidate, not the full M1/M2
surface:

• Multi-target grammar and run pipeline land with M1: target
  grammar and the run pipeline
  (#38), output encoders
  and the WAL (#39).
  Until then the rc1 binary's scan surface is intentionally minimal —
  single targets via the fast mode (-u) on the live-proven engines
  and the diagnostics path fully functional; targets-as-grammar
  (CIDRs, ranges, lists) are rejected until PQ-15 lands.
• Deep- and pq-mode ladders land with M2: the deep-mode plan
  executor (offer-one matrix, pruned DAG)
  (#43), PQC readiness
  scoring (#42), IANA
  regen tables (#41) and
  the surrounding analytics — the full range is tracked under issues
  #38–#45.
• M0 deferred SLO cells — aggregate sustained under load, p95
  per-target, RSS at 50k in-flight and deep-mode rate are measured at
  their owning milestones (M3/M4) and are listed explicitly in
  docs/m0-report.md
  so no cell is silently skipped.