pqprobe

The question it answers

An endpoint can be up for curl and down for a CDN

Hybrid post-quantum key exchange (X25519MLKEM768) is now the default in Chrome, Edge and Firefox, in Go 1.24+, in OpenSSL 3.5+ and at several CDNs. The ML-KEM key share is roughly 1.2 KB, so the ClientHello carrying it no longer fits one TCP segment. Anything on the path that assumed it did — an old TLS library, a middlebox inspecting the hello, a load balancer with its own parser — now has a chance to mishandle the second segment. When it does, the connection resets or hangs, and no alert is sent, because nothing on the far side got far enough to send one.

The evidence that reaches an operator is the worst possible shape:

• Every check you already run keeps passing. curl, openssl s_client, the load balancer health probe and the monitoring agent all send a small classical hello.
• The origin logs nothing. The handshake never completed, so there is no request to log.
• It looks like an application problem. Some users, from some browsers, through one CDN, get a connection error — and an application serving 200s gets read for hours.

The asymmetry is the diagnosis, and it takes about two seconds to see once something dials both ways:

$ pqprobe probe origin.example.com
BAD   origin.example.com:443  pq-intolerant
  BAD   verdict                      pq-intolerant — post-quantum-capable clients cannot connect at all, while classical clients can
        ↳ the classical client connected and the post-quantum-capable one was cut off (reset): every client
          that merely *offers* ML-KEM fails here — Chrome and Edge 131+, Firefox 132+, a CDN with
          post-quantum enabled — while curl and your existing health checks keep passing
  WARN  handshake/pq-preferred       no handshake (reset): read: connection reset by peer
        ↳ an abrupt end means the peer never sent a TLS alert: it choked on the ClientHello rather than declining it
  OK    handshake/classic            TLS 1.3, X25519, TLS_AES_128_GCM_SHA256

What it reports

One class per endpoint, and what to do about it

pqprobe dials the same endpoint several times with deliberately different client shapes and reads the shape of the refusal. Every post-quantum conclusion is conditional on the classical profile having connected: an endpoint that answered nothing is never graded.

Client profiles

A capability class, never a fingerprint

pqprobe builds its ClientHello with Go's crypto/tls. It cannot reproduce Chrome's extension order or a CDN's exact cipher list, and it never claims to. What a profile pins down is which key exchange groups are offered and which TLS versions are acceptable — the property that decides whether a post-quantum-capable client can finish a handshake. The client names below say who is affected; no code branches on them.

The default set is classic,pq-preferred,pq-only: a baseline and the two post-quantum questions. The version edges cost two more connections per endpoint and answer a different question, so they are opt-in via --profile.

Why pq-preferred is the profile that matters

It is the realistic client. It offers hybrid ML-KEM and classical groups, so a peer with no post-quantum support is still expected to complete it, by selecting X25519. A failure here therefore does not mean "no post-quantum support" — it means cannot talk to a client that offered it, and the reason is usually the ~1.2 KB hello.

The set you are migrating to

--groups X25519MLKEM768,X25519 dials exactly that set, in that order, with the same version window as pq-preferred so the two results are comparable. It gets its own handshake finding — you asked for the dial — but it does not decide the class: a set you described is a question, not a baseline. An unknown group name is a usage error listing the known ones, never a silently smaller set.

Which group, not whether some group

--per-group adds one TLS 1.3 handshake per key exchange group — ML-KEM, X25519, P-256, P-384, P-521 — each offering that group and nothing else, in sequence:

$ pqprobe probe --per-group github.com
  OK    groups    accepted: X25519, P-256 · declined with an alert: X25519MLKEM768, P-384, P-521

It is a report, not a grade: no real client offers a single group, so the map never moves the class. What it answers is which group a migration can be planned against — and the two refusals stay apart here too, since cut off on the hybrid group is a size symptom rather than a policy.

Why every profile pins its own groups and versions

Go's defaults change between releases — that is how X25519MLKEM768 became a default in the first place. A profile that inherited them would prove something different after every toolchain upgrade, which is indistinguishable from the endpoint having changed.

$ pqprobe profiles
classic       TLS 1.3 offering only classical groups (X25519, P-256)
              groups: X25519, P-256
              clients: curl, openssl s_client, any pre-2024 client, and every health check you already run

pq-preferred  TLS 1.3 offering hybrid ML-KEM first, with X25519 and P-256 behind it
              groups: X25519MLKEM768, X25519, P-256
              clients: Chrome and Edge 131+, Firefox 132+, CloudFront and other CDNs with post-quantum enabled, Go 1.24+, OpenSSL 3.5+

pq-only       TLS 1.3 offering only hybrid ML-KEM — no classical fallback
              groups: X25519MLKEM768
              clients: a client with post-quantum required, and the default of the next few years

Install

One binary, and nothing to configure

# Homebrew: the tap is this repository
brew tap allan-nava/pqprobe https://github.com/Allan-Nava/pqprobe
brew install pqprobe

# the released binary
go install github.com/Allan-Nava/pqprobe/cmd/pqprobe@latest

# from source
git clone https://github.com/Allan-Nava/pqprobe
cd pqprobe && go build -o pqprobe ./cmd/pqprobe
./pqprobe probe example.com

# the published image: multi-arch, attested, nothing but the binary
docker run --rm ghcr.io/allan-nava/pqprobe:latest probe example.com

# or build it yourself
docker build -t pqprobe .
docker run --rm pqprobe probe example.com

Usage

Commands, targets, flags, exit status

pqprobe probe <target>... [flags]
pqprobe profiles
pqprobe explain [class]   # what a class means; no network call
pqprobe version

Targets

The last form is the one that finds real problems: it is what a CDN does, and it is how you probe one node of a pool that is fronted by a single name.

Flags

Exit status

In a scheduled job

pqprobe probe --inventory inventory/edge --group edge \
  --findings --min-severity WARN --exit-on BAD > findings.json

# or against yesterday: only what changed
pqprobe probe --inventory inventory/edge --baseline yesterday.json --exit-on BAD

--findings is the flat array the sibling tools speak: one object per finding, with check, target, status, message and hint, plus value and unit wherever there is a number — so a machine consumer never has to parse the prose. An empty run emits [], never null.

A fleet

From the inventory you already have

$ pqprobe probe --inventory ansible/inventory/edge --group edge --findings | jq '.[0]'
{
  "check": "verdict",
  "target": "10.11.10.5:443",
  "status": "BAD",
  "message": "pq-intolerant — post-quantum-capable clients cannot connect at all, while classical clients can",
  "hint": "…"
}

• ansible_host= wins over the inventory alias, because the alias frequently does not resolve outside the control node.
• [group:vars] is never read as hosts. (Reading it is how a probe list acquires an endpoint called ansible_user.)
• 1.2.3.4=origin.example.com dials the address while sending that server name — the only way to reproduce a CDN-only failure from a workstation, and the way to find the one node out of six that is broken.
• The profiles of one endpoint are dialled in sequence. Three connections landing at once measures a connection limit instead of a capability.
• --per-address probes every A/AAAA record of a name, by address, and one addresses finding says whether the pool agrees — one bad node out of six is invisible to a name-only probe.

Real output over three public endpoints, September 2026:

$ pqprobe probe example.com github.com google.com
WARN  github.com:443  pq-blind
  WARN  verdict                      pq-blind — no post-quantum support, but post-quantum-capable clients still connect on a classical group
  WARN  handshake/pq-only            no handshake (alert): remote error: tls: handshake failure
  OK    handshake/pq-preferred       TLS 1.3, X25519, TLS_AES_128_GCM_SHA256
OK    example.com:443  pq-ready
OK    google.com:443  pq-ready

3 endpoint(s): 1 pq-blind, 2 pq-ready · worst: 0 ERROR, 0 BAD, 1 WARN, 2 OK

Findings reference

Every check, every status, worst first

Every run emits findings: check, target, status, message, an optional value/unit, and a hint that says what to do. Worst first, in every renderer.

Statuses

ERROR sorts above BAD on purpose: an endpoint that was never reached is not an endpoint that passed, and an operator has to see it first.

Checks

A failed handshake is a WARN on its own, never a BAD: whether it matters is the verdict's job to say, and a per-profile BAD would count the same fact twice.

Safety

It handshakes, and it closes

No request, no body, no credentials, no application data. There is nothing in the binary that can change state on the far side, which is what makes it reasonable to point at production. This is enforced, not promised: go.mod has no require block, and CI fails the build on an import of net/http or os/exec.

Scope

What it is not

None of these is a gap waiting to be filled. Each one is a decision — see INTENT.md.

What pqprobe deliberately does not tell you

• Whether a specific browser build connects. It probes capability classes, not ClientHello fingerprints.
• Nothing about the application behind the endpoint — but it does now report the measured ClientHello size (272 B classical against ~1495 B hybrid, on real endpoints) and says after a hello retry when the peer imposed an extra round trip.
• Anything about the application behind the endpoint. The handshake completes and the connection closes.

The repository

Where everything is written down

go test ./...            # includes a server that dies on a large ClientHello
go test -race ./...
./scripts/backlog.sh lint && ./scripts/backlog.sh check
./scripts/docs.sh check  # no dead link in the site or the Markdown
./scripts/repo-meta.sh lint
sh scripts/render-assets.sh --check

# every commit is a version: gates, changelog section, one commit, one tag
./scripts/release.sh 0.2.0 --commit
./scripts/version.sh check   # HEAD is the version the changelog names