pqcprobe 0.1.0__tar.gz

pqcprobe-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Python bytecode / caches
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Build artifacts
+build/
+dist/
+*.egg
+
+# IDE
+.idea/
+.vscode/
+
+# OS
+.DS_Store

pqcprobe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andre Van Klaveren
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pqcprobe-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: pqcprobe
+Version: 0.1.0
+Summary: Probe a server's TLS configuration and post-quantum (ML-KEM) key-exchange readiness
+Project-URL: Homepage, https://github.com/opratr/pqcprobe
+Project-URL: Repository, https://github.com/opratr/pqcprobe
+Project-URL: Issues, https://github.com/opratr/pqcprobe/issues
+Author-email: Andre Van Klaveren <andre@vanklaverens.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: audit,cryptography,harvest-now-decrypt-later,ml-kem,mlkem,post-quantum,pqc,security,ssl,tls
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: System :: Networking :: Monitoring
+Requires-Python: >=3.9.2
+Requires-Dist: cryptography>=46.0.0
+Requires-Dist: pyopenssl>=26.3.0
+Provides-Extra: dev
+Requires-Dist: bandit; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pip-audit; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pqcprobe
+
+[![Tests](https://github.com/opratr/pqcprobe/actions/workflows/python-tests.yml/badge.svg)](https://github.com/opratr/pqcprobe/actions/workflows/python-tests.yml)
+[![Lint & Security](https://github.com/opratr/pqcprobe/actions/workflows/lint.yml/badge.svg)](https://github.com/opratr/pqcprobe/actions/workflows/lint.yml)
+[![CodeQL](https://github.com/opratr/pqcprobe/actions/workflows/codeql.yml/badge.svg)](https://github.com/opratr/pqcprobe/actions/workflows/codeql.yml)
+[![Python versions](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A small command-line TLS probing utility that uses pyOpenSSL to inspect an HTTPS server's TLS configuration, with a focus on post-quantum readiness.
+
+Features:
+- Reports negotiated TLS version, cipher, ALPN and certificate summary
+- Reports the negotiated key-exchange group and flags whether it is
+  post-quantum (e.g. `X25519MLKEM768`) or classical
+- Assesses post-quantum posture: enumerates which key-exchange groups the
+  server accepts and flags "harvest-now, decrypt-later" (HNDL) risk when no
+  post-quantum key exchange is offered
+- Verifies the certificate matches the requested hostname (SAN/CN, wildcard
+  and IP aware)
+- Probes server support for TLS 1.3 and TLS 1.2
+- Samples which TLS 1.2 ciphers the server accepts (and attempts TLS 1.3 ciphersuites where supported by OpenSSL)
+- Can fetch raw PEM for the server certificate (--raw-cert)
+- Concurrency option for probing (--concurrency)
+- Human-friendly summary (--pretty) or JSON output (--json)
+- Meaningful exit codes for scripting (see below)
+
+Requirements:
+- Python 3.9.2+
+- pyOpenSSL, cryptography (installed automatically)
+- OpenSSL 3.x recommended (3.5+ for post-quantum group support). On macOS the
+  system `openssl` is LibreSSL and cannot test the ML-KEM hybrid groups; install
+  OpenSSL 3.5+ (e.g. via Homebrew) for full functionality.
+
+## Install
+
+```bash
+pip install pqcprobe
+```
+
+This installs a `pqcprobe` command. To run from a source checkout instead:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install -e .
+```
+
+## Usage
+
+```bash
+pqcprobe https://example.com --pretty
+pqcprobe example.com:443 --json
+pqcprobe example.com:443 --raw-cert
+
+# Post-quantum audit: fail (exit 3) if the server offers no PQC key exchange
+pqcprobe https://example.com --fail-on-classical-only
+# Skip group probing entirely (e.g. when the openssl CLI is unavailable)
+pqcprobe https://example.com --no-groups
+```
+
+(From a source checkout without installing, use `python3 pqcprobe.py ...`.)
+
+Post-quantum key-exchange probing:
+- Enumerating group support forces individual groups via the native `openssl`
+  CLI, since pyOpenSSL does not expose a way to set the group list. OpenSSL 3.5+
+  is required for the ML-KEM hybrid groups (`X25519MLKEM768`, etc.). Groups the
+  local openssl doesn't recognize are reported as "not testable" rather than
+  "unsupported" (relevant on macOS, whose system openssl is LibreSSL).
+- Reading the *negotiated* group uses pyOpenSSL's `Connection.get_group_name()`
+  and needs no external tools.
+
+Exit codes:
+- `0` success
+- `1` handshake failed
+- `2` certificate hostname mismatch (when verifying)
+- `3` no post-quantum key exchange offered (only with `--fail-on-classical-only`)
+
+Notes:
+- Programmatic overriding of TLS 1.3 ciphersuites requires a recent OpenSSL + pyOpenSSL exposing `set_ciphersuites`.
+- Cipher probing may produce handshake failures for many ciphers — the tool records successes and errors.
+- Only use pqcprobe against systems you own or are authorized to test.
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Security
+issues should be reported privately per [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © Andre Van Klaveren
+

pqcprobe-0.1.0/README.md

@@ -0,0 +1,91 @@
+# pqcprobe
+
+[![Tests](https://github.com/opratr/pqcprobe/actions/workflows/python-tests.yml/badge.svg)](https://github.com/opratr/pqcprobe/actions/workflows/python-tests.yml)
+[![Lint & Security](https://github.com/opratr/pqcprobe/actions/workflows/lint.yml/badge.svg)](https://github.com/opratr/pqcprobe/actions/workflows/lint.yml)
+[![CodeQL](https://github.com/opratr/pqcprobe/actions/workflows/codeql.yml/badge.svg)](https://github.com/opratr/pqcprobe/actions/workflows/codeql.yml)
+[![Python versions](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A small command-line TLS probing utility that uses pyOpenSSL to inspect an HTTPS server's TLS configuration, with a focus on post-quantum readiness.
+
+Features:
+- Reports negotiated TLS version, cipher, ALPN and certificate summary
+- Reports the negotiated key-exchange group and flags whether it is
+  post-quantum (e.g. `X25519MLKEM768`) or classical
+- Assesses post-quantum posture: enumerates which key-exchange groups the
+  server accepts and flags "harvest-now, decrypt-later" (HNDL) risk when no
+  post-quantum key exchange is offered
+- Verifies the certificate matches the requested hostname (SAN/CN, wildcard
+  and IP aware)
+- Probes server support for TLS 1.3 and TLS 1.2
+- Samples which TLS 1.2 ciphers the server accepts (and attempts TLS 1.3 ciphersuites where supported by OpenSSL)
+- Can fetch raw PEM for the server certificate (--raw-cert)
+- Concurrency option for probing (--concurrency)
+- Human-friendly summary (--pretty) or JSON output (--json)
+- Meaningful exit codes for scripting (see below)
+
+Requirements:
+- Python 3.9.2+
+- pyOpenSSL, cryptography (installed automatically)
+- OpenSSL 3.x recommended (3.5+ for post-quantum group support). On macOS the
+  system `openssl` is LibreSSL and cannot test the ML-KEM hybrid groups; install
+  OpenSSL 3.5+ (e.g. via Homebrew) for full functionality.
+
+## Install
+
+```bash
+pip install pqcprobe
+```
+
+This installs a `pqcprobe` command. To run from a source checkout instead:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install -e .
+```
+
+## Usage
+
+```bash
+pqcprobe https://example.com --pretty
+pqcprobe example.com:443 --json
+pqcprobe example.com:443 --raw-cert
+
+# Post-quantum audit: fail (exit 3) if the server offers no PQC key exchange
+pqcprobe https://example.com --fail-on-classical-only
+# Skip group probing entirely (e.g. when the openssl CLI is unavailable)
+pqcprobe https://example.com --no-groups
+```
+
+(From a source checkout without installing, use `python3 pqcprobe.py ...`.)
+
+Post-quantum key-exchange probing:
+- Enumerating group support forces individual groups via the native `openssl`
+  CLI, since pyOpenSSL does not expose a way to set the group list. OpenSSL 3.5+
+  is required for the ML-KEM hybrid groups (`X25519MLKEM768`, etc.). Groups the
+  local openssl doesn't recognize are reported as "not testable" rather than
+  "unsupported" (relevant on macOS, whose system openssl is LibreSSL).
+- Reading the *negotiated* group uses pyOpenSSL's `Connection.get_group_name()`
+  and needs no external tools.
+
+Exit codes:
+- `0` success
+- `1` handshake failed
+- `2` certificate hostname mismatch (when verifying)
+- `3` no post-quantum key exchange offered (only with `--fail-on-classical-only`)
+
+Notes:
+- Programmatic overriding of TLS 1.3 ciphersuites requires a recent OpenSSL + pyOpenSSL exposing `set_ciphersuites`.
+- Cipher probing may produce handshake failures for many ciphers — the tool records successes and errors.
+- Only use pqcprobe against systems you own or are authorized to test.
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Security
+issues should be reported privately per [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE) © Andre Van Klaveren
+

pqcprobe-0.1.0/docs/DECISIONS.md

@@ -0,0 +1,222 @@
+# Decision Log
+
+A running record of notable decisions for pqcprobe — the *why* behind choices
+that the code and commit history don't make obvious on their own. Newest entries
+at the bottom. Each entry: context, the decision, and its status.
+
+---
+
+## 0001 — Purpose: post-quantum readiness auditing (2026-07-03)
+
+**Context.** The tool is used to audit our own systems in preparation for
+post-quantum cryptography risk, specifically "harvest-now, decrypt-later"
+(HNDL) exposure.
+
+**Decision.** Treat the TLS **key-exchange group** as the primary signal, not
+the symmetric cipher. HNDL risk lives in the key exchange: a session whose keys
+are agreed with classical-only ECDHE can be recorded today and decrypted once a
+cryptographically relevant quantum computer exists. The tool's reporting and
+future features are prioritized accordingly.
+
+**Status.** Accepted.
+
+---
+
+## 0005 — Dependency and platform baseline (2026-07-03)
+
+**Context.** Dependencies were pinned to older releases, and the CI matrix
+tested Python 3.8 — which neither pinned dependency supports (both require
+Python >= 3.9), so the 3.8 job could never install.
+
+**Decision.** Baseline is Python 3.9+ with pyOpenSSL 26.3.0 and cryptography
+49.0.0 (latest stable as of this date). OpenSSL 3.5+ is recommended because it
+ships native ML-KEM and enables the hybrid `X25519MLKEM768` group by default,
+which the PQC work depends on. CI tests Python 3.9–3.13.
+
+**Status.** Accepted.
+
+---
+
+## 0006 — PQC group probing approach (2026-07-03)
+
+**Context.** For PQC auditing the tool needs to (a) report the group actually
+negotiated and (b) enumerate which groups a server will accept. We evaluated
+pyOpenSSL 26.3.0's API for this.
+
+**Findings.**
+- `Connection.get_group_name()` **is** available — reading the negotiated group
+  (e.g. `X25519MLKEM768` vs. a classical `x25519`) is a clean pure-Python call.
+- `set_groups` / `SSL_CTX_set1_groups_list` is **not** bound in pyOpenSSL
+  26.3.0, so we cannot force a specific group list from Python to enumerate
+  server support.
+
+**Decision.** Report the negotiated group via `get_group_name()`. Enumerate
+server support by shelling out to the native `openssl s_client -groups <group>`
+(OpenSSL 3.5.x supports all ML-KEM hybrids). Flag any server offering only
+classical key exchange as an HNDL risk.
+
+**Status.** Implemented on `feature/pqc-group-probing`. Notes from
+implementation: openssl only prints the `Negotiated TLS1.3 group:` line for
+some groups, so handshake success is detected via a real negotiated cipher and
+the forced group is recorded as the one used. Groups the local openssl does not
+recognize are reported as `unknown_locally` (not `unsupported`). Added
+`--fail-on-classical-only` (exit 3) for audit pipelines and `--no-groups` to
+skip probing when the openssl CLI is unavailable.
+
+---
+
+## 0007 — Project name: pqcprobe (2026-07-03)
+
+**Context.** Before publishing a public GitHub repo we checked the working names
+for conflicts. `tlsprobe` collides with an archived C tool
+(github.com/marcobellaccini/tlsprobe) and sits near `tls_prober` / `tlsprober`;
+`TLS-Audit`/`tlsaudit` collides with an active, feature-similar Go tool
+(github.com/adedayo/tlsaudit). Both original names are generic and neither
+signals the post-quantum focus that differentiates this tool.
+
+**Decision.** Rename the project and CLI to **pqcprobe** ("PQC probe"). It is
+unused on PyPI and GitHub and elsewhere on the web, reads clearly, and escapes
+the crowded generic TLS-scanner namespace. Renamed the module
+(`tlsprobe.py` -> `pqcprobe.py`), test file, and all references.
+
+**Follow-up.** The local working directory is still `TLS-Audit`; name the public
+GitHub repo `pqcprobe` at creation for consistency. The PyPI name `pqcprobe` is
+available if we later publish.
+
+**Status.** Accepted.
+
+---
+
+## 0008 — Open-source and packaging setup (2026-07-03)
+
+**Context.** Preparing the project to accept contributions and be published to
+PyPI. It previously had no license file, contributor docs, or packaging.
+
+**Decisions.**
+- **License:** MIT, © 2026 Andre Van Klaveren (added a real `LICENSE` file to
+  back the README's existing claim).
+- **Governance:** added `CONTRIBUTING.md`, `SECURITY.md` (private disclosure to
+  andre@vanklaverens.com — important for a security tool), `CODE_OF_CONDUCT.md`
+  (Contributor Covenant 2.1), and `CHANGELOG.md` (Keep a Changelog).
+- **Packaging:** `pyproject.toml` with the hatchling backend; version is a
+  single source of truth read from `__version__` in `pqcprobe.py`; kept the flat
+  single-module layout (packaged via `only-include`) rather than moving to
+  `src/`, to minimize churn. Exposes a `pqcprobe` console entry point
+  (`pqcprobe:main`, which already returned an exit code).
+- **Publishing:** GitHub Actions workflow using PyPI Trusted Publishing (OIDC),
+  triggered on a published GitHub Release — no API tokens stored. The actual
+  upload is a human-triggered release, never automated blindly.
+
+**Follow-ups before first publish.**
+- GitHub namespace is `opratr`; project URLs in `pyproject.toml` and
+  `CHANGELOG.md` are set accordingly.
+- Register a PyPI "pending" trusted publisher for project `pqcprobe`
+  (workflow `publish.yml`, environment `pypi`).
+
+**Status.** Accepted; build validated locally (`python -m build` + `twine
+check` pass, wheel installs and the `pqcprobe` command runs). Not yet uploaded.
+
+---
+
+## 0009 — Linting and security scanning (2026-07-03)
+
+**Context.** The project had no linting or static/security analysis — the only
+automated gate was the unit tests. For an OSS security tool that shells out to
+`openssl` and parses untrusted network data, that is a gap.
+
+**Decisions.**
+- **Ruff** for linting (rules E/F/W/I/UP), configured in `pyproject.toml` and
+  enforced in CI via `ruff check`. `E501` (line length) is left to `ruff format`,
+  which is *not* gated — the code is not yet reformatted repo-wide, and a full
+  reformat was deliberately avoided to keep diffs reviewable. Import-ordering
+  autofixes were applied.
+- **Bandit** for Python SAST, gated in CI at **medium+** severity. The current
+  code produces only low-severity findings: `B404` (subprocess import) and ~25
+  `B110` (try/except/pass). These are accepted as known/architectural — the
+  subprocess call is core functionality (annotated with a safety rationale and
+  `# noqa: S603`), and the broad excepts are pre-existing tech debt already
+  noted in the original review (candidate for a later cleanup). Gating at
+  medium+ keeps CI honest without failing on these.
+- **pip-audit** scans runtime dependencies (`requirements.txt`) for CVEs in CI.
+- **CodeQL** (`github/codeql-action@v4`, `security-and-quality` queries) runs on
+  push/PR and weekly.
+- **Dependabot** for the `pip` and `github-actions` ecosystems (weekly), which
+  also keeps our "use current versions" preference on autopilot.
+- **pre-commit** config for local Ruff + hygiene hooks (opt-in, not CI-gating).
+- README shows status badges for Tests, Lint & Security, and CodeQL.
+
+**Follow-ups.**
+- README badge URLs use the `opratr` namespace; they render once the repo is
+  pushed to GitHub.
+- Optional future work: reduce the `B110` broad-except count and then consider
+  applying `ruff format` repo-wide and gating it.
+
+**Status.** Accepted; all checks pass locally (ruff clean, bandit medium+ clean,
+pip-audit clean, 21 tests pass).
+
+---
+
+## 0010 — Hash-pinned runtime dependencies (2026-07-04)
+
+**Context.** For supply-chain integrity we want installs to verify the exact
+artifact, not just the version — protecting against a compromised or substituted
+package on the index.
+
+**Decisions.**
+- Hashes live in a **lockfile**, not in package metadata. `pyproject.toml`
+  keeps *abstract* version constraints (what `pip install pqcprobe` resolves for
+  end users); `requirements.txt` is a fully pinned, hash-locked lockfile of the
+  entire transitive tree (cryptography, cffi, pycparser, pyOpenSSL,
+  typing-extensions).
+- The lockfile is generated from `requirements.in` with
+  `uv pip compile --universal --generate-hashes` — `--universal` embeds
+  environment markers so one file is correct across Python 3.9–3.13 (e.g.
+  `pycparser` 2.23 for <3.10 vs 3.0 for ≥3.10; `typing-extensions` only <3.13).
+- CI's test job installs with `pip install --require-hashes -r requirements.txt`,
+  which fails the build if any artifact's hash does not match (verified locally:
+  a tampered hash produces "THESE PACKAGES DO NOT MATCH THE HASHES"). Tests run
+  without an editable install because `pqcprobe.py` is importable from the repo
+  root; the packaged-install path is validated separately in `publish.yml`.
+- **`requires-python` tightened to `>=3.9.2`**: surfaced during resolution,
+  cryptography 49 excludes Python 3.9.0/3.9.1, so the previous `>=3.9` was
+  inaccurate.
+
+**Notes / limits.**
+- Dev tools and the build backend were initially unpinned; now addressed in
+  [[0011]].
+- Dependabot understands hashed requirements and will regenerate hashes on
+  updates, so this stays compatible with the "keep versions current" policy.
+
+**Status.** Accepted; hash-verified install confirmed in a clean venv, tests
+pass.
+
+---
+
+## 0011 — Hash-pin dev tools and the build backend (2026-07-04)
+
+**Context.** Extends [[0010]] to close the residual unpinned surface: the CI dev
+tools (ruff, bandit, pip-audit, build, twine, pre-commit) and the build backend
+(hatchling), which `python -m build` otherwise fetches unpinned in an isolated
+environment.
+
+**Decisions.**
+- Added `requirements-dev.in` -> `requirements-dev.txt`, a universal
+  hash-locked lockfile for the dev/CI toolchain (same `uv pip compile` flow as
+  the runtime lockfile).
+- `lint.yml` installs the tools with `--require-hashes -r requirements-dev.txt`
+  instead of an unpinned `pip install`.
+- `publish.yml` installs the same pinned set and runs `python -m build
+  --no-isolation`, so the build uses the hash-pinned hatchling rather than
+  fetching a build backend on the fly.
+- `hatchling` is included in the dev lockfile specifically to make the
+  no-isolation build verifiable.
+
+**Notes.**
+- Universal resolution pins per-Python variants where a tool dropped an older
+  interpreter (e.g. `bandit` 1.8.6 on 3.9 vs 1.9.4 on ≥3.10); CI (3.13) gets the
+  current releases.
+- pre-commit hook repos remain pinned by git `rev` (their native mechanism),
+  which is separate from the pip hash lockfiles.
+
+**Status.** Accepted; verified in a clean venv — pinned tools run (ruff, bandit,
+pip-audit clean) and `build --no-isolation` + `twine check` pass.