Skip to content

pqblocks-agility

Cryptographic Agility Readiness Scoring (CARS) and CI/CD regression firewall for CycloneDX 1.6 CBOM inventories.

PyPI Area Status Python Licence Source

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

What is pqblocks-agility?

Computes Cryptographic Agility Readiness Scores (CARS) and acts as a CI/CD regression firewall for CycloneDX 1.6 Cryptographic Bills of Materials (CBOM).

Use it to quantitatively measure how easily your codebase can transition away from deprecated classical cryptography to post-quantum standards, and fail pull requests that re-introduce quantum-vulnerable primitives.

Implements the 5-dimension CARS model (Costa, IACR ePrint 2026/1467) and OASIS SARIF 2.1.0 telemetry export.

Install

pip install pqblocks-agility

uv add pqblocks-agility

pip install git+https://github.com/PQBlocks/crypto-agility

uv add git+https://github.com/PQBlocks/crypto-agility

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
import json
from pqblocks_agility.cbom import parse_cbom_dict
from pqblocks_agility.cli import compute_cars_score

cbom_data = {
    "bomFormat": "CycloneDX", "specVersion": "1.6",
    "serialNumber": "urn:uuid:6c361972-23c3-4d4b-9721-a47fa266184a", "version": 1,
    "components": [{"type": "cryptographic-asset", "name": "ML-KEM-768",
                    "properties": [{"name": "pqblocks-scan.algorithm", "value": "ML-KEM-768"},
                                   {"name": "pqblocks-scan.grade", "value": "A"}]}]
}
score, dims = compute_cars_score(parse_cbom_dict(cbom_data))
print(f"CARS score: {score:.1f} / 100.0 (Grade A)")

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-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.
  • pqblocks-scan: Cryptography inventory scanner: finds classical and post-quantum algorithms in source code or a TLS endpoint and…