pqblocks-policy

Policy-as-code engine for evaluating cryptographic posture, post-quantum compliance, and cryptographic bill of materials (CBOM) conformance.

pqblocks-policy allows organizations to define, enforce, and audit cryptographic governance rules across systems, APIs, TLS endpoints, and software dependencies against modern post-quantum standards including NIST FIPS 203/204/205 and NSA CNSA 2.0.

---

Key Features

• Policy-as-Code Engine: Evaluate individual cryptographic assets or entire CBOM collections against declarative YAML/JSON profiles.
• Built-in CNSA 2.0 Profile: Pre-configured cnsa20_default() profile implementing US National Security Agency (NSA) Commercial National Security Algorithm Suite 2.0 timeline rules.
• CBOM & CycloneDX Ingestion: Direct loading and canonical evaluation of CycloneDX 1.6 Cryptographic Bill of Materials (CBOM) documents.
• Sub-Millisecond Evaluation: Evaluates 100 cryptographic assets in ~0.5 ms and 1,000 assets in under 5 ms.
• Audit-Ready Reports: Generates structured ComplianceReport objects containing verdicts (pass, violation, warning), finding lists, severity scores, and violation reasons.

---

Installation

pip install pqblocks-policy

Dependencies

pqblocks-policy requires cryptography and PyYAML.

---

Quickstart

from pqblocks_policy import PolicyEngine, cnsa20_default, Asset, UsageClass

# 1. Load the default CNSA 2.0 profile
profile = cnsa20_default()
engine = PolicyEngine(profile)

# 2. Define a cryptographic asset to evaluate
asset = Asset(ref="tls-session-1", alg="ML-KEM-768+X25519", use=UsageClass.KEY_EXCHANGE)

# 3. Evaluate compliance
report = engine.evaluate([asset])
print(f"Verdict: {report.verdict.value} | Assets: {report.asset_count} | Violations: {report.violation_count}")

Execution Output:

Verdict: pass | Assets: 1 | Violations: 0

---

Usage Example: Auditing Heterogeneous Assets

from pqblocks_policy import PolicyEngine, cnsa20_default, Asset, UsageClass, Verdict

engine = PolicyEngine(cnsa20_default())

assets = [
    Asset(ref="edge-gateway", alg="ML-KEM-768+X25519", use=UsageClass.KEY_EXCHANGE),
    Asset(ref="identity-signing", alg="ML-DSA-87", use=UsageClass.SIGNATURE),
    Asset(ref="legacy-db", alg="RSA-2048", use=UsageClass.KEY_EXCHANGE),
]

report = engine.evaluate(assets)
print(f"Overall status: {report.verdict.value}")

for finding in report.findings:
    if finding.verdict == Verdict.VIOLATION:
        print(f"Violation in {finding.asset_ref} ({finding.algorithm}): {finding.detail}")

---

Architecture & Supported Usage Classes

pqblocks-policy classifies cryptographic assets by their operational role:

• UsageClass.KEY_EXCHANGE: Key encapsulation mechanisms (KEM) and Diffie-Hellman protocols.
• UsageClass.SIGNATURE: Digital signature algorithms for authentication and integrity.
• UsageClass.KEY_GENERATION: Asymmetric and symmetric key derivation operations.
• UsageClass.TLS: Transport layer security cipher suites and protocol configurations.
• UsageClass.HASH: Cryptographic hash functions.

---

Non-Claims & Compliance Notice

Important

Advisory Nature: pqblocks-policy is a policy evaluation and auditing engine.

• Evaluating compliance does not substitute for formal NIST CMVP or FIPS 140-3 testing.
• The package is not certified under FIPS 140-3.
• Conformance verdicts indicate alignment with codified rules and profiles, but do not represent formal NSA accreditation.

---

License

This project is licensed under the Apache 2.0 License. See LICENSE and NOTICE for details.