Audit (`quantum_safe.audit`)¶

Compliance auditing, NIST mapping, and SBOM enrichment.

Auditor¶

class quantum_safe.audit.auditor.Auditor[source]¶

Bases: object

Orchestrates PQC compliance auditing.

All methods are classmethods — no instantiation needed.

Example:

from quantum_safe.audit import Auditor, AuditPolicy

report = Auditor.audit(
    "./src",
    policy=AuditPolicy.strict(),
    metadata={"branch": "main", "commit": "abc123"},
)
print(report.summary_line())
if not report.passed:
    print(report.to_json())
    sys.exit(1)

classmethod audit(target, policy=None, metadata=None, exclude=None)[source]¶

Run a full audit on a directory or file.

Parameters:

target (str | Path) – Directory or file path to audit.
policy (AuditPolicy | None) – Compliance policy. Defaults to AuditPolicy() (standard).
metadata (dict[str, Any] | None) – Arbitrary metadata for the report (CI job ID, etc.).
exclude (list[str] | None) – Directory/file patterns to exclude from scanning.

Return type:

AuditReport

Returns:

AuditReport with all findings and policy evaluation.

classmethod audit_source(source, filename='<string>', policy=None, metadata=None)[source]¶

Audit a source string directly (useful in tests and CI hooks).

Parameters:

source (str) – Python source code as a string.
filename (str) – Virtual filename for error messages.
policy (AuditPolicy | None) – Compliance policy. Defaults to AuditPolicy().
metadata (dict[str, Any] | None)

Return type:

AuditReport

Returns:

AuditReport.

classmethod ci_gate(target, policy=None, output_sarif=None, output_json=None, metadata=None)[source]¶

Run audit and return a shell exit code.

Designed to be called directly from CI pipeline steps:

exit_code = Auditor.ci_gate("./src", output_sarif="audit.sarif")
sys.exit(exit_code)

Parameters:

target (str | Path) – Directory or file to audit.
policy (AuditPolicy | None) – Compliance policy. Defaults to AuditPolicy().
output_sarif (str | None) – If set, write SARIF to this path.
output_json (str | None) – If set, write full JSON report to this path.
metadata (dict[str, Any] | None) – Arbitrary metadata for the report.

Return type:

int

Returns:

0 if all policies pass, 1 if any violations found.

Policy¶

class quantum_safe.audit.policy.AuditPolicy(min_security_level=3, allow_classical_only=False, hybrid_required=True, allow_non_nist_standard=False, fail_on=<factory>, exempt_paths=<factory>, require_migration_state='hybrid_transition', max_classical_only_keys=None)[source]¶

Bases: object

Configurable policy for PQC compliance.

Parameters:

min_security_level (int) – Minimum NIST security level (1-5). Default 3 (ML-KEM-768 / ML-DSA-65 equivalent).
allow_classical_only (bool) – If False, any classical-only crypto finding at HIGH or above is a violation. Default False.
hybrid_required (bool) – If True, PQC must always be in hybrid mode. Default True (matches transition-period guidance).
allow_non_nist_standard (bool) – If False, non-NIST-standard algorithms (BIKE, HQC, etc.) are violations. Default False.
fail_on (list[str]) – Severity levels that cause policy failure. Default [“CRITICAL”, “HIGH”].
exempt_paths (list[str]) – File path patterns that are exempt from policy. Supports glob-style wildcards.
require_migration_state (str) – Minimum acceptable migration state for keys. Default “hybrid_transition”.
max_classical_only_keys (int | None) – If set, more than this many CLASSICAL_ONLY keys in the store is a violation. Default None (no limit).

is_exempt(filepath)[source]¶

Return True if the given filepath matches any exempt pattern.

Parameters:: filepath (str)
Return type:: bool

evaluate(findings)[source]¶

Evaluate findings against this policy.

Returns a list of violations. Empty list = policy satisfied.

Parameters:: findings (list[Finding])
Return type:: list[PolicyViolation]

classmethod from_file(path)[source]¶

Load policy from a JSON or YAML file.

YAML support requires PyYAML (pip install pyyaml). Falls back to JSON if PyYAML is not installed.

Parameters:: path (str | Path)
Return type:: AuditPolicy

classmethod strict()[source]¶

Pre-built strict policy: no classical crypto at all.

Return type:: AuditPolicy

classmethod transition()[source]¶

Pre-built transition-period policy: hybrid required, classical tolerated.

Return type:: AuditPolicy

classmethod permissive()[source]¶

Pre-built permissive policy: only critical findings fail.

Return type:: AuditPolicy

NIST compliance¶

class quantum_safe.audit.compliance.NISTComplianceChecker[source]¶

Bases: object

Evaluates NIST SP 800-208 / FIPS 203/204/205 compliance.

Takes a ScanReport and produces a ComplianceReport that maps each finding to a specific NIST control.

Usage:

from quantum_safe.audit.compliance import NISTComplianceChecker
from quantum_safe.migrate.scanner import Scanner

scan = Scanner.scan_directory("./src")
report = NISTComplianceChecker.check(scan, target="./src")
print(report.to_json())

classmethod check(scan_report, target='', metadata=None)[source]¶

Generate a NIST compliance report from a ScanReport.

Parameters:

scan_report (ScanReport) – Results from Scanner.scan_file/directory/source.
target (str) – What was scanned (for the report header).
metadata (dict[str, Any] | None) – Arbitrary metadata to include in the report.

Return type:

ComplianceReport

Returns:

ComplianceReport with one ComplianceControl per NIST requirement.

class quantum_safe.audit.compliance.ComplianceReport(generated_at, target, controls, overall_level, metadata=<factory>)[source]¶

Bases: object

Full NIST compliance report for a codebase.

generated_at¶: ISO 8601 timestamp.

target¶: What was assessed.

controls¶: All evaluated controls.

overall_level¶: Rolled-up compliance level.

Parameters:

generated_at (str)
target (str)
controls (list[ComplianceControl])
overall_level (ComplianceLevel)
metadata (dict[str, Any])

summary_lines()[source]¶

Human-readable summary for terminal output.

Return type:: list[str]

SBOM enrichment¶

class quantum_safe.audit.sbom.SBOMEnricher[source]¶

Bases: object

Enriches a CycloneDX SBOM with PQC-readiness annotations.

Usage:

with open("sbom.json") as f:
    sbom = json.load(f)

enriched, assessments = SBOMEnricher.enrich(sbom)

with open("sbom-pqc.json", "w") as f:
    json.dump(enriched, f, indent=2)

for a in assessments:
    if a.readiness == PQCReadiness.NOT_READY:
        print(f"NOT READY: {a.name} {a.version} - {a.action}")

classmethod enrich(sbom)[source]¶

Enrich a CycloneDX SBOM with PQC-readiness properties.

Parameters:: sbom (dict[str, Any]) – Parsed CycloneDX JSON SBOM (dict).
Return type:: tuple[dict[str, Any], list[ComponentAssessment]]
Returns:: (enriched_sbom, assessments) – enriched_sbom: The input SBOM with pqc-readiness properties added. assessments: One ComponentAssessment per component.

classmethod from_requirements(requirements_txt)[source]¶

Assess PQC readiness from a requirements.txt string.

Does not require a full SBOM — useful as a quick check during CI. Parses lines of the form:

cryptography==44.0.5
pycryptodome>=3.20.0
quantum-safe==0.1.0

Parameters:: requirements_txt (str) – Contents of a requirements.txt file.
Return type:: list[ComponentAssessment]
Returns:: List of ComponentAssessment objects.

class quantum_safe.audit.sbom.ComponentAssessment(name, version, readiness, reason, since_version=None, action='')[source]¶

Bases: object

PQC readiness assessment for a single SBOM component.

Parameters:

name (str)
version (str | None)
readiness (PQCReadiness)
reason (str)
since_version (str | None)
action (str)

Audit (quantum_safe.audit)¶

Auditor¶

Policy¶

NIST compliance¶

SBOM enrichment¶

Audit (`quantum_safe.audit`)¶