Metadata-Version: 2.4
Name: pqblocks-policy
Version: 0.1.0
Summary: Policy-as-code engine for post-quantum cryptography compliance and CBOM verification.
Author: The PQBlocks Authors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/PQBlocks/crypto-policy-engine
Project-URL: Documentation, https://github.com/PQBlocks/crypto-policy-engine#readme
Project-URL: Source, https://github.com/PQBlocks/crypto-policy-engine
Project-URL: Changelog, https://github.com/PQBlocks/crypto-policy-engine/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/PQBlocks/crypto-policy-engine/issues
Project-URL: Security, https://github.com/PQBlocks/crypto-policy-engine/security/policy
Keywords: post-quantum,pqc,policy,compliance,cnsa,cbom
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security :: Cryptography
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: PyYAML
Requires-Dist: cryptography
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: hypothesis; extra == "test"
Dynamic: license-file

# pqblocks-policy

[![PyPI version](https://img.shields.io/pypi/v/pqblocks-policy.svg)](https://pypi.org/project/pqblocks-policy/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python Versions](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](https://pypi.org/project/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

```bash
pip install pqblocks-policy
```

### Dependencies

`pqblocks-policy` requires `cryptography` and `PyYAML`.

---

## Quickstart

```python
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

```python
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](LICENSE) and [NOTICE](NOTICE) for details.
