pqaudit - Post-Quantum TLS Audit Tool

Problem Statement

Organizations need to assess their TLS infrastructure for post-quantum cryptography (PQC) readiness as quantum computers threaten to break current public-key cryptography. Existing tools either focus on client-side PQC support or lack comprehensive scanning capabilities for server-side PQC evaluation against multiple compliance frameworks (NIST IR 8547, CNSA 2.0, FIPS 140-3).

Solution Architecture

pqaudit provides a comprehensive TLS scanning solution that evaluates server-side PQC support and generates actionable reports:

Technical Implementation

Core Components

1. Connection Handler: Manages TLS connections with customizable timeouts and SNI override
2. PQC Handshake Probe: Tests hybrid key exchange with X25519MLKEM768 and MLKEM1024 offers
3. Cipher Suite Enumerator: Exhaustively tests TLS 1.2/1.3 cipher suites via raw ClientHello crafting
4. Downgrade Detector: Identifies servers accepting TLS versions below 1.3
5. HelloRetryRequest Detector: Finds servers requiring retries for PQC group negotiation
6. Certificate Chain Analyzer: Validates certificate algorithms against deprecation timelines
7. Scoring Engine: Implements weighted rubric across five categories (key exchange 50pts, TLS version 15, cipher suite 15, certificate chain 15, downgrade posture 5)
8. Risk Assessment: Calculates Harvest-Now-Decrypt-Later (HNDL) exposure based on algorithm longevity
9. Report Generator: Produces multiple output formats for different consumption patterns

Key Implementation Details

• Language: Rust for memory safety and performance
• TLS Libraries: Uses rustls and aws-lc-rs for cryptographic operations
• Scanning Modes:
  • Default: Targeted PQC probing with specific key share offers
  • Full scan (--full-scan): Exhaustive cipher suite enumeration via raw ClientHello
  • STARTTLS support: SMTP, IMAP, POP3 protocol upgrades before TLS probing
• Output Formats:
  • Human-readable: Color-coded terminal output with icons and HNDL ratings
  • JSON: Default structured output for programmatic consumption
  • SARIF 2.1.0: For GitHub Code Scanning and IDE integration
  • CycloneDX 1.5 CBOM: Cryptographic Bill of Materials listing observed algorithms
  • Baseline diff: Compares current results against saved baselines to detect regressions
• Compliance Modes:
  • nist (default): NIST IR 8547 - Hybrid key exchange; classical algorithms deprecated
  • cnsa2: NSA CNSA 2.0 - ML-KEM-1024 mandatory; exclusive PQC by 2033
  • fips: FIPS 140-3 - FIPS-approved algorithms only; binary gate scoring
• CI/CD Integration:
  • Exit codes for gating pipelines (--fail-below threshold)
  • GitHub Action for automated scanning and SARIF upload to Code Scanning

Data Flow Diagram

Dependencies

Production Dependencies

• rustls: Modern TLS library written in Rust
• aws-lc-rs: Rust bindings to Amazon’s libcrypto
• serde: Serialization framework for Rust
• serde_json: JSON serialization for Serde
• clap: Command-line argument parser
• reqwest: HTTP client for web-based operations
• url: URL parsing and manipulation
• ipnet: IP network handling for SNI override
• chrono: Date and time handling
• regex: Regular expression library
• thiserror: Error handling derivation
• sarif: SARIF 2.1.0 schema implementation
• cyclonedx: CycloneDX 1.5 CBOM generation

Development Dependencies

• tokio: Asynchronous runtime for testing
• assert_cmd: Command testing utilities
• predicates: Predicate assertions for testing
• tempfile: Temporary file handling for tests
• mockall: Mocking framework for unit tests

Technical Limitations & Considerations

Scanning Limitations

• WAF/Rate Limiting: Sequential ClientHello probing in --full-scan mode may produce false negatives against WAF-protected or rate-limited targets
• Point-in-Time Assessment: Results reflect server configuration at time of scan; dynamic configurations may change between scans
• SNI Dependencies: Virtual hosting may require correct SNI for accurate results
• Certificate Chains: Relies on server-provided certificate chain; incomplete chains may affect validation accuracy

Compliance Considerations

• Algorithm Timelines: Based on published NIST/NSA/NIST guidelines; actual migration deadlines may vary by jurisdiction or sector
• Hybrid Detection: Identifies PQC key exchange but doesn’t quantify classical fallback usage
• Certificate Assessment: Focuses on algorithm deprecation; doesn’t evaluate key length or signature scheme weaknesses beyond quantum vulnerability

Performance Characteristics

• Connection Efficiency: Connection reuse where possible; minimal handshake overhead
• Scan Duration: Typical scans complete in seconds; --full-scan may take minutes depending on target responsiveness
• Resource Usage: Low memory footprint; single binary with no runtime dependencies

Use Cases

Security Operations

• Vulnerability Management: Regular scanning for PQC gaps in public-facing infrastructure
• Compliance Reporting: Demonstrating adherence to emerging PQC mandates
• Vendor Assessment: Evaluating third-party service PQC readiness
• Incident Response: Post-incident analysis of cryptographic exposure

Development & DevOps

• CI/CD Gates: Preventing deployment of services with inadequate PQC readiness
• Pre-launch Validation: Ensuring new services meet PQC requirements before production
• Configuration Drift Detection: Baseline tracking to identify unauthorized TLS configuration changes
• Local Development: Validating development environment PQC support

Research & Planning

• Migration Planning: Identifying systems requiring PQC upgrades
• Risk Quantification: Measuring HNDL exposure for executive reporting
• Benchmarking: Comparing PQC adoption across industries or geographic regions
• Academic Research: Studying real-world PQC deployment patterns

Architecture Deep Dive

Module Responsibilities

Connection Handling

• Establishes TLS connections with configurable parameters
• Manages timeouts, SNI override, and protocol selection
• Handles STARTTLS negotiation for email protocols

PQC Probing

• Sends ClientHello with specific PQC key share offers (X25519MLKEM768, MLKEM1024)
• Records whether server negotiates hybrid or classical key exchange
• Detects HelloRetryRequest requirements for PQC groups

Cipher Enumeration

• Constructs valid ClientHello messages for TLS 1.2 and 1.3
• Iterates through supported cipher suites
• Handles server alerts and invalid suite responses gracefully

Certificate Analysis

• Parses and validates certificate chains
• Checks signature algorithms against deprecation timelines
• Reports key usage and extension compliance

Scoring Engine

• Implements weighted rubric across five categories
• Applies compliance-mode specific weightings and thresholds
• Generates normalized 0-100 score

Risk Assessment

• Maps algorithms to longevity estimates
• Calculates HNDL exposure based on data sensitivity and algorithm lifespan
• Applies sensitivity modifiers for classified information handling

Reporting

• Formats results for multiple output targets
• Generates CBOM with observed algorithms and properties
• Produces SARIF for security tool integration
• Creates human-readable summaries with actionable findings

Security Considerations

• No sensitive data storage; all information ephemeral during scan
• Respects rate limits through configurable concurrency and delays
• No attempt to bypass security measures beyond standard TLS probing
• All cryptographic operations use vetted libraries (rustls, aws-lc-rs)
• Binary is statically linked with no runtime dependencies

Performance Characteristics

Scanning Speed

• Default PQC probe: Typically <5 seconds per target
• Full cipher enumeration: Variable based on suite support and network conditions
• Concurrent scanning: Limited by --concurrency flag (default: 10)

Resource Usage

• Memory: Typically <50MB during operation
• CPU: Bursty during handshake and cryptographic operations
• Network: Minimal bandwidth usage; primarily TLS handshakes

Reliability Features

• Connection timeout handling with configurable --timeout
• Graceful degradation for partial scan failures
• Detailed error reporting for troubleshooting
• Deterministic output formats for automation

Testing & Reliability

Test Strategy

• Unit tests for cryptographic and parsing logic
• Integration tests with mock TLS servers
• Fuzz testing for malformed input handling
• Golden file testing for output format consistency

Reliability Features

• Comprehensive error handling with contextual messages
• Input validation at all entry points
• Type safety throughout prevents runtime errors
• Deterministic behavior for identical inputs

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.

Disclaimer

pqaudit evaluates what TLS servers support during the handshake. Whether connecting clients actually negotiate PQC depends on client library configuration and version. Users should verify client-side PQC support separately using appropriate tools for their specific client stacks (browsers, language-specific TLS libraries, etc.).

Developed with AI assistance (Claude, Anthropic). Code reviewed and maintained by human contributors who take full responsibility for correctness and quality.