Skip to content

pqblocks-scan

Cryptography inventory scanner: finds classical and post-quantum algorithms in source code or a TLS endpoint and writes a CycloneDX 1.6 CBOM, a SARIF 2.1.0 report and a readiness grade.

Install from GitHub Area Status Python Licence Source

At a glance
Area Migration & readiness
Import import pqblocks_scan
Command line pqblocks-scan
Version 0.1.0 (Alpha)
Python >=3.11
Native dependency none
Repository PQBlocks/cbom-scanner
Licence Apache-2.0

What is pqblocks-scan?

Cryptography inventory scanner for the post-quantum transition. It finds classical and post-quantum algorithms in source code (Python by syntax tree, other languages by pattern) and in a live TLS endpoint's negotiated cipher suite. It then writes a CycloneDX 1.6 CBOM (Cryptography Bill of Materials), a SARIF 2.1.0 report and an A–F readiness grade.

Use it to get a first inventory of where RSA, ECC, MD5, SHA-1, AES, ML-KEM and ML-DSA appear in a code base, and to gate CI on it.

It follows CycloneDX 1.6 (specVersion: "1.6"), OASIS SARIF 2.1.0, the CNSA 2.0 and NIST IR 8547 transition timelines, and the CARS readiness score (Costa, IACR ePrint 2026/1467).

Install

pip install git+https://github.com/PQBlocks/cbom-scanner

uv add git+https://github.com/PQBlocks/cbom-scanner

PyPI release staged

pqblocks-scan installs from its GitHub repository while the PyPI release is staged. The import name and API are identical either way.

Quickstart

Executed, not just written

This is the quickstart from the package README. It was run against the package source when this page was generated.

quickstart.py
from pqblocks_scan.discovery import Discovery
from pqblocks_scan.scorer import CARSScorer
from pqblocks_scan.cbom import CBOMGenerator

src = "import hashlib\nh = hashlib.sha1(b'x').hexdigest()\nfrom pqcrypto.kem import ml_kem_768\n"
assets = Discovery().discover_source(src, "app.py").assets
print([(a.algorithm, a.line_number, a.is_quantum_vulnerable) for a in assets])
# [('ML-KEM-768', 3, False), ('SHA-1', 2, True)]
grade = CARSScorer.evaluate(assets)
print(grade.score, grade.letter)                      # 55.5 C
print(CBOMGenerator.generate(assets)["specVersion"])  # 1.6

Examples

Runnable scripts in the repository:

Documentation and evidence

Every PQBlocks package ships the same evidence set, so each claim can be checked against tests, sources and measurements.

  • Overview

    What it does, install, usage and API.

  • For AI agents

    Correct imports, pitfalls and rules for coding assistants.

  • Security notes

    What it protects, hostile input, constant-time and audit status.

  • Testing

    Test suites, coverage, vectors and what is not covered.

  • Benchmarks

    Measured performance, including where it loses.

  • Evidence

    Primary sources and the method-to-code map.

  • Verification report

    Self-verification results, defects found and limits.

  • Use cases

    Worked scenarios and when to pick something else.

  • Changelog

    Every release and what changed.

  • pqblocks-agility: Cryptographic Agility Readiness Scoring (CARS) and CI/CD regression firewall for CycloneDX 1.6 CBOM inventories.
  • pqblocks-cbom: CycloneDX 1.5 CBOM metadata enrichment engine injecting quantum-safe classifications and CNSA 2.0 compliance properties.
  • pqblocks-cnsa-evidence: CNSA 2.0 evidence pack generator for quantum-safe compliance, CBOM generation, and migration scheduling.
  • pqblocks-jwe-audit: High-throughput JSON Web Encryption (JWE) cryptographic policy auditor enforcing CNSA 2.0 and NIST FIPS 203 PQC…
  • pqblocks-lint: Static analysis for Python source that finds classical and post-quantum cryptographic primitives with a source-to-sink…
  • pqblocks-policy: Policy-as-code engine for post-quantum cryptography compliance and CBOM verification.