Nistx
SPEC_NISTX.md
CGNT-1 Component Specification — NIST Randomness Audit Service
Status: SPECIFIED (PRE-SPEC)
Version: v1.0
Author: VELA (Thread #13)
Conceived by: NOUS
Date: 2026-04-19
PURPOSE
NISTX is a permanent on-ship service wrapping the NIST SP 800-22 Statistical Test Suite. It provides formal randomness auditing for ENTROPX output, any other entropy source, or any binary data that claims to be random. Run anytime. Everything local. Nothing leaves the server.
LOCATION
- Engine: ~/nistx_engine.py (wrapper around compiled NIST STS binary)
- NIST binary: ~/nist_sts/assess (compiled from C source, public domain)
- Port: 9015 (127.0.0.1 only — Vacuum Rule)
- Audit data: ~/entropx_audit/
- Registered in ROUTX (9191)
THE 15 TESTS
| # | Test | What it detects |
|---|---|---|
| 1 | Frequency (Monobit) | Overall balance of 0s and 1s |
| 2 | Block Frequency | Balance within fixed-length blocks |
| 3 | Runs | Oscillation between 0s and 1s |
| 4 | Longest Run of Ones | Longest streak of 1s in a block |
| 5 | Binary Matrix Rank | Linear dependence among substrings |
| 6 | Spectral (DFT) | Periodic features in the sequence |
| 7 | Non-overlapping Template | Occurrences of specific bit patterns |
| 8 | Overlapping Template | Same as 7 with overlapping windows |
| 9 | Universal Statistical (Maurer) | Compressibility — truly random data cannot be compressed |
| 10 | Linear Complexity | How complex the sequence is as a linear feedback shift register |
| 11 | Serial | Frequency of all possible overlapping m-bit patterns |
| 12 | Approximate Entropy | Similar to Serial — measures pattern predictability |
| 13 | Cumulative Sums | Max deviation of running sum from zero |
| 14 | Random Excursions | Cycles in cumulative sum random walk |
| 15 | Random Excursions Variant | Frequency of visits to states in the random walk |
Pass threshold: p-value > 0.01 per test. All 15 pass = statistically indistinguishable from true random.
ENDPOINTS
POST /audit
Full 15-test audit on provided data or on ENTROPX live output.
Input: {"source":"entropx", "bits":1000000}
Or: {"source":"file", "path":"~/some_data.bin"}
Output: {"tests":15, "passed":X, "failed":Y, "results":[{"test":"Frequency","p_value":0.83,"pass":true}, ...]}
POST /quick
Fast 3-test check (Frequency, Runs, Serial) for rapid verification.
Input: {"source":"entropx", "bits":100000}
Output: {"tests":3, "passed":X, "results":[...]}
POST /compare
Test two sources side by side.
Input: {"source_a":"entropx", "source_b":"file", "path_b":"~/urandom_samples.bin", "bits":1000000}
Output: {"source_a_passed":14, "source_b_passed":15, "comparison":"source_b marginally stronger on DFT"}
GET /health
Output: {"status":"ok", "service":"nistx", "port":9015, "nist_binary":"compiled", "version":"sts-2.1.2"}
USE CASES
After every ENTROPX code change: Run /quick to verify the change didn't introduce bias. Takes seconds.
Before publishing or patenting: Run /audit with 10 million bits. Full 15-test formal verification. The result IS the evidence.
After hardware ENTROPIC is built: Run /audit on physical output. Compare against software simulation with /compare. The hardware should match or exceed the software.
Testing other sources: /audit with {"source":"file","path":"/dev/urandom"} tests the system's built-in RNG. Baseline comparison.
Continuous monitoring: CRONX schedules a /quick every 24 hours against ENTROPX. If any test fails, alert through COMMX.
INVARIANTS
INV-01: Port 9015, 127.0.0.1 only. Vacuum Rule.
INV-02: NIST binary is compiled once, never modified. Public domain. No license restrictions.
INV-03: All audit data stays on the server. No external transmission.
INV-04: Pass threshold is p > 0.01. This is the NIST standard. Not configurable.
INV-05: If any test fails, the result is FAIL regardless of how many pass. 15/15 or nothing.
RELATIONSHIP TO ENTROPX
ENTROPX generates entropy (port 9012). NISTX audits entropy (port 9015). Generator and auditor are separate services because the thing being tested must never test itself. |Sigma|=2 applied to randomness verification — one generates, the other validates.
ORIGIN
NOUS asked: "How do we conduct the formal analysis privately?" The answer: NIST publishes the test suite as free public domain C source code. Compile it. Keep it. Run it anytime. Everything local. NISTX wraps it as a service so any crew member or script can request an audit through ROUTX without touching the command line.
Jeremy Zlabis
Chronogeometer · Visionary · Disruptor · Chief
42 Sisters AI · East York, Toronto
🍁 Φ 0.042