QSTriage

QSTriage — Cryptographic Policy & Justification Engine

Cryptographic migration is not a scanner problem.

A scanner can tell you where RSA is. It cannot tell you which decision comes next, which uncertainty blocks action, or how that decision can be defended later.

QSTriage evaluates cryptographic inventories and supported CycloneDX CBOM evidence and produces deterministic PQC Decision Records (PDR 0.3). Each record preserves the evidence, policy context, confidence limits, and resulting action. QSTriage runs locally and does not modify production systems.

What QSTriage does

QSTriage:

• validates native YAML inventories and supported CycloneDX CBOM JSON,
• classifies algorithm identifiers against a bounded, standards-backed grammar,
• keeps risk attention separate from evidence, confidence, and verification,
• reconciles classification, evidence, policy, and context into one canonical decision per asset,
• generates PDR 0.3 records whose hashes any RFC 8785 implementation can recompute, and verifies and compares PDR documents,
• models dependency-amplified blast radius and basic hybrid-PQC migration pressure,
• produces Markdown reports and JSON/CSV exports.

Why now

NIST's first three PQC standards are final, and its transition plan removes quantum-vulnerable algorithms from NIST standards by 2035. Executive Order 14412 sets 2030 and 2031 milestones for PQC key establishment and signatures in U.S. Federal high-value assets and high-impact systems, excluding National Security Systems. NSA CNSA 2.0 sets a separate schedule for those systems. Long-lived data creates pressure sooner because ciphertext collected today may remain valuable when decryption becomes possible. QSTriage addresses the work between inventory and migration: what must be verified, what moves first, and why.

Quickstart

QSTriage requires Python 3.11 or later.

python -m pip install qstriage
qstriage version

The repository contains the bundled inventory and CBOM examples used below.

Core workflow

inventory/CBOM
  -> classification
  -> context and evidence review
  -> risk scoring and policy evaluation
  -> canonical decision
  -> PDR, impact simulation, report, and export

From a fresh clone:

python -m pip install -e .
qstriage validate examples/sample_inventory.yaml
qstriage review evidence examples/sample_inventory.yaml
qstriage score examples/sample_inventory.yaml
qstriage pdr generate examples/sample_inventory.yaml --output reports/pdr.json
qstriage pdr verify reports/pdr.json

Generated files are no-clobber by default. Use --overwrite only when replacing an existing output is intentional. See the Usage Guide for the complete CLI workflow.

Example decision backlog

The bundled five-asset inventory produces:

All five sample actions are justified under the supplied evidence and still require human review. Risk attention ranks assets; it does not select the canonical action or authorize a production change.

Classifier integrity

QSTriage does not classify by substring or fuzzy similarity. MARSALA is not RSA; SHAKEWEIGHT is not SHAKE. A positive classification requires the complete normalized identifier to match an explicit grammar.

Unknown identifiers stay unknown and block decision-grade treatment; they are never quietly treated as safe. A recognized PQC family with missing or unsupported parameters receives neither quantum-resistant nor standardized-PQC status. The v1.2.1 compatibility corpus locks 26 reviewed identifiers to eight named public sources.

The three PQ/T hybrid TLS groups defined in RFC 10024 (X25519MLKEM768, SecP256r1MLKEM768, SecP384r1MLKEM1024) are classified only by their exact names, and every hybrid record requires human review of implementation certification. Any other hybrid spelling stays unknown. The registry keeps the cited source text verbatim.

See the Algorithm Identifier Grammar.

Verifiable release provenance

Release jobs require two clean builds to match byte for byte and include SHA-256 checksums and a reproducible CycloneDX SBOM. Eligible public runs add GitHub build-provenance and SBOM attestations. PyPI publication is environment-gated and uses OIDC Trusted Publishing rather than a stored API token. Verification commands appear in the Trust model.

Evidence Closure

Evidence Closure is available from v1.3.0 as a preview. Its patch format, commands, and MCP tool interfaces may change in a minor release.

It converts QSTriage-reported evidence gaps into structured questions and provenance-aware assertions. Patches are bound to the exact source inventory, validated before application, written to a new inventory, and compared through the same deterministic assessment pipeline.

The optional MCP surface exposes four read-only, path-confined tools. The repository Codex skill may inspect gaps, draft and validate a patch, and compare inventories only after the human applies it. It never applies the patch itself.

The bundled demo closes seven evidence findings and moves the evidence score from 0.00 to 1.00; the migration_planning action and gated state remain unchanged.

See the Evidence Closure guide.

Scope

QSTriage is not a universal cryptography-discovery scanner. It accepts explicit native inventories and supported CycloneDX CBOM shapes.

Its scores are deterministic prioritization indices. They do not estimate compromise probability, the arrival date of a cryptographically relevant quantum computer, or expected financial loss. See Scoring Rationale.

Canonical actions are review and planning categories, not deployment instructions. QSTriage does not rotate certificates, deploy cryptographic changes, or perform remediation.

Enforced workload limits

QSTriage refuses inputs that exceed its supported limits. It does not truncate them or continue with a partial decision result.

Additional limits cover field length, YAML structure, graph traversal, rendered output, and critical-path enumeration. See Input Contracts for the complete enforced contract.

Documentation

• Usage Guide — commands, workflows, examples, and configuration
• Input Contracts — supported inputs, limits, and parsing boundaries
• Standards and Classification — registry and normalization behavior
• Algorithm Identifier Grammar — bounded matching rules and fail-closed behavior
• Scoring Rationale — prioritization index and interpretation limits
• Simulation Rationale — model, warnings, assumptions, and non-claims
• Evidence and Context — normalization, completeness, evidence, and confidence
• Evidence Closure — provenance-aware enrichment with human approval
• Canonical Decision Model — action gating, verification, and reason codes
• PDR 0.3 Contract — structure, provenance, determinism, and versioning
• CBOM Compatibility — tested artifact shapes and scanner boundaries
• Security Policy — reporting and enforced trust boundaries

Trust model

Generated files are no-clobber by default, and terminal/Markdown output neutralizes untrusted presentation characters. File-backed PDR generation parses and hashes the same captured bytes.

The CI and security workflows use read-only repository permissions, immutable action references, hashed dependency locks, vulnerability and static-analysis checks, and full-history secret scanning. A separate alert workflow runs only after a scheduled Security run fails on main; it holds only issues: write, runs no repository code, and opens or updates one tracking issue.

The release workflow resolves an exact tag to an immutable commit, checks that the tag and package version agree, and builds only that source. Its two clean builds must match before the workflow emits the wheel, source archive, CycloneDX SBOM, and SHA-256 manifest. Attestations are created only for eligible public-repository runs.

Verify a downloaded release bundle from its directory with:

sha256sum --check SHA256SUMS

For an eligible public run with GitHub attestations:

gh attestation verify qstriage-*.whl --repo ILIASTEKEOGLOU/QSTriage
gh attestation verify qstriage-*.tar.gz --repo ILIASTEKEOGLOU/QSTriage

Release tags must match the package version exactly, for example v1.4.0 for package version 1.4.0. PyPI publication uses an exact existing tag, a guarded GitHub environment, and OIDC Trusted Publishing rather than a stored PyPI API token.

Manual release-artifact runs require an existing exact release tag. Run the workflow definition from main and supply the tag to rebuild:

gh workflow run release.yml --ref main -f release_tag=v1.4.0

Development

Python 3.11 is the locked CI and release baseline. Create and activate a virtual environment, then install the development dependencies:

python -m venv .venv
# Activate .venv using the command for your shell.
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
python -m pytest

The Python 3.11 job installs the exact hashed resolution in requirements/py311.lock. Separate blocking jobs resolve the declared dependency ranges afresh on Python 3.12 through 3.14 and run the same CLI, dependency, and test checks.

Project status

QSTriage is an early public release for local cryptographic analysis, PQC migration planning, and PDR generation. It is provided without an SLA or guaranteed response time.

License

Copyright 2026 Ilias Tekeoglou.

QSTriage is licensed under the Apache License, Version 2.0. See LICENSE.