CPU Throttling Guide - TYCHON Quantum Readiness

🎯 CPU Throttling Overview

The -cputhrottle flag provides comprehensive control over CPU usage across all resource-intensive operations in the TYCHON Quantum Readiness. This feature prevents system overload, ensures smooth operation alongside other applications, and provides predictable performance characteristics.

Supported values are none, low, medium, and high (case-sensitive). Omitting -cputhrottle selects medium. An unsupported value emits a warning naming the invalid value and the applied medium fallback to the console and, when configured, the scan log. The scan continues; the invalid value alone does not cause a nonzero exit or prevent report creation. The fallback preserves the existing default limits: 75% target CPU, adaptive throttling, and 75% of CPU cores rounded up with a minimum concurrency of 2 and a maximum of 16.

✅ Key Benefits

• Prevents system resource exhaustion
• Reduces memory consumption by 40-70%
• Allows concurrent workload execution
• Adaptive throttling based on system load

🚀 Quick Start

# Default (medium throttling)
certscanner -mode local -cipherscan

# High performance scanning
certscanner -mode local -cipherscan -cputhrottle none

# Resource-conscious scanning
certscanner -mode local -cipherscan -cputhrottle low

⚙️ Throttle Levels Explained

🔥 None

Concurrency: 2x CPUs

CPU Target: 100%

Best For: Dedicated systems, overnight scans

⚠️ May cause system slowdown

🐢 Low

Concurrency: 0.5x CPUs

CPU Target: 50%

Best For: Production servers, active workstations

✓ Minimal system impact

⚡ Medium

Concurrency: 1x CPUs

CPU Target: 70%

Best For: General use, balanced performance

✓ Default - Recommended

🚀 High

Concurrency: 1x CPUs

CPU Target: 90%

Best For: Fast scans, idle systems

✓ Optimal speed/resource balance

📊 Real-World Performance Metrics

Based on testing with a 14-core system scanning 516 cipher suites and 2,300+ filesystem certificates:

Metric	None	Low	Medium	High
CPU Usage	100%	50%	70%	90%
Memory Usage	~5.2 MB	~1.3 MB	~2.6 MB	~2.6 MB
Scan Time (relative)	1.0x	4.0x	2.0x	1.5x
Concurrent Operations	28	7	14	14
Filesystem Workers	56	14	28	28
System Responsiveness	Poor	Excellent	Good	Fair

💾 Memory Efficiency Gains

Without Throttling (None):

• Peak Memory: 5.2 MB
• Buffer Allocations: 516+ per operation
• Goroutines: 28-56 concurrent
• Risk: Can reach GB-scale with large CIDR blocks

With Throttling (Low):

• Peak Memory: 1.3 MB (-75%)
• Buffer Allocations: 100 max (capped)
• Goroutines: 7-14 concurrent
• Risk: Protected against memory exhaustion

🗂️ Memory on Large Filesystems

Filesystem scans (-scanfilesystem and the per-application config scan) retain only files that match a certificate, key, keystore, config or encrypted-file pattern. The shared walk cache holds at most 200,000 entries across all roots, including concurrent walks still buffering entries. Walks that do not fit are streamed to consumers and walked again by later scanner phases. Certificate and config candidates are processed incrementally; config references are resolved before directly embedded material. This limits retained discovery metadata, not total process memory: directory traversal and report findings can still require additional memory.

Files scanned	Before	After
600,000	268 MB peak	122 MB peak
3,600,000	1,092 MB peak	117 MB peak

Measured on Linux with -scanmemory -scanfilesystem -cputhrottle high. Before the change, memory grew by roughly 0.3 KB per file for the life of the scan.

Soft memory limit

The throttle level also sets a Go runtime soft memory limit, so the garbage collector works harder as the heap approaches it. Set GOMEMLIMIT in the environment to override it.

• none: no limit
• low: 512 MiB
• medium: 1 GiB
• high: 2 GiB

Note that high is the least throttled setting that still applies throttling: none is unthrottled, low is the most throttled. The Linux in-memory certificate scan also honors the throttle delay between large memory regions.

🔧 Operations Affected by CPU Throttling

CPU throttling comprehensively controls resource usage across all scanner operations:

🔐 Cryptographic Operations

✓
Cipher Suite Enumeration
TLS/SSL cipher testing and negotiation
✓
Certificate Analysis
X.509 certificate parsing and validation
✓
SSH Key Exchange
SSH protocol negotiation and testing

📁 Filesystem Operations

✓
Certificate Discovery
PEM, DER, CRT, CER file scanning
✓
Outlook Archive Scanning
PST, OST, PAB file analysis
✓
Trust Store Analysis
System and Java keystore inspection

🌐 Network Operations

✓
Port Scanning
Local and remote port discovery
✓
Host Discovery
Multi-host parallel scanning
✓
DNS Enumeration
Subdomain discovery and resolution

💻 System Operations

✓
Memory Scanning
Process crypto library detection
✓
VPN Client Detection
30+ VPN client identification
✓
IPSec Tunnel Analysis
IKE/IPSec configuration parsing

🎯 Recommended Use Cases

Production Server Scanning

certscanner -mode remote -host production.example.com -cipherscan -cputhrottle low

Why Low: Minimizes impact on production services, uses only 50% CPU, allows normal server operations to continue unimpeded.

Developer Workstation

certscanner -mode local -scanfilesystem -cputhrottle medium

Why Medium: Default setting provides good balance, allows concurrent development work while scanning completes reasonably quickly.

Overnight Security Audit

certscanner -mode remote -host 10.0.0.0/16 -cipherscan -cputhrottle high

Why High: Maximizes scanning speed during off-hours, completes comprehensive audits faster while system is idle.

CI/CD Pipeline Integration

certscanner -mode local -quickscan -cputhrottle low -output report.json

Why Low: Ensures pipeline stability, prevents build agent resource exhaustion, predictable execution time.

Dedicated Security Scanner

certscanner -mode remote -host targets.txt -cipherscan -cputhrottle none

Why None: Maximizes throughput on dedicated hardware, completes large-scale assessments in minimum time.

✅ Best Practices & Recommendations

👍 Do's

✓
Start with Medium (default)
Test and adjust based on system response
✓
Use Low for production systems
Prioritize stability over speed
✓
Monitor with -logfile
Track performance metrics and throttling effects
✓
Consider scan scope
Large CIDR blocks need more aggressive throttling
✓
Use High for idle periods
Maximize efficiency during maintenance windows

❌ Don'ts

✗
Avoid None on shared systems
Can cause severe performance degradation
✗
Don't scan /8 networks without throttling
16M+ IPs can exhaust memory
✗
Don't ignore memory warnings
High memory alerts indicate throttling needed
✗
Avoid frequent throttle changes
Let adaptive throttling stabilize
✗
Don't disable for "speed"
Often counterproductive due to resource contention

⚠️ Critical Warning: Large Network Scans

Scanning large CIDR blocks (e.g., /8, /16) without proper throttling can cause:

• Memory exhaustion (GB-scale allocations)
• System crashes (especially on Windows)
• Network infrastructure overload
• Security monitoring alerts

Always use -cputhrottle low or medium for large-scale scans!

🔬 Technical Implementation Details

Adaptive Throttling Algorithm

                            // Concurrency calculation

                            base = NumCPU() * multiplier

                            // Throttle multipliers:

                            none: 2.0x CPUs

                            low: 0.5x CPUs

                            medium: 1.0x CPUs

                            high: 1.0x CPUs

                            // I/O operations get 2x boost

                            filesystem_workers = base * 2

                            port_scan_workers = base * 2

                            // CPU-bound stay at base

                            cipher_workers = base

                            dns_workers = base

Memory Protection

                            // Buffer size caps

                            channel_buffer = min(workers*2, 100)

                            // CIDR expansion limits

                            max_ips_per_cidr = 65536

                            // Memory pressure detection

                            danger_threshold = 1GB

                            if memory > threshold {

                              force_gc()

                              log_warning()

                            }

                            // Automatic cleanup

                            monitor_interval = 20s

                            gc_on_high_memory = true

Performance Monitoring Output Example:

                        PERFORMANCE: Starting monitoring - Initial: RAM=0.84MB, CPU=2.0%, Goroutines=1, PID=44941

                        CPU_THROTTLE: Level=medium, MaxConcurrent=14, MaxCPU=70.0%, Adaptive=true, CPUs=14

                        Using 28 worker threads for filesystem scanning

                        PERFORMANCE: RAM=2.6MB, CPU=68.0%, Goroutines=28, Time=14:26:34

                        PERFORMANCE: RAM=2.4MB, CPU=65.0%, Goroutines=24, Time=14:26:54

📝 Version History

v1.0.58 - Extended CPU Throttling

• Applied throttling to filesystem, port scanning, and DNS operations
• Added CIDR expansion limits (max 65,536 IPs)
• Fixed memory leak preventing 57.9GB allocation on /8 networks

v1.0.55 - Initial CPU Throttling

• Introduced -cputhrottle flag with four levels
• Applied to cipher scanning operations
• Added adaptive throttling based on system load