openentropy

Measure and operationalize hardware entropy for research and security.

Collect entropy from on-device hardware sources, analyze source quality with statistical tests, and deliver raw or conditioned output through CLI, Rust, Python, and HTTP interfaces.

One workflow for entropy research, validation, and cryptographic deployment.

By Amenti Labs

</div>

Quick Start

# Install
cargo install openentropy-cli

# Discover entropy sources on your machine
openentropy scan

# Benchmark all fast sources
openentropy bench

# Output 64 random hex bytes
openentropy stream --format hex --bytes 64

# Live TUI dashboard
openentropy monitor

By default, only fast sources (<2s) are used. Pass --all to include slower sources (DNS, TCP, GPU, BLE). The positional alias all is also accepted for compatibility.

External QRNG hardware

Most OpenEntropy sources come from the host machine itself. OpenEntropy also supports external hardware devices when they are attached and discoverable:

Crypta Labs QCicada USB QRNG — exposed as the qcicada source. OpenEntropy can read the device's quantum output and benchmark, analyze, record, or compare it alongside on-host sources. The device's own output modes map to raw, sha256, and samples, and OpenEntropy now uses QCicada's fresh-start continuous-mode helper from qcicada 0.2.2, so it discards already-buffered device input once after entering continuous mode instead of serving the first read from stale queued bytes. See the QCicada manual.

Python

pip install openentropy

from openentropy import EntropyPool, detect_available_sources

sources = detect_available_sources()
print(f"{len(sources)} entropy sources available")

pool = EntropyPool.auto()
source = sources[0]["name"]
data = pool.get_source_bytes(source, 256, conditioning="sha256")

Build from source (native extension):

git clone https://github.com/amenti-labs/openentropy.git && cd openentropy
pip install maturin
maturin develop

Two Audiences

Security engineers use OpenEntropy to validate entropy quality and seed CSPRNGs:

openentropy analyze --profile security --output audit.md

Researchers use OpenEntropy to study raw noise characteristics:

openentropy analyze --profile deep --output analysis.json

Security engineers seed CSPRNGs, generate keys, and supplement /dev/urandom with independent hardware entropy. The SHA-256 conditioned output (--conditioning sha256, the default) produces cryptographic-quality random bytes. The security profile enables the NIST test battery, min-entropy breakdown, and SHA-256 conditioning in one flag.

Researchers study the raw noise characteristics of hardware subsystems. Pass --conditioning raw to get unwhitened, unconditioned bytes that preserve the actual noise signal from each source. The deep profile enables 100K samples, cross-correlation, and PEAR-style trial analysis.

Raw mode enables:

Hardware characterization — measure min-entropy, autocorrelation, and spectral properties of individual noise sources
Silicon validation — compare noise profiles across chip revisions, thermal states, and voltage domains
Anomaly detection — monitor entropy source health for signs of hardware degradation or tampering
Cross-domain analysis — study correlations between independent entropy domains (thermal vs timing vs IPC)

What Makes This Different

Most random number generators are pseudorandom — deterministic algorithms seeded once. OpenEntropy continuously harvests real physical noise from your hardware:

Thermal noise — three independent oscillator beats (CPU crystal vs audio PLL, display PLL, PCIe PHY PLLs)
Timing and microarchitecture — clock phase noise, DRAM row buffer conflicts, speculative execution variance, TLB shootdowns, DVFS races, ICC bus contention, prefetcher state, APRR JIT timing, ANE clock domain crossing
I/O and IPC — disk and NVMe latency (including IOKit sensor polling, raw device, and Linux passthrough), USB enumeration, Mach port IPC, pipe buffer allocation, kqueue events, fsync journal
GPU and compute — GPU warp divergence, IOSurface cross-domain timing, Neural Engine inference timing
Scheduling and system — nanosleep drift, GCD dispatch queues, thread lifecycle, P/E-core migration, timer coalescing, kernel counters, process table snapshots
Network and sensors — DNS resolution timing, TCP handshake variance, WiFi RSSI, BLE ambient RF, audio ADC noise
Deep hardware — dual clock domain beats, SITVA, AES-XTS context switching, SEV broadcast, COMMPAGE seqlock, SMC thermistor, getentropy TRNG reseed

The pool XOR-combines independent streams. No single source failure can compromise the pool.

Conditioning Modes

Conditioning is optional and configurable. Use --conditioning on the CLI or ?conditioning= on the HTTP API:

| Mode | Flag | Description | |------|------|-------------| | SHA-256 (default) | --conditioning sha256 | SHA-256 conditioning. Cryptographic quality output. | | Von Neumann | --conditioning vonneumann | Debiasing only — removes bias while preserving more of the raw signal structure. | | Raw | --conditioning raw | No processing. Source bytes with zero whitening — preserves the actual hardware noise signal for research. |

Raw mode is what makes OpenEntropy useful for research. Most HWRNG APIs run DRBG post-processing that makes every source look like uniform random bytes, destroying the information researchers need. Raw output preserves per-source noise structure: bias, autocorrelation, spectral features, and cross-source correlations. See Conditioning for details.

Documentation

Docs site: https://amenti-labs.github.io/openentropy/
PyPI package: https://pypi.org/project/openentropy/

| Doc | Description | |-----|-------------| | Source Catalog | Source catalog with physics explanations and platform notes | | CLI Reference | Full command reference and examples | | Conditioning | Raw vs VonNeumann vs SHA-256 conditioning modes | | Trial Analysis Methodology | PEAR-style 200-bit trials, calibration gate, and references | | Telemetry Model | Experimental telemetry_v1 context model and integration points | | Rust API Reference | Core Rust API surface | | Architecture | Crate structure and design decisions | | Python SDK | PyO3 bindings and Python API reference | | Examples | Rust and Python code examples | | Troubleshooting | Common issues and fixes | | Security | Threat model and responsible disclosure |

Acknowledgments

The expanded statistical analysis roadmap and method inventory were informed by:

vikingdude81/qrng-analysis-toolkit

We appreciate the open-source work that helped shape this comparative QRNG/PRNG analysis surface.

Entropy Sources

The current source registry spans 13 mechanism-based categories; actual availability varies by platform:

| Category | Count | |----------|:-----:| | Thermal | 4 | | Timing | 7 | | Scheduling | 6 | | IO | 6 | | IPC | 4 | | Microarchitecture | 16 | | GPU | 3 | | Network | 3 | | System | 6 | | Signal | 3 | | Sensor | 4 | | Quantum | 1 |

For full per-source descriptions, platform availability, and physics notes, see Source Catalog.

Currently supported external hardware:

qcicada — Crypta Labs QCicada USB QRNG (manual)

CLI Reference

For the full command reference and examples, see CLI Reference.

Most-used workflows:

openentropy scan
openentropy bench
openentropy stream --format hex --bytes 64
openentropy analyze --profile security         # NIST battery + entropy + sha256
openentropy analyze --profile deep             # 100K + forensic + cross-corr + trials
openentropy record clock_jitter --duration 30s
openentropy sessions sessions/<id> --profile deep
openentropy compare sessions/<id-a> sessions/<id-b> --profile deep

On sessions, profile presets apply only when a specific session path is provided. openentropy sessions with no path always stays in list mode.

PEAR-style trial methodology references (200-bit tri

Openentropy

Install / Use

README