Documentation

Getting Started

Step 1: Probe a domain

pqprobe scan yourcompany.com --verbose

Target: yourcompany.com:443
Timestamp: 2026-09-30 01:26:52.735265366 +0200 CEST m=+0.000960100
Protocols: TLS 1.3, TLS 1.2
Resolver: system
Addresses: 1 dialed, worst 203.0.113.10:443
  203.0.113.10:443 v4 full TLS 1.3,TLS 1.2 x25519 D(57)
Complete: yes
Ciphers: TLS_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256, TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256, TLS_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_AES_128_GCM_SHA256, TLS_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA256, TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
Chain (3, as presented):
  0: CN=yourcompany.com | ECDSA 256 | ECDSA-SHA256 | until 2026-11-29
  1: CN=Sectigo Public Server Authentication CA DV E36,O=Sectigo Limited,C=GB | ECDSA 256 | ECDSA-SHA384 | until 2036-03-21
  2: CN=Sectigo Public Server Authentication Root E46,O=Sectigo Limited,C=GB | ECDSA 384 | ECDSA-SHA384 | until 2038-01-18

Security Score: 57/100 (Grade: D)
Score Deductions:
  - Cipher: CBC mode ciphers supported - vulnerable to padding oracle attacks (-16)
  - Key Exchange: RSA key exchange detected - no forward secrecy (-27)
  - Post-Quantum: No PQC key exchange. Classical KEX is exposed to active downgrade risk. Max grade C. (-0)
Risk Priority: EMERGENCY (Risk Score: 43)
Recommendation: CRITICAL: INTERNAL/PII data with security grade D (score: 57). Immediate remediation required. Deploy emergency fixes, escalate to security team, implement temporary mitigations if needed.

PASS   yourcompany.com:443  grade D
1 target: 1 passed, 0 failed policy, 0 not scanned. Exit code 0.

That is real output from a public host, with its name and address replaced. A name resolves to one or more addresses; the first address of each family gets the full probe sequence and the rest a short one, and the grade is the worst full-sequence address. yourcompany.com negotiates TLS 1.3 with x25519 and no post-quantum key exchange, which caps it at 79. It also accepts CBC suites and RSA key exchange, which take it to 57, a D. Without --verbose the ciphers, chain, deductions and recommendation are left out. The CLI scores at MEDIUM criticality unless --sensitivity says otherwise, which scales each deduction by 1.1.

In a pipeline, the same probe gates the job. Exit code 0 means every target passed, 1 means a target failed a --fail-on condition, and 2 means a target could not be scanned, including a target the address policy refuses (loopback, and private ranges unless --allow-private-targets opens them). --sarif writes SARIF 2.1.0 for this run's targets.

pqprobe --db pqprobe.db scan --targets-file targets.txt \
  --fail-on 'grade<B' --fail-on tls10 --fail-on no-pqc --fail-on regression \
  --sarif pqprobe-network.sarif

Conditions: grade<X, tls10, tls11, no-pqc, incomplete (a probe got no answer; see Probe Outcomes), and regression, which compares the grade with the last stored scan of the target under the same scoring version. Keep the SARIF as a job artifact on GitLab, not in the sast report slot: the results locate network endpoints, not files in the repository.

Step 2: Analyze your code

pqprobe-static scan . --output sarif

Analyzes source code for cryptographic usage — hardcoded algorithms, weak key sizes, deprecated ciphers, insecure TLS config. 188 detection patterns across Go, Python, Java, C, C++, JavaScript, TypeScript, Rust, C#, Ruby, PHP, Zig, Swift and Kotlin, plus config files (nginx, Apache, YAML, JSON). Cryptographic libraries are detected by name, 21 of them, and an import is reported as a library component distinct from an algorithm asset.

SARIF output uploads directly to GitHub or GitLab Security tabs. No new dashboard — findings appear alongside your existing code scanning results.

# GitHub Actions
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: pqprobe-results.sarif

# GitLab CI, 19.2 and later
artifacts:
  when: always
  paths: [pqprobe-results.sarif]
  reports:
    sarif: pqprobe-results.sarif

GitLab's sast report slot takes GitLab's own SAST JSON, not SARIF. Before 19.2, convert the SARIF first; docs/ci-integration.md in the source distribution has both paths.

Step 3: Check your dependencies

pqprobe dep-audit .

go.mod — 3 crypto dependencies

  crypto/tls (stdlib)     PQC: ✓ since Go 1.24    Current: Go 1.22 ⚠ upgrade
  golang.org/x/crypto     PQC: ✓ since v0.31.0    Current: v0.28.0 ⚠ upgrade
  github.com/lib/pq       PQC: inherits stdlib     No action needed

Summary: 2 dependencies need version bumps for PQC support

Covers nine ecosystems: go.mod, package.json, requirements.txt, Pipfile and pyproject.toml, Cargo.toml, pom.xml and build.gradle, Gemfile, composer.json, .csproj and packages.config, and Conan (conanfile.txt, conanfile.py). Reports which libraries use cryptography, whether they support PQC, and the minimum version to upgrade to. Results are printed, not stored.

Step 4: Track your trajectory

Probe the same targets over time. pqprobe compares results and assigns a migration trajectory:

• IMPROVING — you enabled PQC key exchange, upgraded a library, rotated to a stronger cert. The gap between your posture and the deadline is closing.
• STABLE — nothing changed. The deadline is closer but you haven't moved.
• DEGRADING — a new service appeared without PQC, something regressed, a cert downgraded. The gap is growing.

pqprobe analyze example.com --days 90

Most organizations right now are STABLE. That's the finding — you haven't started, and the deadline hasn't stopped.

Add --project to extrapolate your trajectory against actual compliance deadlines:

pqprobe analyze example.com --project

For each CNSA 2.0 date (1 January 2027, 31 December 2030, 31 December 2031) and other frameworks with dates, you get: on track, at risk, stalled, or regressing — with projected completion date. Requires 3+ scans.

Export

pqprobe export-cbom output.json          # CycloneDX Cryptographic Bill of Materials
pqprobe export-sarif findings.sarif      # SARIF 2.1.0 for every stored endpoint
pqprobe export inventory.csv             # Full inventory for CMDB/SIEM
pqprobe report example.com               # Detailed report for a single target

Exports read what is stored. scan, probe, the protocol scan-* commands, passive analyze, import mde, and scan-local, audit-windows and dep-audit (at sensitivity 1 or 2) store their results, and import static stores a pqprobe-static record; scan-ssh and scan-fhir print theirs and store nothing. Every export reads each stored row by its kind (TLS, SMTP, SMB, SSH, HL7, DICOM, Defender inventory, filesystem, Windows audit, dependency audit, static analysis): an SMB row is exported as SMB, not as a TLS endpoint.

Grades

pqprobe grades measure post-quantum preparedness, not just classical TLS hygiene. Scoring version 11. A TLS endpoint without post-quantum key exchange caps at 79, grade C, however clean its classical configuration.

Every scan records its deductions: --verbose prints them, and the JSON output and the dashboard show them.

Deductions

Scores start at 100 and each issue subtracts points. A criticality multiplier scales each deduction, rounded down: LOW 1.0, MEDIUM 1.1, HIGH 1.2. The CLI maps --sensitivity 1 and 2 to MEDIUM and HIGH, defaulting to 1; 0 (LOW) is reserved for the scheduler, and a command that stores its result refuses it. The server scores submitted scans at MEDIUM and the scheduler at LOW.

There is no deduction for a certificate close to expiry; only an expired one counts.

PQC Cap

After deductions, the score is capped by post-quantum posture:

A post-quantum certificate signature also lifts the TLS cap, since the scanner marks the result post-quantum either way.

Fatal Conditions

These set the score to 0, grade F, before any deduction or cap:

• SSL 2.0 or SSL 3.0 accepted
• TLS 1.0 or TLS 1.1 accepted (deprecated by RFC 8996, PCI DSS 4.0, BSI TR-02102)
• An EXPORT cipher suite
• A NULL cipher suite
• DES, 3DES or DES40, whatever the key exchange, ECDHE included
• RC4
• An MD5 certificate signature

Which address is graded

Every address that completed the full probe sequence is scored on its own. The host takes the lowest score; a tie goes to the address with the larger deduction total, which the cap would otherwise hide. When the scoring version changes, the server rescores stored scans after startup, in the background, each under the criticality it was first scored under, and stamps the new version. The API serves throughout; until the rescore finishes, a stored grade is the one its scoring_version gave, and /api/v1/health reports "rescoring": true.

Probe Outcomes

A TLS scan sends one ClientHello per question: one protocol version, one cipher suite, one key-exchange group at a time. Each probe ends in one of three ways.

A scan is complete when every probe on every connected address got an answer; otherwise it lists the checks that did not, as version:TLS 1.0, group:x448, suite:…, dhe or classic. Text output shows Complete: yes or Complete: no, 2 checks unknown: group:x448, version:TLS 1.0, and marks the score [incomplete: 2 checks unknown]; JSON carries complete and unknown. The grade stands on what was answered: a deduction whose evidence never arrived does not fire, and the result is marked incomplete rather than guessed. --fail-on incomplete fails a target that left any check unknown.

Only the full sequence probes TLS 1.1 and older and every suite; a short-sequence address is probed for TLS 1.3, TLS 1.2 and X25519MLKEM768 only, so it is evidence of what it accepted, never of what it refused.

Suites are probed one at a time at TLS 1.2. When a version probe finds TLS 1.1, TLS 1.0 or SSL 3.0 accepted, the suite the server chose for that probe is listed at that version. Each suite in the result lists the versions the server negotiated it at, newest first, in versions in JSON and in the TLS column of the result card: a suite the server takes on TLS 1.2 and TLS 1.1 reads 1.2, 1.1.

RSA key-exchange fallback. When the default handshake meets a handshake-failure alert, a TLS 1.2 hello offering only RSA key exchange is tried. If the server answers it, the address is probed as usual and its record carries "fallback": "rsa-key-exchange" in JSON.

Legacy-version fallback. When the default handshake is refused on its version, a protocol-version alert or a server settling on a version below TLS 1.2, a hello offering TLS 1.1, TLS 1.0 and SSL 3.0 with every suite those versions carry is tried; it is also tried when the RSA key-exchange hello was refused. If the server answers it, the address is probed as usual and its record carries "fallback": "legacy-version".

Network check: post-quantum handshake sizes

pqprobe netcheck runs from inside a network against hosts, a file of hosts or CIDR ranges. Per host it reports whether the endpoint offers post-quantum key exchange, the result of the TLS scan's own default handshake and X25519MLKEM768 probe, and a handshake size test. Nothing is graded or stored, and a TLS scan sends none of the test's hellos.

The size test sends a small control ClientHello, then one ClientHello at each client-flight size of the calculator, every key exchange except Classic McEliece: 550, 583, 1,318, 1,702, 1,734, 1,767 and 2,086 B at the default fixed part. Each carries that key exchange's key share and one for X25519, padded to the size, so a server without the group still answers and the result is about the size. A ClientHello longer than the connection's segment size, as the kernel reports it, is written as two segments, the first exactly that size, with a one-second pause between them, the reproduction tldr.fail uses; --force-split cuts at 1,460 B.

The summary's first line states the counts: hosts checked, hosts that do not offer post-quantum key exchange, hosts where a post-quantum-sized handshake fails. The failing hosts come next, grouped by shared failure, with the largest size answered. One line per host says whether the server asks for the hybrid group when it is offered without a key share, or completes on classical. In a range, an address with nothing listening is skipped and counted. --format json and csv write one row per host, and --label puts a label on every row so runs from several sites can be concatenated. The report names hosts and the path from where the command ran; a device is described only as what the failing hosts have in common.

The Test button. The calculator lists the same sizes, one row per key exchange. Enter a host and press Test: our server runs the size test against that host on port 443 and marks each row. The page makes no network call until the button is pressed. The test runs under the public probe's limits: rate limit, pause between hellos, opt-out list and address policy. The calculator's server-flight rows are not testable against someone else's server, and hosts on an internal network need pqprobe netcheck.

Sources

• RFC 9846, The Transport Layer Security (TLS) Protocol Version 1.3, sections 4.2.4, 4.3.7 and 4.3.8: rfc-editor.org/rfc/rfc9846.html
• RFC 7685, A TLS ClientHello Padding Extension: rfc-editor.org/rfc/rfc7685.html
• NIST FIPS 203, ML-KEM key sizes: csrc.nist.gov/pubs/fips/203/final
• IANA, TLS Supported Groups registry: iana.org/assignments/tls-parameters
• OpenSSL, SSL_CTX_set1_groups_list manual page: docs.openssl.org/3.5/man3/SSL_CTX_set1_curves

Refused addresses. Loopback, 0.0.0.0/8, ::/128, link-local, multicast, 240.0.0.0/4, 100::/64 and the scanning host's own addresses are never dialed. The private and other special-purpose ranges are refused too unless --allow-private-targets opens them; pqprobe netcheck checks a private range or host named to it without the flag. Refused addresses are listed in reserved_addresses; a name that resolves only to refused addresses fails with reserved address space, exit code 2 in the CLI and a 400 when submitted to the server.

Deployment

PQProbe deploys as a single binary with zero external dependencies. The server stores everything in one SQLite file. Its outbound connections go to the targets you probe and, only when you configure them, to GitHub for sign-in, to your Jira instance, and to your alert webhook.

Install

The tarball contains:

• bin/pqprobe-server — API server and web dashboard
• bin/pqprobe — CLI probing tool
• bin/pqprobe-static — Static code analyzer
• etc/pqprobe.env.example — Configuration template
• etc/pqprobe.service — systemd unit file
• INSTALL.md — Step-by-step deployment guide

# Extract
tar xzf pqprobe-*-linux-amd64.tar.gz
cd pqprobe-*/

# Create system user and directories
sudo useradd -r -s /bin/false pqprobe
sudo mkdir -p /opt/pqprobe/bin /opt/pqprobe/data
sudo cp bin/* /opt/pqprobe/bin/
sudo cp etc/pqprobe.env.example /opt/pqprobe/pqprobe.env
sudo chown -R pqprobe:pqprobe /opt/pqprobe

# Install systemd service
sudo cp etc/pqprobe.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now pqprobe

# Verify
curl http://localhost:8080/api/v1/health

Docker

# Build and run with Docker Compose
docker-compose up -d

# Or build individual images
docker build -f deployments/docker/Dockerfile.server -t pqprobe-server .
docker build -f deployments/docker/Dockerfile.cli -t pqprobe-cli .
docker build -f deployments/docker/Dockerfile.static -t pqprobe-static .

Authentication

By default, the dashboard and API are open. PQPROBE_REQUIRE_AUTH=true requires an API key or a signed-in session for the data and export routes marked gated in the API Reference. Scan submission, reading a scan result, the probe preview and the dashboard pages stay open either way; /app and /dashboard/nis2 render recent scans and the NIS2 posture into the page.

# In /opt/pqprobe/pqprobe.env
PQPROBE_REQUIRE_AUTH=true
PQPROBE_JWT_SECRET=your-secret-here  # for persistent sessions

When auth is required and no active API key exists, the server creates one named bootstrap-admin at startup and prints it to the log. Create more at the console with:

sudo -u pqprobe /opt/pqprobe/bin/pqprobe-server \
  -db /opt/pqprobe/data/pqprobe.db create-key

Use the API key with any request, as X-API-Key or Authorization: Bearer pqp_…:

curl http://localhost:8080/api/v1/scans -H "X-API-Key: pqp_your_key_here"

Keys made at the console (the bootstrap key and create-key) can delete any scan but the scheduler's; any other key can delete only the scans it uploaded. Any key can create more through POST /api/v1/keys; each key records the key that created it, lists itself, the keys it created and its user's keys, and revokes only keys it created. A console key cannot be revoked through the API. There is no separate admin role beyond that.

GitHub OAuth (optional)

For browser-based login, create a GitHub OAuth App and set:

PQPROBE_GITHUB_CLIENT_ID=your-client-id
PQPROBE_GITHUB_CLIENT_SECRET=your-client-secret
PQPROBE_GITHUB_CALLBACK_URL=https://your-domain/api/v1/auth/github/callback

Without an allowlist, any GitHub account can sign in, and with PQPROBE_REQUIRE_AUTH every signed-in account passes the gate. Limit sign-in with PQPROBE_GITHUB_ALLOWED_USERS (logins, comma-separated, case-insensitive) or PQPROBE_GITHUB_ALLOWED_ORG (active members of one organization; the server then asks GitHub for the read:org scope). A refused account gets no session. Sessions are JWTs in an HttpOnly cookie valid for 24 hours; a login removed from the user list is refused on its next request.

Scheduler

With PQPROBE_AUTO_SCAN_TARGETS set, the server scans a list of targets on its own: the first cycle at startup, then every --auto-scan-interval hours (24), with --auto-scan-workers targets at a time (8). Each worker pauses 2 to 4 seconds between targets; a TLS handshake times out after 10 seconds, and a mail target is checked for an open port for 3 seconds first. A save the database refuses as busy is retried after 1, 2, 4 and 8 seconds. The first cycle after a start skips every target the scheduler stored a row for within the last interval, failed scans included, so a restart finishes the cycle it interrupted rather than scanning every target again; later cycles scan every target due.

The targets file is a JSON array:

[
  {"host": "www.example.com", "category": "banking", "country": "DE"},
  {"host": "mail.example.com:25", "category": "banking", "probe_target": "example.com"},
  {"host": "archive.example.com", "category": "banking", "cadence": "weekly"}
]

PQPROBE_OPTOUT_LIST names a file of hostnames, IP addresses and CIDRs, one per line, # for comments, that the instance never connects to. A missing file counts as empty. It applies to every scan the instance makes: listed entries are removed from the scheduler's targets at startup, a submitted scan of a listed target is refused with a message that the operator of the host has opted out, and a domain probe leaves listed hosts out. A hostname is matched as written; an address or a network is matched against the address about to be dialed, so a name that resolves into a listed network is covered. A host with only some of its addresses listed is scanned on the others, and its record names each address left out as an address entry with the reason as its error; such an entry does not enter the grade. A result that is an opt-out refusal is never stored. The CLI takes the same file with --optout-list, and the worker with -optout-list. Entries reach the list only by editing the file. pqprobe optout-check --optout-list optout.txt --targets-file targets.json is a dry run of a file: it lists, per entry, the targets it would exclude and the total, looking names up in the DNS and connecting to no target.

Scheduler results are public, never expire, and are scored at LOW criticality. A target that could not be scanned is stored as an ungraded row, so population figures count it. Scheduler rows are never deleted through the API. They feed /app, the NIS2 dashboard and scheduler alerts. Scans submitted with "private": true are hidden from lists and deleted 72 hours after submission.

Stored scans are kept in retention tiers. Each scan's row holds a summary; its record is stored apart, with every certificate stored once and referenced by fingerprint, in every tier.

An uploaded scan joins its host's tiers by its scan time, with no pin for its date. A job moves records down the tiers once a day. A cited scan is one a published figure was built from, recorded in the cited_scans table: the edge-attribution results and the scan the Aer Lingus post links are recorded at startup, and pqprobe-cohort -cite writes the scan IDs of an export for pqprobe cite <file> to record. A database stored by an earlier version is moved to this layout once, in the background after startup, with NIS2 posture builds paused and the last stored build served meanwhile; the server keeps answering throughout, and a restart continues the move where it stopped.

Moving records frees space inside the database file but does not shrink it: new scans reuse the freed pages. To return the space to the disk, stop the server and run VACUUM on the database with sqlite3, as the user the server runs as, then start it again. VACUUM rewrites the whole file and needs free disk of about twice the size it will end up, for its temporary copy and its WAL. The scheduler resumes its cycle after the restart, so the stop costs no rescanning.

Scheduler Alerts

The automated scanner can compare every scan with the previous scheduler scan of the same host and report what changed. Set --alert-webhook log to write alerts to the log, or a URL to also receive each host's alerts as one JSON POST. Unset, nothing is evaluated. --alert-expiry-days sets the certificate expiry window; 0 turns that rule off.

Addresses are compared as sets, so a rotating address set does not read as a change, and an unanswered probe is never taken for a refusal. Each alert is logged as an [alert] JSON line before the POST. The POST has a 30-second timeout and is not retried; the webhook URL never appears in the log.

{
  "event": "pqprobe.alert", "version": 1,
  "target": "www.example.com:443", "scan_id": "...", "prior_scan_id": "...",
  "observed_at": "2026-09-30T05:12:44Z", "prior_observed_at": "2026-09-29T05:10:02Z",
  "alerts": [
    { "rule": "hybrid_lost", "message": "Hybrid post-quantum key exchange is no longer accepted on any address",
      "old_groups": ["X25519MLKEM768"], "new_groups": ["secp256r1", "x25519"], "addresses": ["192.0.2.10:443"] }
  ]
}

Each rule's fields and the suppression conditions in full are in docs/scheduler-alerts.md in the source distribution.

Configuration Reference

API Reference

Every route the server registers. Open routes never ask for credentials. Gated routes are open until PQPROBE_REQUIRE_AUTH=true, then need an API key or a session. The rest always need what they say.

An uploaded scan belongs to the key that uploaded it. A scan's routes (/api/v1/scan/{id}, its CBOM, SARIF, compliance report, diff and Jira export) answer 404 for it to anyone but that key and console keys, and the history, projection and finding routes leave it out for them. Uploads are private: they never appear in /app or on the home page, and the scheduler's alerts and the NIS2 dashboard never read them. They do count in the horizon view and in the statistics, which cover every stored scan. A finding is tracked separately for each source of scans of a host: the scheduler, submissions, and each uploading key.

Authentication methods

• API key: X-API-Key: pqp_… or Authorization: Bearer pqp_…. A malformed or revoked key gets 401, on open routes too.
• Session: after GitHub sign-in, a JWT in the HttpOnly pqprobe_token cookie (24 hours, SameSite Lax, Secure with --secure-cookies).
• Session token: the same JWT as Authorization: Bearer, for a token that does not start with pqp_.

Rate limits

Every route is limited per client address: --rate-limit requests (60) per --rate-window seconds (60), a sliding window. Behind a reverse proxy, list it in --trusted-proxies, or every client is counted as the proxy. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time a slot frees); a refused request gets 429 with Retry-After equal to the window. A request with an API key is also limited per key, rate_limit requests a minute (60), with 429 and Retry-After: 60. A full scan queue answers 429 with Retry-After: 30.

Errors

Errors are JSON, {"error": "message"}, with the HTTP status carrying the class: 400 for a bad request or a refused target, 401 without credentials, 403 with credentials that may not do this, 404, 405 for a wrong method, 429 when limited, 503 while the posture is being built.