Architecture Overview
DuoKey PQC Scanner Architecture
Comprehensive overview of DuoKey PQC Scanner architecture, components, and operational modes
Introduction
The DuoKey PQC Scanner is a comprehensive Post-Quantum Cryptography (PQC) readiness assessment tool for high-performance, cross-platform cryptographic asset discovery and analysis.
High-Level Architecture
Data flow
Scanner architecture
Every scan follows the same five stages, from CLI dispatch to a formatted report; the risk scorer grades each finding from 0 to 10 with a P0 to P4 priority.
Architecture Flow
CLI Entry Point
Parses one of the scanner's subcommands (filesystem, domain, inventory, source-code, ci, cbom, qrs, ssh, fortinet, jfrog, terraform, cloud, vault, agent, enroll, upload-scan, and feature-gated packet-capture / network). Validates inputs and dispatches to the corresponding scanner.
Scanner Execution
The selected scanner collects raw cryptographic data -- TLS handshakes, certificate files, source code patterns, cloud KMS metadata, or SSH host keys. Scanners run concurrently and parallelize file traversal where applicable.
Parser Layer (PEM / DER / PKCS#12)
Raw data is fed to format-specific parsers that extract certificate metadata, key algorithms, and signature schemes.
Risk Scoring (0-10)
Each parsed finding passes through the risk scorer, which assigns a quantum risk score from 0 to 10, maps it to a severity level (Critical through Info), assigns a priority (P0-P4), and generates recommendations.
Output Formatting
The scored result is serialized by the chosen output formatter -- JSON, YAML, HTML, ANSI terminal, or CycloneDX 1.7 CBOM -- and written to file or stdout.
Module Architecture
The scanner is organized into distinct functional areas, each with a focused responsibility:
| Area | Responsibility |
|---|---|
| CLI | Command-line parsing and command dispatch |
| Core | Crypto algorithm detection, quantum risk scoring, X.509 operations, and the crypto algorithms database |
| Scanners | One module per scan kind -- host inventory, filesystem, domain/TLS, source code, SSH, Fortinet, JFrog, Terraform, cloud KMS, vault, and (feature-gated) offline packet capture / live network capture |
| Parsers | Format parsers for JKS, PKCS#12, PEM, DER, and nginx/apache configuration files |
| Output | Output formatters -- JSON, YAML, SARIF (for CI/CD), and terminal |
| Utilities | Logging, error handling, and OS-specific helpers |
Core Scanning Modes
The scanner covers several discovery scenarios; these four are the most commonly used entry points (see CLI Reference for the full command list):
1. Inventory Mode - Host Scanner
One-shot, full local-host cryptographic discovery: filesystem certificate sweep, SSH keys, and (Windows) certificate store, installed apps, and registry policy. Elevated privileges recommended for complete results.
2. Filesystem Mode - File & Keystore Scanner
Recursive search for certificates and keystores in specified directories. Supports JKS, PKCS#12, PEM, DER, and configuration files. Parallel processing for large directory trees.
3. Domain Mode - TLS/SSL Scanner
External TLS connection analysis for domains and IP addresses. Multi-version TLS testing, certificate chain extraction, cipher suite enumeration; add --pqc for the readiness report.
4. Network Mode - Live Packet Capture
Live network-interface capture for TLS/SSH handshake inspection (feature-gated). For offline analysis of an existing .pcap file, see Packet Capture.
Quantum Risk Scoring Algorithm
The scanner uses a multi-criteria scoring system that blends several weighted factors into a final score from 0 to 100, which is then mapped to a priority level. The factors and their weights are:
| Factor | Weight |
|---|---|
| Quantum risk | 30% |
| Business criticality | 25% |
| Data sensitivity | 20% |
| Exposure | 10% |
| Compliance | 10% |
| Migration complexity | 3% |
| Migration cost | 2% |
The resulting score is mapped to one of five priority levels:
| Priority | Meaning | Recommended action |
|---|---|---|
| P0 | Critical | Immediate action required |
| P1 | High | Action within 3 months |
| P2 | Medium | Action within 6 months |
| P3 | Low | Action within 12 months |
| P4 | Info | Monitor |
Vulnerable Algorithms Detected
| Algorithm | Key Size | Quantum Risk Score | Severity |
|---|---|---|---|
| RSA | < 2048-bit | 10/10 | Critical |
| RSA | 2048-bit | 8/10 | High |
| RSA | 3072-bit | 6/10 | Medium |
| RSA | 4096-bit | 4/10 | Medium |
| ECDSA | P-256 | 8/10 | High |
| ECDSA | P-384 | 7/10 | High |
| ECDSA | P-521 | 6/10 | Medium |
| DSA | Any | 9/10 | Critical |
| 3DES | N/A | 10/10 | Critical |
| RC4 | N/A | 10/10 | Critical |
Output Formats
The scanner supports multiple output formats for different use cases:
The default machine-readable format. Each JSON report contains the scan metadata, the list of findings, a risk summary, and a set of recommendations.
Performance Characteristics
Scalability
- TLS Endpoints: Can scan thousands per hour
- Filesystem: Processes 100K+ files efficiently with parallel scanning
- Memory: Low memory footprint (<100MB typical)
- CPU: Multi-threaded for optimal performance
Benchmarks
Filesystem scanning is highly efficient; throughput is environment-dependent — as an indicative figure, on the order of 1,000 PEM certificates process in tens of milliseconds.
Cross-Platform Support
| Platform | Status | Notes |
|---|---|---|
| Linux | Full Support | Preferred platform, all features |
| macOS | Full Support | Intel & Apple Silicon |
| Windows | Full Support | Windows 10/11, Server 2019+ |
Integration Capabilities
The scanner can be embedded as a library. A caller configures a scan -- choosing the mode (for example, domain), the targets, and the output format -- runs it, and reads back the results, including the overall PQC readiness score.
Security Considerations
Privilege Requirements
| Mode | Privilege Required |
|---|---|
| Agent Mode | Requires root/admin for full system access |
| Network Mode | Requires CAP_NET_RAW or equivalent |
| Filesystem Mode | Standard user privileges sufficient |
| Domain Mode | Standard user privileges sufficient |
Data Protection
Private keys are never extracted or exported. Only metadata and public information are collected. All network communication is encrypted (TLS 1.3). Audit logging is enabled for all operations.