pqblocks-lint¶

Static analysis for Python source that finds classical and post-quantum cryptographic primitives with a source-to-sink taint pass and reports them as a CycloneDX 1.6 CBOM or a SARIF 2.1.0 log.

At a glance


Area	Migration & readiness
Import	`import pqblocks_lint`
Command line	`pqblocks-lint`
Version	0.1.0 (Alpha)
Python	>=3.11
Native dependency	liboqs
Repository	PQBlocks/pqc-lint
Licence	Apache-2.0

What is pqblocks-lint?¶

Static analysis for Python source that finds cryptographic primitives and says which ones a quantum computer would break (RSA, ECDSA/ECC, X25519) and which it would not (ML-KEM, AES-256, HKDF).

Use it to build a first inventory of the cryptography in a Python codebase as a CycloneDX 1.6 CBOM or a SARIF 2.1.0 log, as one input to a post-quantum migration plan.

How it works: it parses the code with Python's ast module (the code is never executed), builds a data-flow graph, follows values from key-generation calls to encrypt, sign, exchange and derive calls, and matches the result against a fixed table of name patterns. It is a static-analysis heuristic, not a cryptographic module.

Read Limitations before using the verdict as a CI gate. Ed25519, DSA and finite-field DH are not detected, so a file using only those gets NO_CRYPTO_DETECTED.

Install¶

pip (from GitHub)uv (from GitHub)

pip install git+https://github.com/PQBlocks/pqc-lint

uv add git+https://github.com/PQBlocks/pqc-lint

PyPI release staged

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

Native dependency: liboqs

The post-quantum primitives come from liboqs (Open Quantum Safe). The package README explains how the library is located: install notes.

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 pathlib, tempfile
from pqblocks_lint import cli

src = pathlib.Path(tempfile.mkdtemp(), "keys.py")
src.write_text("from cryptography.hazmat.primitives.asymmetric import rsa\n"
               "def make_key():\n"
               "    key = rsa.generate_private_key(public_exponent=65537, key_size=2048)\n"
               "    return key\n")
code = cli.main(["--target", str(src), "--format", "cbom", "--output", str(src.with_suffix(".cbom.json")), "--seed", "0"])
print(code)   # 1: quantum-vulnerable cryptography found (RSA-2048)

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-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…