\n\n![\"Revizor](\"./assets/logo.svg#only-light\")
\n![\"Revizor](\"./assets/logo-light.svg#only-dark\")
\n\n
\n\n\n\n\nHardware fuzzing for the age of speculation
\n\n\n\n- __:fontawesome-solid-arrow-right: Get Started__\n\n ---\n\n
\n\n---\n\n## __:fontawesome-solid-bug: Trophies__{ .trophies-header }\n\n#### Transient Scheduler Attack - L1 Cache (TSA-L1)\n\n=== \"Description\"\n A speculative leak affecting AMD Family 19h processors where false completions in load instructions can leak data from the L1 data cache across security boundaries. The attack exploits the linear address-based microtag system used for L1 cache lookups - when a load finds a matching microtag entry but the L1 doesn't contain valid data, invalid data from the matching microtag entry is used in a false completion. This leak enables information disclosure between kernel/userspace, hypervisor/guest, across different applications or VMs, and from SEV-SNP VMs to the host.\n=== \"CVE\"\n [CVE-2024-36357](https://nvd.nist.gov/vuln/detail/CVE-2024-36357)\n=== \"Links\"\n * More details in: [Enter, Exit, Page Fault, Leak: Testing Isolation Boundaries for Microarchitectural Leaks](https://aka.ms/enter-exit-leak)\n * AMD Security Advisory: [Advisory](https://www.amd.com/en/resources/product-security/bulletin/amd-sb-7029.html)\n\n\n#### Transient Scheduler Attack - Store Queue (TSA-SQ)\n\n=== \"Description\"\n A speculative leak affecting AMD Family 19h processors where false completions in Store-To-Load Forwarding operations can leak data from previous store instructions. When a load matches an older store's address but the store data isn't yet available, a false completion occurs using invalid data from a previously executed store that occupied the same store queue entry. This effect enables information leakage from the OS kernel to user applications, hypervisor to guest, and to a lesser extent, between application.\n=== \"CVE\"\n [CVE-2024-36350](https://cve.mitre.org/cgi-bin/cvename.cgi?name=2024-36350)\n=== \"Links\"\n * More details in: [Enter, Exit, Page Fault, Leak: Testing Isolation Boundaries for Microarchitectural Leaks](https://aka.ms/enter-exit-leak)\n * AMD Security Advisory: [Advisory](https://www.amd.com/en/resources/product-security/bulletin/amd-sb-7029.html)\n\n#### Control Register Speculation\n\n=== \"Description\"\n A speculative leak affecting AMD processors where user processes can speculatively infer control register values even when User Mode Instruction Prevention (UMIP) is enabled. This bypasses intended security boundaries by allowing unprivileged code to access system-level configuration information through speculative channels.\n=== \"CVE\"\n [CVE-2024-36348](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-36348)\n=== \"Links\"\n * More details in: [Enter, Exit, Page Fault, Leak: Testing Isolation Boundaries for Microarchitectural Leaks](https://aka.ms/enter-exit-leak)\n * AMD Security Advisory: [Advisory](https://www.amd.com/en/resources/product-security/bulletin/amd-sb-7029.html)\n\n#### TSC_AUX Speculation\n\n=== \"Description\"\n A speculative leak affecting AMD processors affecting AMD processors that permits user processes to infer the Time Stamp Counter Auxiliary (TSC_AUX) register value even when direct reads are disabled.\n=== \"CVE\"\n [CVE-2024-36349](https://nvd.nist.gov/vuln/detail/CVE-2024-36349)\n=== \"Links\"\n * More details in: [Enter, Exit, Page Fault, Leak: Testing Isolation Boundaries for Microarchitectural Leaks](https://aka.ms/enter-exit-leak)\n * AMD Security Advisory: [Advisory](https://www.amd.com/en/resources/product-security/bulletin/amd-sb-7029.html)\n\n\n#### Divider State Sampling (DSS)\n\n=== \"Description\"\n A speculative leak where division-by-zero operations can transiently return values that depend on previous division operations. The leaked state persists across privilege boundaries. The discovery of the leak triggered a patch to the Linux kernel as well as other operating systems.\n=== \"CVE\"\n [CVE-2023-20588](https://nvd.nist.gov/vuln/detail/CVE-2023-20588)\n=== \"Links\"\n More details in: [Speculation at Fault](https://www.usenix.org/system/files/usenixsecurity23-hofmann.pdf)\n\n#### String Comparison Overrun (SCO)\n\n=== \"Description\"\n Revizor discovered that string operations on Intel and AMD CPUs (in particular, string comparison and string scan) can speculatively bypass the bounds of their target strings, which permits the attacker to leak data from out-of-bounds memory locations.\n=== \"Links\"\n More details in: [Hide & Seek with Spectres](https://www.microsoft.com/en-us/research/publication/hide-and-seek-with-spectres-efficient-discovery-of-speculative-information-leaks-with-random-testing/)\n\n#### Zero Dividend Injection (ZDI)\n\n=== \"Description\"\n 64-bit division operations on Intel CPUs can speculative ignore the upper bits of the divisor, thus producing an incorrect computational result. This speculation can potentially impact the security of cryptographic algorithms that use division to implement modulo operations.\n=== \"Links\"\n More details in: [Hide & Seek with Spectres](https://www.microsoft.com/en-us/research/publication/hide-and-seek-with-spectres-efficient-discovery-of-speculative-information-leaks-with-random-testing/)\n\n#### Read-Modify-Write Speculation\n\n=== \"Description\"\n A new variant of Microarchitectural Data Sampling (MDS) where a store operation to read-only memory triggers speculative behavior. When a read-modify-write instruction (like XADD) attempts to access read-only memory, it speculatively returns stale data from internal CPU buffers, even though the read itself would be permitted.\n=== \"Links\"\n More details in: [Speculation at Fault](https://www.usenix.org/system/files/usenixsecurity23-hofmann.pdf)\n\n#### Non-canonical Store Forwarding\n\n=== \"Description\"\n A speculative leak where stores to non-canonical addresses can be forwarded to subsequent loads from the canonical versions of those addresses. This means that even though a store operation fails due to an invalid address format, its data can still be transiently accessed by later instructions using a related valid address.\n=== \"Links\"\n More details in: [Speculation at Fault](https://www.usenix.org/system/files/usenixsecurity23-hofmann.pdf)\n\n#### Variable-latency Spectre\n\n=== \"Description\"\n A variant of Spectre vulnerability where the leakage is caused by the race condition that appears when a speculative memory access is data-dependent on a variable-latency instruction. This race condition can expose the operands of the variable-latency instruction.\n=== \"Links\"\n More details in [the Revizor paper](https://www.microsoft.com/en-us/research/publication/revizor-testing-black-box-cpus-against-speculation-contracts/)\n\n#### Store-based Spectre V1\n\n=== \"Description\"\n Several defense proposals (e.g., STT, KLEESpectre) assumed that stores do not modify the cache state until they retire. We used Revizor to validate this assumption, and discovered that is not true on recent Intel CPUs (e.g., CoffeeLake).\n=== \"Links\"\n More details in [the Revizor paper](https://www.microsoft.com/en-us/research/publication/revizor-testing-black-box-cpus-against-speculation-contracts/)\n\n#### Speculative Store with Forwarding\n\n=== \"Description\"\n Revizor discovered that two consecutive loads from the same address can speculatively return two different values if one of them receives a forwarded value from a store while the other load experiences a speculative store bypass. This combination exposes more information to the attacker compared to the original store bypass.\n=== \"Links\"\n More details in [the appendix to the Revizor paper](https://www.microsoft.com/en-us/research/publication/revizor-testing-black-box-cpus-against-speculation-contracts/)\n\n\n"
},
{
"path": "docs/internals/architecture/analysis.md",
"content": "| | |\n| ---------------- | ------------------ |\n| Module | `rvzr/analyser.py` |\n| Public interface | `Analyser` |\n| Inputs | `CTrace`, `HTrace` |\n| Outputs | `Violation` |\n\nThe Analyser compares contract traces with hardware traces to detect violations. The core principle: inputs with identical CTraces should produce equivalent HTraces. When they don't, a contract violation has occurred.\n\n```python\nFor all inputs i, j:\n if CTrace(i) == CTrace(j) and HTrace(i) != HTrace(j):\n → Violation detected\n```\n\nAnalyser implementations:\n\nDifferent analysers define \"equivalent HTrace\" differently:\n\n- `MergedBitmapAnalyser` (default) — Merges samples using bitwise OR, compares bitmaps. For cache-based channels.\n- `SetAnalyser` — Compares sets of unique samples.\n- `MWUAnalyser` — Uses Mann-Whitney U statistical test. For timing-based channels.\n- `ChiSquaredAnalyser` — Uses chi-squared test for distribution differences.\n"
},
{
"path": "docs/internals/architecture/code.md",
"content": "# Test Case Code Generation\n\n| | |\n| ---------------- | ------------------------ |\n| Module | `rvzr/code_generator.py` |\n| Public interface | `CodeGenerator` |\n| Inputs | `InstructionSet` |\n| Outputs | `TestCaseProgram` |\n\nThis module generates random assembly programs for testing. The generator creates programs designed to trigger speculative execution and expose microarchitectural leaks.\n\n### Generation process\n\n1. Create control flow graph — Generate a random Directed Acyclic Graph (DAG) of basic blocks. The DAG structure prevents infinite loops while allowing branches and mispredictions.\n\n2. Add jump instructions — Insert conditional and unconditional jumps at block boundaries to connect the blocks according to the DAG.\n\n3. Fill basic blocks — Populate blocks with random instructions from the tested instruction pool, respecting instruction frequencies and operand constraints.\n\n4. Instrument — (Optionally) Prevent faults by masking memory addresses, avoiding division by zero, and ensuring all accesses stay within the sandbox.\n\n5. Assemble — Convert to binary and extract metadata.\n\n6. Transform into RCBF — Serialize the test case into Revizor's custom binary format ([RCBF](../../ref/binary-formats.md)) for execution.\n\n### Test case representation\n\n```text\nTestCaseProgram\n ├─ CodeSection (one per actor)\n │ └─ Function\n │ └─ BasicBlock\n │ └─ InstructionNode\n │ └─ Instruction\n │ └─ Operand\n └─ TestCaseBinary\n └─ SymbolTable\n```\n\n### Variants\n\nArchitecture-specific implementations of the code generator exist for x86 and ARM64, named `X86Generator` and `ARM64Generator` in `rvzr/arch/*/code_generator.py`\n"
},
{
"path": "docs/internals/architecture/data.md",
"content": "# Test Case Data Generation\n\n| | |\n| ---------------- | ------------------------ |\n| Module | `rvzr/data_generator.py` |\n| Public interface | `DataGenerator` |\n| Inputs | `Config` |\n| Outputs | `InputData` |\n\n`DataGenerator` generates input data that is used to initialize registers and memory before executing a test case, on both the model and the target hardware.\n\n\n## Generation modes\n\nTwo input generation modes are supported:\n\n### Standard generation\n\nInterface: `DataGenerator.generate(...)`\n\nThis method creates fully random inputs using a PRNG. Can optionally reduce entropy (to increase trace collisions) or inject special values (zeros, boundary values) to trigger edge cases.\n\n### Boosted generation\n\nInterface: `DataGenerator.generate_boosted(...)`\n\nBoosted generation solves the following challenge:\nTwo detect a violation via relational non-interference testing, we always need at least two inputs that produce identical contract traces (see [Trace Analysis](overview.md#6-trace-analysis)). Generating such contract-equivalent inputs through pure randomness is extremely inefficient because the entropy of contract traces is usually very high, and thus most random inputs produce unique traces.\n\nBoosted generation addresses this by leveraging dynamic taint analysis on the model side. It works as follows: Start by producing a set of random inputs using standard generation. Then, we execute the test case with each input in the model and perform backwards taint analysis to identify which input bytes affect the contract trace (tainted) and which don't (untainted). This produces a set of `InputTaint` objects that map input bytes to their taint status. These taint maps a fed back into the `generate_boosted()` method, which creates new inputs such that the tainted bytes remain fixed while the untainted bytes are randomized.\n\n```text\nOriginal InputData → Model → InputTaint → N contract-equivalent inputs\n```\n\nSuch \"boosted\" inputs are guaranteed to produce the same contract trace as the original input while still being mostly random.\n\n\n## Data Representation\n\nEach input is represented as an `InputData` object, which is a numpy structured array containing\n\n- Memory contents\n- General-purpose registers\n- SIMD registers\n- Flags and special registers\n\nfor each actor in the test case. This object can be serialized into Revizor's custom binary format ([RDBF](../../ref/binary-formats.md)) for consumption by the model and executor.\n"
},
{
"path": "docs/internals/architecture/exec.md",
"content": "# Hardware Tracing\n\n| | |\n| ---------------- | --------------------------------------- |\n| Module | `rvzr/executor.py`, `rvzr/executor_km/` |\n| Public interface | `Executor` |\n| Inputs | `TestCaseProgram`, `InputData` |\n| Outputs | `HTrace` |\n\n## Executor\n\nThe Executor runs test cases on real hardware and collects hardware traces (HTraces) using side-channel measurements. It uses a two-layer architecture: Python code communicates with a kernel module that performs measurements in kernel space.\n\n```text\nPython (executor.py)\n ├─ X86IntelExecutor\n ├─ X86AMDExecutor\n └─ ARM64Executor\n │\n │ /sys/rvzr_executor/ interface\n ▼\nKernel Module (executor_km/)\n```\n\n## HTrace representation\n\nThe `HTrace` class (`rvzr/traces.py`) represents hardware traces collected during execution. The executor produces one `HTrace` object per program-input pair, meaning that for each `TestCaseProgram` execution with each `InputData` input, one `HTrace` is generated.\n\nEach `HTrace` encapsulates multiple measurements results (samples): This is because the executor typically repeats the execution several times and each execution produces one measurement sample. Such repeated measurements allow us to apply statistical methods when comparing noisy hardware traces (see [Trace Analysis](analysis.md) below).\n\nThe structure of an `HTrace` is as follows:\n\n```text\nHTrace\n └─ Array[RawHTraceSample]\n ├─ trace Main measurement (cache bitmap, timestamp, or registers)\n └─ pfc0-pfc4 Performance counter values\n```\n"
},
{
"path": "docs/internals/architecture/fuzz.md",
"content": "# Orchestration Module\n\n| | |\n| ---------------- | ---------------------------------------- |\n| Module | `rvzr/fuzzer.py` |\n| Public interface | `Fuzzer` |\n| Inputs | `Config`, `InstructionSet`, ASM Template |\n| Outputs | Violation artifact, logs |\n\nThe `Fuzzer` class is the main coordinator. It manages the core components (`CodeGenerator`, `DataGenerator`, `Model`, `Executor`, and `Analyser`) and orchestrates the fuzzing loop.\n\n## Main workflow\n\n```text\nFuzzer.start()\n └─> for each test case:\n ├─> CodeGenerator.create_test_case() → TestCaseProgram\n ├─> DataGenerator.generate() → List[InputData]\n └─> Fuzzer.fuzzing_round(program, inputs)\n ├─> Model.trace_test_case() → List[CTrace]\n ├─> Executor.trace_test_case() → List[HTrace]\n ├─> Analyser.filter_violations() → List[Violation]\n └─> if violation: multi-stage filtering pipeline\n```\n\n\n## Multi-stage filtering\n\nWhen a potential violation is found, the Fuzzer runs it through several validation stages. Each stage modifies parameters and re-checks the violation to rule out false positives:\n\n1. `fast` — Initial fast detection using minimal speculative nesting on the model side and small sample size on the executor side\n2. `nesting` — Re-collect ctraces with the model using full speculative nesting. This rules out false positives caused by incomplete speculation modeling\n3. `taint_mistake` — Re-collect ctraces for the boosted inputs to rule out boosting-based generation mistakes\n4. `priming` — Perform a so-called \"priming test\" (swap the order of violating inputs) to rule out false positives caused by inconsistent microarchitectural state across executions\n5. `noise` — Increase sample size on the executor side to increase statistical confidence and rule out noise-induced violations\n6. `arch_mismatch` — Compare the architectural output (i.e., register/memory states) of the model and executor to rule out violations caused by functional mismatches (i.e., by bugs in the model or executor)\n\nIf a violation survives all stages, Revizor saves a reproduction package (called \"violation artifact\") containing the test case, inputs, configuration, and detailed report.\n\n## Fuzzer variants\n\nThe `Fuzzer` class is abstract. There are several variants modifying the baseline logic:\n\n- `X86Fuzzer` / `ARM64Fuzzer` — Architecture-specific implementations\n- `ArchitecturalFuzzer` — Validates model correctness (i.e., performs stage 6 `arch_mismatch` for all test cases, even non-violating ones)\n- `ArchDiffFuzzer` — Completely discards the model, and instead compares two hardware executions, one with a normal test case and one with a speculation fence added after every instruction. This variant is used to detect speculation-induced architectural bugs, like zenbleed.\n"
},
{
"path": "docs/internals/architecture/isa.md",
"content": "# Instruction Set Specification\n\n| | |\n| ---------------- | ------------------ |\n| Module | `rvzr/isa_spec.py` |\n| Public interface | `InstructionSet` |\n| Inputs | `base.json` |\n| Outputs | `InstructionSet` |\n\nThis module manages the instruction set available for fuzzing. It loads ISA definitions from a JSON file (`base.json`) and applies user-configured filters to create a pool of allowed instructions.\n\nEach instruction is represented by an `InstructionSpec` containing instruction name and category, operand specifications, and instruction properties.\n\nProcessing pipeline:\n\n1. Load ISA specification from JSON\n2. Apply filters (allowlist, blocklist, categories, register restrictions)\n3. Remove duplicates\n4. Categorize instructions by type (control flow, memory access, etc.)\n\n\n"
},
{
"path": "docs/internals/architecture/logging.md",
"content": "# Logging\n\n| | |\n| ---------------- | ----------------------------- |\n| Module | `rvzr/logs.py` |\n| Public interface | `FuzzLogger`, etc. |\n| Inputs | N/A |\n| Outputs | Log messages (stdout, stderr) |\n\nRevizor uses a centralized logging system with configurable verbosity. The system uses the Borg pattern to share state across modules.\n\nAvailable logging modes:\n\n- info — General messages and progress\n- stat — Statistics\n- dbg_* — Debug modes for specific components\n\nLogging components:\n\n- Basic functions: `error()`, `warning()`, `inform()`, `dbg()`\n- Module-specific loggers: `FuzzLogger`, `GeneratorLogger`, `ISALogger`, `ExecutorLogger`, `AnalyserLogger`\n\n"
},
{
"path": "docs/internals/architecture/mini.md",
"content": "# Post-violation Analysis\n\n| | |\n| ---------------- | ------------------------------- |\n| Module | `rvzr/postprocessing/` |\n| Public interface | `Minimizer` |\n| Inputs | Violation artifact (.asm, .bin) |\n| Outputs | Minimized test case and inputs |\n\nAfter confirming a violation, users can run post-processing to simplify the test case and identify the root cause. The postprocessing module applies minimization passes that reduce complexity while preserving the violation.\n\nClass hierarchy:\n\n```text\nMinimizer\n └─ Orchestrates passes, manages files\n\nBaseMinimizationPass\n ├─ Instruction passes (modify code)\n ├─ Data passes (modify inputs)\n └─ Analysis passes (add annotations)\n```\n\nInstruction passes (operate on test case code):\n\n- `InstructionRemovalPass` — Remove instructions one at a time to find essential ones\n- `NopReplacementPass` — Replace with NOPs (preserves alignment)\n- `InstructionSimplificationPass` — Replace complex instructions with simpler ones\n- `ConstantSimplificationPass` — Simplify immediate values\n- `MaskSimplificationPass` — Simplify bitmasks\n- `LabelRemovalPass` — Remove unused labels\n- `FenceInsertionPass` — Insert fences to identify speculation boundaries\n\nData passes (operate on inputs):\n\n- `DifferentialInputMinimizerPass` — Use delta debugging to find minimal byte differences\n- `InputSequenceMinimizationPass` — Reduce number of inputs\n\nAnalysis passes (add annotations):\n\n- `AddViolationCommentsPass` — Annotate assembly with memory addresses from execution\n"
},
{
"path": "docs/internals/architecture/model.md",
"content": "# Contract Tracing\n\n| | |\n| ---------------- | ------------------------------ |\n| Module | `rvzr/model.py` |\n| Public interface | `Model` |\n| Inputs | `TestCaseProgram`, `InputData` |\n| Outputs | `CTrace` |\n\n## Model\n\nThe Model executes test cases according to a leakage contract and produces contract traces (CTraces). These represent the information expected to leak during execution, including speculative execution.\n\nRevizor supports two model backends:\n\n- **Unicorn**: This backend is based on the [Unicorn CPU emulator](https://www.unicorn-engine.org/). It implements the contract by hooking into instruction execution and memory access events. Documentation is provided in [Unicorn Backend](../model-backends/model-unicorn.md).\n- **DynamoRIO**: This backend uses [DynamoRIO](https://dynamorio.org/) for dynamic binary instrumentation. It instruments the test case to insert hooks for tracing and speculation simulation. Documentation is provided in [DynamoRIO Backend](../model-backends/model-dr.md).\n\nBoth implement the same interface defined by the abstract `Model` class.\n\n## Contract Trace Representation\n\nA `CTrace` is a sequence of typed observations representing leaked information:\n\n```text\nCTrace\n └─ List[CTraceEntry]\n ├─ mem Memory address\n ├─ pc Program counter\n ├─ val Data value\n ├─ reg Register value\n └─ ind Indirect branch target\n```\n\nCTraces use `xxhash` for fast equality checking, enabling efficient grouping into equivalence classes.\n"
},
{
"path": "docs/internals/architecture/overview.md",
"content": "# Architecture Overview & Code Structure\n\nThis document introduces Revizor's architecture and key components. It is designed to provide an overview of how the codebase is organized and how the main pieces work together.\n\n!!! info \"Prerequisites\"\n This document assumes familiarity with the concepts of side-channel attacks, speculative execution, and [Speculation Contracts and Model-based Relational Testing (MRT)](../../topics/contracts.md).\n\n## How Revizor Works\n\nRevizor detects CPU security vulnerabilities using Model-based Relational Testing (MRT). The core idea is to compare what a CPU should leak (according to a leakage model) with what it actually leaks during execution.\n\nBasic process:\n\n1. Generate random assembly programs\n2. Execute them on both a leakage model and real hardware\n3. Compare the observed hardware behavior with the model's predictions\n4. If they match, the CPU behaves as expected (discard the test)\n5. If they differ, a potential vulnerability has been found\n\nThe leakage model acts as a reference model of the expected CPU behavior. If the real CPU leaks more information than the model predicts (i.e., if it diverges from the reference), this indicates a potential security vulnerability. For details on how leakage models work, see [Speculation Contracts](../../topics/contracts.md).\n\nRevizor runs the following loop until it finds a violation or completes the configured number of test cases:\n\n\n\n## 1. Initialization\n\nThis step runs once at startup. Revizor reads the fuzzing configuration, which specifies:\n\n- Target CPU architecture\n- ISA (instruction set) specification\n- Which instructions to test\n- Which side channels to monitor\n- Other fuzzing parameters\n\nThe `cli.py` module handles command-line arguments and creates the main objects: `InstructionSet` (from `isa_spec.py`), `Config` (from `config.py`), and `Fuzzer` (from `fuzzer.py`).\n\n## 2. Code Generation\n\nEach fuzzing round starts by generating a random test program. This is an assembly program with semi-random control flow, built from a pool of allowed instructions.\n\nThe code generator can be configured to control the shape of the control flow graph, which instructions to include, and how often each instruction appears. It also (optionally) instruments the program to prevent faults like division by zero.\n\nThe `Fuzzer` calls `CodeGenerator.create_test_case()` (in `code_generator.py`), which returns a `TestCaseProgram` object representing the generated assembly program.\n\n## 3. Data Generation\n\nNext, Revizor generates random inputs for the test program. Each input contains initial values for registers and memory. These values are pseudo-random but use fixed seeds for reproducibility.\n\nThe `DataGenerator` class (in `data_generator.py`) creates these inputs and returns them as `InputData` objects. See [binary formats](../../ref/binary-formats.md#revizor-data-binary-format-rdbf) for the structure of input data.\n\n## 3.5 Test Case Filtering (Optional)\n\nSome test cases are unlikely to reveal vulnerabilities, so Revizor can filter them out early to save time. This is optional and disabled by default.\n\nTwo filters are available:\n\n- Speculation filter: Uses performance counters to check if the test case triggers branch mispredictions. Without mispredictions, the test cannot expose speculative leaks.\n- Observation filter: Compares the original test case with a \"fenced\" version (with serialization instructions added). If both produce identical traces, speculation left no observable effects.\n\nThese filters are implemented in architecture-specific fuzzer classes (like `X86Fuzzer` in `rvzr/arch/x86/fuzzer.py`).\n\n## 4. Model Execution\n\nThe model executes the test program with each generated input and produces contract traces (CTraces). These traces represent what the model predicts should leak during execution.\n\nThe `Model` class (in `model.py`) provides two key methods:\n\n- `load_test_case()`: Loads the program into the model\n- `trace_test_case()`: Executes the program with each input and returns CTraces\n\nRevizor supports multiple model backends: [Unicorn](../model-backends/model-unicorn.md) (CPU emulator) and [DynamoRIO](../model-backends/model-dr.md) (dynamic instrumentation). Both implement the same interface.\n\n## 5. Hardware Execution\n\nThe executor runs the test program on the target hardware with each input and collects hardware traces (HTraces). A hardware trace is a set of observable microarchitectural effects (like cache state or timing) caused by the test case execution. Traces are typically collected using side-channel techniques (e.g., Prime+Probe, Flush+Reload) or by reading performance counters.\n\nTo ensure that the measurements reflect the test case execution (rather than noise), the executor creates a controlled measurement environment by disabling interrupts, flushing caches, and repeating executions multiple times.\n\nThe `Executor` class (in `executor.py`) works through a kernel module (`executor_km/`) that performs measurements in kernel space. It provides the same interface as the model: `load_test_case()` and `trace_test_case()`.\n\n## 6. Trace Analysis\n\nThe analyzer compares contract traces (what should leak) with hardware traces (what actually leaked) to detect violations. Instead of directly comparing traces, it uses an equivalence class approach.\n\nHow it works:\n\n1. Group by contract: Inputs with identical CTraces form a ContractEqClass. According to the model, these inputs should be indistinguishable.\n2. Group by hardware: Within each ContractEqClass, inputs with similar HTraces form HardwareEqClasses. These inputs are actually indistinguishable on real hardware.\n3. Detect violations: If a ContractEqClass splits into multiple HardwareEqClasses, a violation has occurred. The model says the inputs should look the same, but hardware reveals differences between them.\n\nThis approach focuses on information leakage rather than exact trace values, and it essentially implements a non-interference check (see [Theoretical Foundations](../../topics/contracts.md)).\n\nThe `Analyser` class (in `analyser.py`) implements this logic in its `filter_violations()` method.\n\n## 7. Post-violation Analysis\n\nWhen Revizor detects a potential violation, it runs additional tests to filter out false positives. These tests modify execution parameters and verify the violation still occurs. See [post-violation tests](mini.md) for details.\n\nIf the violation survives all filters, Revizor reports it to the user and saves reproduction artifacts. The user can then use [minimization tools](../../howto/minimize.md) to simplify the test case and identify the root cause.\n\nThe post-violation logic is implemented in `Fuzzer.fuzzing_round()`, and the `FuzzLogger` class handles reporting.\n"
},
{
"path": "docs/internals/code-structure.md",
"content": "# Code Structure\n\nThe Revizor codebase is organized into the following main directories:\n\n```text\nrvzr/ Main source code directory containing core fuzzing logic\n ├── *.py Core modules that implement main fuzzing components\n ├── tc_components/ Test case representation objects (code and data)\n ├── model_unicorn/ Unicorn-based leakage model\n ├── model_dynamorio/ DynamoRIO-based leakage model\n ├── executor_km/ Kernel module that implements the hardware executor\n ├── postprocessing/ Minimization utilities for contract counterexamples\n └── arch/ Architecture-specific implementations (x86/ and arm64/)\ntests/ Unit and integration tests\ndocs/ Documentation files\n```\n\nThe main entry point is `rvzr/cli.py`, which parses command-line arguments and initializes the `Fuzzer` object.\n\n"
},
{
"path": "docs/internals/contributing/code-style.md",
"content": "# Code Style\n\nPlease follow these coding standards when writing code for inclusion in Revizor.\n\n## Python\n\n* Unless otherwise specified, follow PEP 8. But remember that PEP 8 is only a guide, so respect the style of the surrounding code as a primary goal.\n* An exception to PEP 8 is our rules on line lengths. Don’t limit lines of code to 79 characters if it means the code looks significantly uglier or is harder to read. We allow up to 100 characters.\n* All files should be formatted using the `flake8` auto-formatter. Use all default settings except for the line width (`--max-line-length 100`)\n* The Python and C files use 4 spaces for indentation, and YAML uses 2 spaces.\n* The project repository includes an .editorconfig file. We recommend using a text editor with EditorConfig support to avoid indentation and whitespace issues.\n* Use underscores, not camelCase, for variable, function and method names (i.e. poll.get_unique_voters(), not poll.getUniqueVoters()).\n* Use InitialCaps for class names (or for factory functions that return classes).\n* In docstrings, follow PEP 257.\n\n## C\n\n* All files should be formatted using the `clang-format`. The settings are included into the `.clang-format` files in the directories with C files. Just run the formatter with: `clang-format -i *.c`\n\n## Misc\n\n* Remove import statements that are no longer used when you change code. flake8 will identify these imports for you. If an unused import needs to remain for backwards-compatibility, mark the end of with `# NOQA` to silence the flake8 warning.\n* Systematically remove all trailing whitespaces from your code as those add unnecessary bytes, add visual clutter to the patches and can also occasionally cause unnecessary merge conflicts. Some IDE’s can be configured to automatically remove them and most VCS tools can be set to highlight them in diff outputs.\n"
},
{
"path": "docs/internals/contributing/general.md",
"content": "# General Development Guidelines\n\n## Testing\n\nTo run automated tests you will need to install a few more dependencies:\n\n* [Bash Automated Testing System](https://bats-core.readthedocs.io/en/latest/index.html)\n* [mypy](https://mypy.readthedocs.io/en/latest/getting_started.html#installing-and-running-mypy)\n* [flake8](https://flake8.pycqa.org/en/latest/index.html)\n\nWith the dependencies installed, you can run the tests with:\n\n```bash\n./tests/runtests.sh\n```\n\nNote that some of the acceptance tests are microarchitecture-dependent.\nThese tests are labeled \"Detection\" (e.g., `\"Detection [spectre-type] Spectre V1; load variant\"`), and they may fail if the CPU under test does not have a given vulnerability.\nGenerally, if a few of these tests fail, it is not a problem, but if all of them (or a significant portion) fail, it indicates an issue with the fuzzer.\n\n## Submitting Patches\n\nTo submit a patch, use the following procedure:\n\n* Fork Revizor on github:\n\n [https://docs.github.com/en/github/getting-started-with-github/fork-a-repo](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo)\n\n* Create a topic branch:\n\n```bash\ngit checkout -b my_branch\n```\n\n* Make sure all tests pass (see [Testing](#testing))\n* Make sure your code follows the guidelines in [Code Style](code-style.md)\n* Push to your branch\n\n```bash\ngit push origin my_branch\n```\n\n* Initiate a pull request on github:\n\n [https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request)\n\n* Wait for the PR to get reviewed and merged\n"
},
{
"path": "docs/internals/contributing/git.md",
"content": "# Git Workflow Guidelines\n\n## Git Messages\n\nWe practice the following conventions for commit messages:\n\n```\n\n Welcome to the Revizor documentation! Whether you're a new user looking to get started or a developer interested in contributing, you'll find all the information you need here.\n
\n\n [Start Here](intro/start-here.md){ .md-button .md-button--primary }\n [Learn Revizor](intro/01-overview.md){ .md-button }\n [Ask a Question](howto/ask-a-question.md){ .md-button }\n [Cite Revizor](ref/papers.md){ .md-button }\n\n\n- __:fontawesome-solid-code: Source Code__\n\n ---\n\n\n The Revizor project lives on GitHub. Explore the source code, report issues, and contribute to the project.\n \n
\n\n\n [GitHub](https://github.com/microsoft/side-channel-fuzzer){ .md-button }\n [Contributing](internals/contributing/overview.md){ .md-button }\n [Bug Reports](https://github.com/microsoft/side-channel-fuzzer/issues){ .md-button }\n [Explore Docs](structure.md){ .md-button }\n\n\n- __:fontawesome-solid-comments: Join the Community__\n\n ---\n\n\n Join the Revizor community to get help, discuss ideas, suggest features, and share your experiences.\n \n
\n\n [Zulip Community](https://rvzr.zulipchat.com/){ .md-button }\n [GitHub Discussions](https://github.com/microsoft/side-channel-fuzzer/discussions){ .md-button }\n\npublic inputs `Pub` and all pairs of secret inputs `Sec1`, `Sec2` it holds that
`PublicOut(P, Sec1, Pub) = PublicOut(P, Sec2, Pub)`.\n\nHere are some examples to illustrate this principle:\n\n=== \"Example 2: Interfering program\"\n\n: Suppose our program simply copies a secret to output:\n\n ```c\n void copy(int* sec, int* output) {\n *output = *sec;\n }\n ```\n\n: Running it with two different secrets clearly yields different public outputs (e.g., `output` becomes 5 in one run and 7 in another). An attacker would distinguish these runs, so the program is **not** noninterferent—it blatantly leaks information.\n\n---\n\n=== \"Example 3: Noninterfering program\"\n\n: A trivial example of a noninterferent program is one that produces no output dependent on the secret. For instance:\n\n ```c\n void assign_zero(int* sec, int* output) {\n *output = 0;\n }\n ```\n\n: This program ignores secret `sec` entirely and always sets the public output `output` to 0. No matter what the secret input is, the public output is constant (0), so an attacker gains no information about `sec`. Indeed, any two runs are indistinguishable (both runs output 0). This satisfies noninterference (albeit by doing nothing useful with the secret).\n\n---\n\n=== \"Example 4: Allowed benign dependency\"\n\n: It is possible for a program to use secret data internally yet still be noninterferent as long as the final public outputs don’t reveal those secrets. For instance:\n\n ```c\n void mask_secret(int* sec, int* output) {\n int temp = *sec;\n temp = temp * 0; // multiply secret by 0\n *output = temp;\n }\n ```\n\n: Here the program *did* read the secret (`sec`) and even manipulated it, but it “washed out” the secret by multiplying by 0. The value assigned to `output` is always 0. From an external view, this is just like the previous example—no dependence of `output` on `sec`. Noninterference is concerned only with *what can be observed by the attacker*, not with whether the program internally used the secret. As long as any use of the secret eventually has no effect on outputs, the policy holds.\n\n: Naturally, this example is not useful either, as it does nothing with the secret. In practice, however, there are techniques to ensure noninterference while still making use of secret data for useful computations. We won't go into these techniques here as they are beyond the scope of this primer.\n\n---\n\nOne important insight is that noninterference is relative to a given specification of what is “observable.” If you consider only the functional outputs as observable, a program might be noninterferent in that model. But if in reality the attacker can observe more (e.g., the execution time of a program), then the program that was secure in theory might be insecure in practice. This leads us to examine how *side channels* break the assumptions of basic noninterference.\n\n## Beyond Direct Outputs: Side Channels\n\nThe original works on information-flow properties focused on direct outputs of a program (e.g., writing to a file or a network socket). However, in practice, attackers can extract information from more than just the “official” outputs of a program. For example, the attacker might observe how long a computation takes or measure the power consumption of a device. These additional sources of information are called **side channels**. Side channels are unintended channels through which secret data can be inferred by observing the system’s behavior, even if the direct outputs are secure.\n\nThese side channels can reveal information about the secret inputs, and so we must include them in the definition of noninterference. Similarly to how we defined `PublicOut(Sec, Pub)` as the observable output, we can define `Trace` as the observable side-channel information for a given program `P`.\n\n```\ntrace = Trace(P, Sec, Pub)\n```\n\nFor example, a trace might be the execution time of the program or its cache access pattern.\n\nNoninterference then requires that the traces of two runs with different secrets - `(Sec1, Pub)` versus `(Sec2, Pub)` - are indistinguishable to an attacker. This is a stronger requirement than just looking at the functional outputs.\n\n=== \"Definition 2: Side-Channel Noninterference\"\n: Given a side channel that produces a trace `Trace`, a program `P` is noninterferent with respect to this side channel if, for all public inputs `Pub` and all pairs of secret inputs `Sec1`, `Sec2` it holds that
`Trace(P, Sec1, Pub) = Trace(P, Sec2, Pub)`.\n\nHere are some examples of side channels and how they can violate noninterference:\n\n=== \"Example 5A: Timing side channel\"\n\n: Consider a program that reads a compares a password with a user’s input:\n\n ```c\n bool check_password(const char *attempt, const char *pswd) {\n for (int i = 0; i < length(pswd); i++) {\n if (attempt[i] != pswd[i]) {\n return false; // mismatch found, return early\n }\n }\n return true; // all characters matched\n }\n ```\n\n: If the attacker can measure how long the function takes to reject a guess, they can infer the password one character at a time. This leakage surfaces as a violation of the noninterference property with respect to timing observations.\n\n: A counterexample to Definition 2 could be as follows: Let's say we use the same input on two different secrets:\n\n: - `input1={attempt=\"aaa\", pswd=\"abc\"}`\n: - `input2={attempt=\"aaa\", pswd=\"aab\"}`\n\n: The traces of these inputs will be:\n\n: - `trace1 = Trace(check_password, input1) = 1`\n: - `trace2 = Trace(check_password, input2) = 2`\n\n: These inputs constitute a violation of Definition 2, as `trace1 != trace2` even though the two inputs have the same public values.\n\n---\n\n=== \"Example 5B: Timing side channel - Password length\"\n\n: Noninterference is able to model different kinds of secret-dependent leaks. Let's take for example a patched version of the previous program:\n\n ```c\n bool check_password(const char *attempt, const char *pswd) {\n int len = min(length(attempt), length(pswd));\n bool same = true;\n for (int i = 0; i < len; i++) {\n same = same && (attempt[i] == pswd[i]); // all the loop is executed\n }\n return same;\n }\n ```\n\n: In this version there is no early-exit condition, yet the attacker is still able to infer the _length_ of the password through a side-channel. This is captured by the following counterexample:\n\n: - `input1={attempt=\"aaaaaa\", pswd=\"b\"}`, `trace1 = 1`\n: - `input2={attempt=\"aaaaaa\", pswd=\"bbb\"}`, `trace2 = 3`\n\n: Which shows that the program still violates Definition 2.\n\n---\n\n=== \"Example 6: Cache side channel\"\n\n: Consider a program that uses a secret value to index into an array, as in the following code:\n\n ```c\n int multiply(const char *array, int pub, int sec) {\n char x = array[sec];\n return x * pub;\n }\n ```\n\n: A co-located attacker could observe the cache access pattern of the program by using Prime+Probe or Flush+Reload attack. Such traces can reveal the addresses accessed by the program and thus leak the secret value. This leakage would violate the noninterference property with respect to cache observations.\n\n: A violation could be surfaced by two inputs:\n\n: - `input1={array=0x10000, pub=1, sec=0x40}`\n: - `input2={array=0x10000, pub=1, sec=0x80}`\n\n: Let's assume that the cache line size is 64 bytes, and the cache is direct-mapped, meaning that the cache line ID is based on the memory access address `addr` as `line_id = (addr % 0x1000) // 0x40`. Since the array access in the first line of `multiply` will access two different addresses for the two inputs, they will also produce two different traces:\n\n: - `trace1 = Trace(multiply, input1) = ((0x10000 + 0x40) % 0x1000) // 0x40 = 1`\n: - `trace2 = Trace(multiply, input2) = ((0x10000 + 0x80) % 0x1000) // 0x40 = 2`\n\n: Since we have two inputs that match on the secret value `sec` but differ on the cache trace, this constitutes a violation of Definition 2.\n\n## Challenges of Side-Channel Noninterference\n\nDespite its completeness, the above formalization of side-channel noninterference is too simplistic to faithfully capture the side effects of program execution on modern, highly optimized hardware, especially CPUs. There are two key challenges:\n\n- *Challenge 1 - Noisy and Non-Deterministic Traces*: The traces observed by the attacker over a side channel are typically noisy, non-deterministic, and depend on the microarchitectural state of the CPU. For example, cache access patterns can be influenced by other programs running on the machine, the operating system and its interrupts, and can depend on microarchitectural buffers like store buffers or branch history tables. This means that the `Trace` function is not a simple deterministic function of the program inputs, but a complex function of many factors, some of which affect the result concurrently and in a non-deterministic fashion.\n\n- *Challenge 2 - Unknown Side Channels*: Modern CPUs have a plethora of side channels, including cache timing, branch prediction, and many others. To ensure complete confidentiality, we need to check that the program does not leak information over *any* of them. This is a challenging task, as we do not know the full set of possible side channels when it comes to commercial hardware with proprietary microarchitectures. For example, a CPU might have an obscure microarchitectural optimization that vastly expands possibilities for information leaks, as was the case with Spectre and Meltdown vulnerabilities. Not including this optimization will undermine the noninterference analysis. Therefore, to test for noninterference comprehensively, we need a way to discover and reason about all possible side channels that could leak information.\n\nThe next two sections discuss how speculation contracts address these challenges.\n\n## Speculation Contracts: Dealing with the Complexity of Modern Hardware\n\nAs a solution to the first challenge, Guarnieri et al. (2021) introduced the concept of **speculation contracts**. A speculation contract is a simplified and deterministic model of the hardware, designed to capture the information that a given program *could* leak over side channels when executed with the given inputs. The key term here is \"could\"—the contract is not meant to exactly predict the side-channel traces, but instead, it errs on the side of caution, overestimating the possible leaks to achieve deterministic and noise-free traces.\n\nA speculation contract works by defining two key aspects for every instruction in the CPU's ISA:\n\n1. [**Observation Clause**](../glossary.md#observation-clause): For each instruction that may have\nan observable side effect, the contract declares an observation clause. It describes the data\nexposed by the instruction.\n\n2. [**Execution Clause**](../glossary.md#execution-clause): For each instruction whose semantics\nmay be affected by hardware optimizations (e.g., speculative execution), the contract declares an\nexecution clause. It describes the effect of such optimizations, but without specifying the exact\nmechanism of the optimization.\n\nAt a high level, a contract implements a function `ContractTrace` that maps a program `P` and its\ninputs `Sec, Pub` to a [contract trace](../glossary.md#contract-trace-ctrace) `ctrace`. It is\nessentially a conservative approximation of the `Trace` function.\n\n```\nctrace = ContractTrace(P, Sec, Pub)\n```\n\nThe contract trace is a sequence of all data that is exposed when a program is executed according\nto a contract. It captures the side-channel observations that *could be visible* if the CPU\nfollowed the speculation contract's rules for a given program execution.\n\nAccordingly, the noninterference property is redefined in terms of the contract trace:\n\n=== \"Definition 3: Contract Noninterference\"\n\n: Given a contract that produces a contract trace `ContractTrace`, a program `P` is noninterferent with respect to this contract if,
for all public inputs `Pub` and all secret inputs `Sec1`, `Sec2`, it holds that
`ContractTrace(P, Sec1, Pub) = ContractTrace(P, Sec2, Pub)`.\n\nThe following examples illustrate how a contract can be used to model side-channel leaks on a CPU.\n\n=== \"Example 7: Memory Observation Contract, MEM-SEQ\"\n\n: Let's imagine a CPU with a shared data cache and no other optimizations (i.e., no speculation). A co-located attacker can recover the addresses of loads/stores by observing which of the cache sets changed their state via a cache timing side-channel attack (e.g., Prime+Probe). We can encode these expectations in an observation clause for loads and stores by specifying that they expose their address. Since the CPU does not speculate, the execution clause for all instructions is empty. We call this contract MEM-SEQ (memory leakage with sequential execution), and it can be summarized as a table:\n\n | | Observation Clause | Execution Clause |\n | ----- | ------------------ | ---------------- |\n | Load | Expose Address | - |\n | Store | Expose Address | - |\n | Other | - | - |\n\n: Note that MEM-SEQ intentionally overestimates the leaks by assuming that the attacker observes complete addresses loads/stores (in contrast to a subset of bits that are actually leaked in practice) and that *all* loads/stores are observable (in reality, they might be masked by noise or other factors). This overestimation is intentional to ensure that the contract is conservative and captures all possible corner cases.\n\n: Let's now consider how we can produce a contract trace using MEM-SEQ. We will use a slightly modified version of the `multiply` function from Example 6:\n\n ```c\n int multiply(const char *array, int pub, int sec) {\n char x = array[sec]; // MEM-SEQ exposes: &array[sec]\n char y = array[pub]; // MEM-SEQ exposes: &array[pub]\n return x * y;\n }\n ```\n\n: The inputs are:\n\n: - `input1 = {array=0x10000, pub=1, sec=2}`\n: - `input2 = {array=0x10000, pub=1, sec=3}`\n\n: The model collects a trace by executing the program line-by-line according to the rules in the table above (in practice, this is usually done using a modified CPU emulator). The first line has a load from memory, so the model records the address `&array[sec]` as exposed. The second line has another load, so the model records the address `&array[pub]` as exposed. The contract traces for this program would be:\n\n: - `ctrace1 = ContractTrace(multiply, input1) = [0x10002, 0x10001]`\n: - `ctrace2 = ContractTrace(multiply, input2) = [0x10003, 0x10001]`\n\n: Finally, this model can be used to check for noninterference by comparing contract traces according to Definition 3. In this case, we have two inputs with matching public values and different secrets, and they produced different contract traces, `ctrace1 != ctrace2`. This constitutes a violation and means that the `multiply` function is not noninterferent with respect to MEM-SEQ.\n\n---\n\n=== \"Example 8: Branch Prediction Contract, MEM-COND\"\n\n: Now let's consider a more complex scenario, with a CPU that implements branch prediction—a common form of speculative execution. In this case, the CPU may incorrectly predict branch targets and execute instructions that are not part of the correct control flow. We can model this behavior in a contract by introducing an execution clause for conditional jumps that specifies the mispredicted target. To make the example useful, we will assume that the CPU also has a data cache, so the observation clause for loads and stores remains the same as in MEM-SEQ. We call this contract MEM-COND (memory leakage with conditional branch misprediction).\n\n | | Observation Clause | Execution Clause |\n |------------|--------------------|-------------------|\n | Load | Expose Address | - |\n | Store | Expose Address | - |\n | Cond. Jump | - | Mispredict Target |\n | Other | - | - |\n\n: As a target program we will use the following function:\n\n ```c\n int conditional_multiply(char *array, int pub, int sec) {\n int z = array[pub]; // MEM-COND exposes: &array[pub]\n if (z < 10) { // MEM-COND mispredicts (assume z = 10)\n z *= array[sec]; // MEM-COND exposes: &array[sec]\n }\n return z;\n }\n ```\n\n: and a pair of inputs with the same public value but different secrets:\n\n: - `input1 = {array=0x10000, pub=1, secret=2}`\n: - `input2 = {array=0x10000, pub=1, secret=3}`\n\n: The first line of `conditional_multiply` has a load, so it exposes its address, `&array[pub]`. For the sake of this example, let's assume this load returns `10`, so the next branch is not supposed to be taken. However, according to MEM-COND, branches take the wrong target, so the model executes the third line anyway. This line is a load, so it exposes the address `&array[sec]`. After this, the program terminates, and the resulting traces are:\n\n: - `ctrace1 = ContractTrace(conditional_multiply, input1) = [0x10002, 0x10001]`\n: - `ctrace2 = ContractTrace(conditional_multiply, input2) = [0x10003, 0x10001]`\n\n: Again, the traces are different, so the program violates noninterference with respect to MEM-COND.\n: Notably, however, these two inputs would *not* violate noninterference with respect to MEM-SEQ, as the branch at line 2 would not be mispredicted, and the traces would be identical:\n\n: `ctrace_mem_seq1 = ctrace_mem_seq2 = [0x10001]`\n\n## Building and Testing Speculation Contracts\n\nSpeculation contracts are typically built by hand, with the initial versions based on public knowledge of the CPU's microarchitecture and its side-channel vulnerabilities. However, in the case of commercial CPUs, the exact details of the microarchitecture are often proprietary and not publicly disclosed. In these cases, the contract could—and often will—be incomplete. This is where the testing of speculation contracts becomes crucial: the initial \"draft\" of a contract is tested against the real hardware to ensure that it captures all side-channel leaks that the CPU exhibits. If the contract misses something, it is refined based on the results of the testing, and the process is repeated until the contract is deemed safe to use.\n\nBut how do we test a speculation contract? A naive approach might be to directly compare the traces produced by the model with the traces collected from the real CPU for the same program and inputs. However, this approach is generally not feasible because the contract traces intentionally overestimate the hardware traces, so mismatches are expected. Moreover, the model might expose information differently than the real hardware (e.g., the model might expose load/store addresses, while the hardware exposes cache set indexes), meaning direct comparison is often impossible.\n\nInstead, a more precise approach is to compare *the information contained in the traces*. The idea is to check that the information exposed by the model is a strict superset of the information exposed by the real hardware. This is done by verifying that all inputs producing identical contract traces for a given program also produce identical hardware traces. If this property holds for all possible programs and inputs (ignore the complexity question for now), then any program that would be noninterferent with respect to the real hardware is guaranteed to be noninterferent with respect to the speculation contract. At this point, the model is safe to use as a proxy for real hardware when analyzing side-channel leaks.\n\nTo formalize this idea, let's introduce a new function `HardwareTrace` to denote the\n[hardware trace](../glossary.md#hardware-trace-htrace) collected from the real hardware, and it\nwill take an extra argument `Ctx` to capture the fact that real-world hardware traces depend on\nthe microarchitectural state (e.g., on the state of branch predictors or caches).\n\n=== \"Definition 4: [Contract Compliance](../glossary.md#contract-compliance)\"\n\n: A CPU complies with a speculation contract if, for all programs `P`, all input pairs\n`(Sec1, Pub), (Sec2, Pub)`, and all initial microarchitectural states `Ctx`, if\n`ContractTrace(P, Sec1, Pub) = ContractTrace(P, Sec2, Pub)`, then\n`HardwareTrace(P, Sec1, Pub, Ctx) = HardwareTrace(P, Sec2, Pub, Ctx)`.\n\n\nand conversely\n\n=== \"Definition 5: [Contract Violation](../glossary.md#violation)\"\n\n: A CPU violates a speculation contract if there exists a program `P`, a microarchitectural\nstate `Ctx`, and two inputs `(Sec1, Pub), (Sec2, Pub)` such that\n`ContractTrace(P, Sec1, Pub) = ContractTrace(P, Sec2, Pub)` and
\n`HardwareTrace(P, Sec1, Pub, Ctx) != HardwareTrace(P, Sec2, Pub, Ctx)`.\n\nWe call the tuple `(P, Ctx, Sec1, Sec2)` a\n[**contract counterexample**](../glossary.md#violation-artifact-aka-contract-counterexample). The\ncounterexample demonstrates that an adversary can learn more information from hardware traces than\nwhat the contract specifies. A counterexample indicates a potential microarchitectural leakage\nthat was not accounted for by the contract. The goal of Revizor is to find such counterexamples.\n\n## [Model-Based Relational Testing](../glossary.md#model-based-relational-testing-mrt) and Revizor\n\nRevizor applies the principles above, and provides a framework for building executable speculation\ncontracts together with a mechanism to test real hardware (currently only CPUs) against these\ncontracts by searching for contract counterexamples, as in Definition 5. However, there are\ncertain issues that appear when the theory from the previous section is applied in practice, which\nwe had to address in Revizor.\n\nThe first issue is the search space: testing all possible programs and inputs is literally\nimpossible. We mitigate this issue by relying on a sampling-based approach, similar to fuzzing,\nwhere we approximate the complete search space via random sampling. Specifically, Revizor generates\nsmall (50-100 instructions long) programs, creates random inputs for them, collects both the\ncontract and hardware traces for these inputs, and checks whether any of the traces constitute a\ncontract counterexample. This process is called\n[*Model-based Relational Testing*](../glossary.md#model-based-relational-testing-mrt), and it is\ndetailed further in the [Architecture Overview](../internals/architecture/overview.md).\n\nThis approach works well in practice because any given hardware optimization can typically be triggered by many different programs, and we need to find only one instance to detect a violation. Evidence of this is the [list of trophies](https://microsoft.github.io/side-channel-fuzzer/) that Revizor has already amassed.\n\nThe second issue we encountered is nondeterminism. As mentioned earlier, hardware traces can be non-deterministic due to various factors like interrupts or other programs running on the machine. To handle this, we use statistical methods: Revizor collects hardware traces for each program-input pair multiple times and then compares their distributions. If the distributions of the traces are statistically similar, Revizor considers the traces to be equivalent. This approach helps us account for noise in the hardware traces while still making reliable decisions about contract compliance.\n\nFor more details, see [Architecture Overview](../internals/architecture/overview.md).\n\n## Conclusion\n\nIn this primer, we have introduced the concepts of noninterference, side channels, and speculation contracts, which all underlie the design of Revizor:\n\n- The hardware fuzzer in Revizor uses speculation contracts and the concepts of noninterference (1) to detect unexpected side channels and dangerous microarchitectural optimizations in commercial CPUs, and (2) to aid in building sound leakage models for those CPUs.\n- The software fuzzer in Revizor (*NOTE: currently under construction*) uses the leakage models produced by the hardware fuzzer, and applies the principles of noninterference testing to detect side-channel vulnerabilities in real-world software.\n\nWith these two components, we aim to provide a comprehensive tool for discovering and mitigating side-channel vulnerabilities software that can handle even the most obscure and complex microarchitectural optimizations in modern hardware.\n\n---\n\n## Sources and Further Reading\n\n- A. Sabelfeld and A. C. Myers. *Language-Based Information-Flow Security*. IEEE Journal on Selected Areas in Communications, 21(1), 2003. (Survey of information-flow security, implicit/explicit flows, covert channels, etc.)\n- J. A. Goguen and J. Meseguer. *Security Policies and Security Models*. IEEE Symposium on Security and Privacy, 1982. (Origin of noninterference as a security policy formalism.)\n- J. B. Almeida et al. *Verifying Constant-Time Implementations*. USENIX Security Symposium, 2016. (Constant-time programming principles and the ct-verif tool for automated verification.)\n- M. Guarnieri, B. Köpf, J. Reineke, P. Vila. *Hardware-Software Contracts for Secure Speculation*. IEEE Symposium on Security and Privacy, 2021. (Original paper on speculation contracts.)\n- O. Oleksenko, C. Fetzer, B. Köpf, M. Silberstein. *Revizor: Testing Black-box CPUs against Speculation Contracts*. ACM International Conference on Architectural Support for Programming Languages and Operating Systems (ASPLOS), 2022. (Paper describing Model-based Relational Testing and Revizor.)\n\n" }, { "path": "docs/intro/04-tutorials.md", "content": "# Starting with Tutorials\n\nLet's learn by example.\n\nThis is a starting point for a tutorial series that will teach you how to use Revizor for testing CPUs, from the most basic cases, to detection of Spectre and Meltdown, to building custom campaigns for detecting new vulnerabilities, and up to building custom extensions for Revizor for the most advanced cases.\n\n!!! note \"Prerequisites\"\n Before proceeding with this tutorial, ensure that you have completed the installation steps outlined in the [Installation Guide](02-install.md).\n\n!!! question \"Need Help?\"\n - **Questions about the tutorial?** Check the [FAQ](../faq/general.md) or open a [GitHub discussion](https://github.com/microsoft/side-channel-fuzzer/discussions)\n - **Found a bug?** Report it in [GitHub issues](https://github.com/microsoft/side-channel-fuzzer/issues)\n\n### Let's get started!\n\nReady to dive in?\n\n* [Tutorial 1](./tutorials/01-first-fuzz.md) - run your first fuzzing campaign with Revizor\n* [Tutorial 2](./tutorials/02-first-vuln.md) - find your first microarchitectural vulnerability with Revizor\n* [Tutorial 3](./tutorials/03-faults.md) - learn how to test faults and exceptions with Revizor\n* [Tutorial 4](./tutorials/04-isolation.md) - explore how to test domain isolation boundaries\n* [Tutorial 5](./tutorials/05-extending.md) - extend Revizor with custom features\n" }, { "path": "docs/intro/start-here.md", "content": "# Getting started\n\nNew to Revizor? Or to side-channel testing in general? You came to the right\nplace: read this material to quickly get up and running.\n\n## Introductory Materials\n\n* [Revizor at a Glance](01-overview.md): Understand what Revizor is, what problems it solves, and see a quick example of violation detection.\n* [Installation Guide](02-install.md): Get Revizor installed on your system and verify your setup.\n* [Core Concepts](03-primer.md): Learn about contracts, traces, speculation, and other fundamental concepts needed to use Revizor effectively.\n* [Tutorial Series](04-tutorials.md): Follow a series of hands-on tutorials that walk you through running your first tests, detecting violations, and rump up all the way to root-cause analysis and design of custom campaigns.\n* [Glossary](../glossary.md): A quick reference for key terms used throughout the documentation.\n\n## Research\n\nInterested in the academic research behind Revizor? Check out the papers listed in the [Research Papers](../ref/papers.md) section.\n\n## Need Help?\n\n[Ask a Question](../howto/ask-a-question.md) about Revizor if you need assistance or have any questions.\n" }, { "path": "docs/intro/tutorials/01-first-fuzz.md", "content": "# Tutorial 1: Your First Fuzz\n\nThis is the first part of the tutorial on the basic usage of Revizor.\n\n### Overview\n\nIn this first tutorial, we'll start with a baseline experiment to verify your Revizor installation and familiarize yourself with the basic workflow. This tutorial walks you through a simple fuzzing campaign that should find no violations.\n\nThe goal of this first campaign is verification, not vulnerability detection. We'll deliberately choose an instruction set that should not trigger speculation on Intel or AMD CPUs—specifically, simple arithmetic operations without any branches or memory speculation sources. Since there are no conditional branches to mispredict and no page faults to speculate around, we expect the CPU to execute sequentially without any speculative side effects.\n\nThis baseline is useful for two reasons. First, it confirms your installation is working correctly. If the fuzzer crashes or behaves unexpectedly, you'll know there's a setup issue rather than discovering problems later during more complex campaigns. Second, it establishes what \"no violations\" looks like, so you can recognize the difference when you do find a vulnerability in the next tutorial.\n\n### Create your first configuration file\n\nRevizor's behavior is controlled by a YAML configuration file that specifies which instructions to test and what contract to check against. Create a file named `config.yaml` with the following content:\n\n```yaml\n# tested instructions\ninstruction_categories:\n - BASE-BINARY\n\n# prevent branch generation\nmax_bb_per_function: 1\nmin_bb_per_function: 1\n\n# contract\ncontract_observation_clause: loads+stores+pc\ncontract_execution_clause:\n - no_speculation\n```\n\nLet's understand each section. The `instruction_categories` field tells Revizor which instructions to include in generated test cases. We're using `BASE-BINARY`, which includes only arithmetic and logical operations like `add`, `sub`, `and`, `xor`, and `mov`. These operations are data-processing instructions that don't involve control flow or special memory access patterns.\n\nThe `max_bb_per_function` and `min_bb_per_function` settings both set to 1 ensure that Revizor generates programs with exactly one basic block—meaning no branches at all. This simplifies our test cases to pure arithmetic sequences, eliminating any possibility of branch misprediction.\n\nThe contract configuration section is set to use the simplest contract, CT-SEQ. This contract assumes nothing about the target CPU except the presence of CPU caches, making it a zero-knowledge baseline for detecting unknown vulnerabilities. With CT-SEQ, Revizor reports any information leaks beyond the most trivial non-speculative cache accesses.\n\nFor a complete reference of all configuration options, see the [Configuration Reference](../../ref/config.md).\n\n\n### Run the Campaign\n\nLet's run the fuzzer with your baseline configuration:\n\n```bash\nrvzr fuzz -s base.json -c config.yaml -n 100 -i 50 -w .\n```\n\nThis command tells Revizor to execute 100 test cases (`-n 100`) with 50 inputs per test case (`-i 50`), using the ISA specification from `base.json` and your configuration file. The `-w .` flag specifies the working directory for saving any violations.\n\nYou'll see output similar to this:\n\n```\nINFO: [fuzzer] Starting at 14:32:18\n100 (100%)| Stats: Cls:50/50,In:100,R:5,SF:0,OF:0,Fst:0,CN:0,CT:0,P1:0,CS:0,P2:0,V:0\n================================ No Violations detected ===========================\n```\n\nThe campaign should complete in under a minute with no violations detected. This is exactly what we expect—our simple arithmetic instructions don't trigger speculation, so the hardware behaves according to the strict sequential contract.\n\n### Interpret the statistics\n\nLet's examine the statistics line to understand what Revizor is reporting:\n\n```\n100 (100%)| Stats: Cls:50/50,In:100,R:5,SF:0,OF:0,Fst:0,CN:0,CT:0,P1:0,CS:0,P2:0,V:0\n```\n\n#### `100 (100%)`\n\nThis part shows we completed all 100 test cases. This number was continuously updated while the fuzzer was running.\n\n#### `Cls:50/50`\n\nThese numbers indicate the number of [equivalence classes](../../glossary.md#contract-equivalence-class) formed by the inputs. The first number is the effective classes (> 1 input per class) and the second is the total number of classes.\n\nIf you don't understand what all of this means, that's ok. The only important factors are:\n\n- if both numbers are equal (or at least close), and they are also equal to the number of inputs that you've set via `-i` command-line argument: everything is going well.\n- if the numbers are different, it means either a misconfiguration or an issue with the input generator. Ensure that `input_per_class` config option is `> 1`.\n- if the numbers are equal, but they are both considerably lower than the number of inputs set via `-i`: You're using an overly simple fuzzing configuration, and you're unlikely to find anything with it.\n\nNone of the issues above should happen if you're using the config file from this tutorial. If they do, double-check your installation.\n\n#### `R:5`\n\nThis is an indirect indicator of the level of noise on the system. More concretely, it is the average sample size used by the executor. It is an adaptive number, which increases when the tool starts to encounter false positive caused by noise.\n\nThis number should be relatively small. If you see that it's going above 10-20 range, it is likely because something is polluting the measurements. Consider applying the suggestions [here](../02-install.md#7-optional-system-configuration).\n\n#### `SF:0,OF:0,Fst:0,CN:0,CT:0,P1:0,CS:0,P2:0`\n\nThese numbers are the statistics on the effectiveness of various optimizations used by Revizor, such as speculation and observation filtering.\n\nYou can ignore these numbers for now, as they are useful only when you're trying to optimize performance of the fuzzer. If you're still curious, though, see the [Fuzzing Statistics Reference](../../ref/runtime-statistic.md).\n\n### Understand what this means\n\nThe successful completion of this baseline campaign tells you several things. Your Revizor installation is working correctly—the fuzzer can generate test cases, execute them on your hardware, collect traces, and analyze the results. Your system is stable enough for fuzzing—there's no excessive noise preventing measurement. The kernel module loaded correctly and can execute test programs in the sandbox environment.\n\n!!! success \"Setup Verified\"\n If you've successfully completed this baseline campaign with no violations, your Revizor installation is ready for real vulnerability detection. You can now proceed to Tutorial 2 with confidence.\n\n!!! warning \"Troubleshooting Common Issues\"\n If the fuzzer crashes or produces errors, check these common problems:\n\n **Module not loaded**: Ensure the kernel module is loaded with `lsmod | grep rvzr_executor`. If not, run `cd rvzr/executor_km && make && sudo make install`.\n\n **Permission denied**: Revizor needs root privileges to access performance counters. Check that your user account on the system has `sudo` privileges.\n\n **ISA specification missing**: If you see \"base.json not found\", run `rvzr download_spec` first to download the instruction set specification.\n\n### What's Next?\n\nYou've finished the first tutorial. Congrats!\n\nIf you're ready to go further and start detecting violations, proceed to [Tutorial 2](./02-first-vuln.md).\n\n" }, { "path": "docs/intro/tutorials/02-first-vuln.md", "content": "# Tutorial 2: Detecting Your First Vulnerability\n\nThis tutorial is the first step into actual vulnerability detection. You'll learn how to set up a fuzzing campaign that tests conditional branches. And, most likely, it will end with a detection of Spectre V1.\n\n### Testing Workflow\n\nBefore we begin with actual testing, let's take a step back and consider how a typical testing workflow looks like.\n\nThe process of using Revizor normally constitutes of the following steps:\n\n1. **Design the campaign** by selecting which instructions to test and choosing an appropriate contract that defines what behavior we consider a violation.\n2. **Create a configuration file** that captures these decisions.\n3. **Run the fuzzer** to generate and execute random test cases.\n4. **Validate the violation** to ensure it's genuine and not a false positive.\n5. **Minimize the test case** to remove unnecessary complexity, making it easier to understand.\n6. **Analyze the minimized program** to identify the root cause of the vulnerability.\n\nIn the following, we will go step-by-step through this workflow.\n\n### Plan the campaign\n\nLet's imagine we have a new CPU and want to determine if conditional branches produce any information leakage on it. These instructions are infamous for causing Spectre V1, therefore it is always useful to start with them when testing a new CPU.\n\nThe first step is planning our fuzzing campaign strategically.\n\nFor effective testing, we'll focus on a minimal instruction subset rather than the entire ISA. Spectre V1 requires only two capabilities: conditional branches (to trigger misprediction) and memory accesses (to leak information through side channels). By limiting our instruction set to just arithmetic operations and conditional branches, we accomplish two goals. First, the fuzzer will find violations faster because there are fewer instruction combinations to explore. Second, when we do find a violation, it will be much easier to analyze because the test case will be simpler.\n\n!!! warning\n Note that this focused approach is *not* representative of a real fuzzing campaign. This tutorial is intentionally simplified to help with understanding. In a real campaign, you'll need to find balance between having a broad scope (increases changes of finding unknown vulnerabilities) and having focus on specific CPU features (simplifies root-cause analysis). For more guidance on campaign design, see [How to Design a Fuzzing Campaign](../../howto/design-campaign.md).\n\nWe'll pair this minimal instruction set with the strictest possible contract—one that forbids any speculation whatsoever. This means Revizor will flag any speculative behavior as a violation. While this contract is more restrictive than what modern CPUs actually guarantee, it's perfect for our purposes. Since we're only testing conditional branches and simple arithmetic, any speculation we detect will almost certainly be Spectre V1.\n\nWith this campaign plan, we are trying to answer a specific question: \"Does this CPU leak information through conditional branches?\"\n\n### Create the configuration file\n\nNow that we've planned our campaign, let's translate it into a configuration file. Create a YAML file with the following content:\n\n```yaml\n# tested instructions\ninstruction_categories:\n - BASE-BINARY\n - BASE-COND_BR\n\n# contract\ncontract_observation_clause: loads+stores+pc\ncontract_execution_clause:\n - no_speculation\n\n# enable perf. optimizations\nenable_speculation_filter: true\nenable_observation_filter: true\nenable_fast_path_model: true\n```\n\nThe `instruction_categories` section implements our decision to use a minimal instruction set. We're including `BASE-BINARY` for arithmetic operations like addition and comparison, and `BASE-COND_BR` for conditional branches like `jz` and `jne`. These two categories give the fuzzer everything it needs to express Spectre V1 patterns.\n\nThe contract configuration consists of two clauses. The `contract_observation_clause` tells Revizor what microarchitectural side effects to track. We're using `loads+stores+pc`, which observes memory access addresses and the program counter—exactly what an attacker would monitor through cache timing attacks. The `contract_execution_clause` defines what execution behavior is allowed. By setting it to `no_speculation`, we're telling Revizor that any speculative execution is a violation.\n\nThe performance optimization flags at the bottom significantly speed up fuzzing without affecting correctness. The `enable_speculation_filter` skips test cases that don't trigger speculation at all. The `enable_observation_filter` skips test cases that leave no observable traces. The `enable_fast_path_model` allows Revizor to reuse contract traces across similar inputs, reducing the model execution overhead.\n\nFor a complete reference of all configuration options, see the [Configuration Reference](../../ref/config.md).\n\n### Run the fuzzer\n\nNow we're ready to start fuzzing. Run Revizor with the following command:\n\n```\n./revizor.py fuzz -s base.json -c config.yaml -n 1000 -i 10 -w .\n```\n\nThis command tells Revizor to run 1000 test cases (`-n 1000`), with 10 inputs per test case (`-i 10`), using the ISA specification from `base.json` (`-s`) and our configuration file (`-c`). The `-w .` flag tells Revizor to save any violations it finds to the current directory.\n\nAs the fuzzer runs, you'll see a continuously updating progress line:\n\n```\n50 ( 5%)| Stats: Cls:10/10,In:20,R:7,SF:38,OF:6,Fst:6,CN:0,CT:0,P1:0,CS:0,P2:0,V:0\n```\n\n### View the detected violation\n\nAfter a minute or so, you should see a violation.\nIt will be reported in a format similar to this:\n\n```\n================================ Violations detected ==========================\nViolation Details:\n\n-----------------------------------------------------------------------------------\n HTrace | ID:4 | ID:14 |\n-----------------------------------------------------------------------------------\n^......^...^........^.................^...........^............. | 626 | 0 |\n^......^...^........^........................................... | 1 | 18 |\n^^.....^...^........^....^...................................... | 0 | 609 |\n\n```\n\nExcellent! We've successfully detected a contract violation. Let's understand what this violation report is telling us.\n\n\nThe report shows us the violation details in a table format. The header row displays the input IDs that triggered the violation—in this case, inputs 4 and 14:\n\n`| ID:4 | ID:14 |`\n\nThese are two inputs from our test case that the contract predicted would behave identically, but the hardware traces show they behaved differently.\n\nThe three rows below show the different hardware traces that were observed:\n\n```\n^......^...^........^.................^...........^.............\n^......^...^........^...........................................\n^^.....^...^........^....^......................................\n```\n\nEach row represents a distinct cache access pattern, visualized as a bitmap where `^` marks an accessed cache line and `.` marks an untouched cache line. We're using Prime+Probe cache side channel measurements (default), so each position in the bitmap corresponds to one of the 64 cache sets in the L1D cache. (A cache set is a group of cache lines that compete for the same position in the cache—when the CPU accesses memory at a particular address, the data goes into a specific cache set determined by the address bits.)\n\nFor example, the first trace reads like this:\n\n```\nCache Set 0 accessed\n| Cache Set 11 accessed\n| | Cache set 38 accessed\n| | |\n^......^...^........^.................^...........^.............\n | | |\n | | Cache Set 50 accessed\n | Cache Set 20 accessed\n Cache Set 7 accessed\n```\n\nFinally, the numbers in the columns tell us how often each trace appeared for each input:\n\n```\n... | 626 | 0 |\n... | 1 | 18 |\n... | 0 | 609 |\n```\n\nLooking at the first hardware trace we see it appeared 626 times for input 4 but never for input 14. The third trace shows the opposite pattern—0 times for input 4 but 609 times for input 14. This clear separation in the distributions confirms this is a genuine violation, not random noise.\n\nWhat we're seeing is a data-dependent cache access pattern. The test case accessed different cache lines depending on the input data, creating an observable side channel. We don't know yet what caused this channel, but we can already tell that it's likely to be caused by speculation; non-speculative cache accesses are permitted by our reference contract, so they wouldn't be reported as violations.\n\nFor more details on interpreting violation reports, see [How to Interpret Violation Results](../../howto/interpret-results.md).\n\n### Violation Artifact\n\nThe artifact for this violation is stored in a directory named `violation-