Revizor is a security-oriented fuzzer for detecting information leaks in CPUs, such as Spectre and Meltdown. It tests CPUs against Leakage Contracts and searches for unexpected leaks.
For more details, see our Paper (open access here), and the follow-up paper.
Warning: Keep in mind that the Revizor runs randomly-generated code in kernel space. As you can imagine, things could go wrong. Make sure you're not running Revizor on an important machine.
-
Architecture: Revizor supports Intel and AMD x86-64 CPUs. We also have experimental support for ARM CPUs (see
arm-portbranch) but it is at very early stages, use it on your own peril. -
No virtualization: You will need a bare-metal OS installation. Testing from inside a VM is not (yet) supported.
-
OS: The target machine has to be running Linux v4.15 or later.
The preferred installation method is using pip within a virtual environment.
The environment must be running Python 3.9 or later.
sudo apt install python3.9 python3.9-venv
/usr/bin/python3.9 -m pip install virtualenv
/usr/bin/python3.9 -m virtualenv ~/venv-revizor
source ~/venv-revizor/bin/activate
pip install revizor-fuzzerThen build and install the kernel module:
# building a kernel module require kernel headers
sudo apt-get install linux-headers-$(uname -r)
# required for cpuid.h
sudo apt-get install linux-headers-generic
# get the source code
git clone https://github.com/microsoft/sca-fuzzer.git
# build the executor
cd sca-fuzzer/src/x86/executor
make uninstall # the command will give an error message, but it's ok!
make clean
make
make installrvzr download_spec -a x86-64 --extensions ALL_SUPPORTED --outfile base.jsonFor more stable results, disable hyperthreading (there's usually a BIOS option for it). If you do not disable hyperthreading, you will see a warning every time you invoke Revizor; you can ignore it.
Optionally (and it really is optional), you can boot the kernel on a single core by adding -maxcpus=1 to the boot parameters (how to add a boot parameter).
The fuzzer is controlled via a single command line interface rvzr (or revizor.py if you're running directly from the source directory).
It accepts the following arguments:
-s, --instruction-set PATH- path to the ISA description file-c, --config PATH- path to the fuzzing configuration file-n , --num-test-cases N- number of test cases to be tested-i , --num-inputs N- number of input classes per test case. The number of actual inputs = input classes * inputs_per_class, which is a configuration option-t , --testcase PATH- use an existing test case instead of generating random test cases--timeout TIMEOUT- run fuzzing with a time limit [seconds]-w- working directory where the detected violations will be stored
For example, this command
rvzr fuzz -s base.json -n 100 -i 10 -c config.yaml -w ./violationswill run the fuzzer for 100 iterations (i.e., 100 test cases), with 10 inputs per test case.
The fuzzer will use the ISA spec stored in the base.json file, and will read the configuration from config.yaml. If the fuzzer finds a violation, it will be stored in the ./violations directory.
See docs for more details.
The fuzzing process is controlled by a configuration file in the YAML format, passed via --config option. At the very minimum, this file should contain the following fields:
contract_observation_clauseandcontract_execution_clausedescribe the contract that the CPU-under-test is tested against. See this page for a list of available contracts. If you don't know what a contract is, Sec. 3 of this paper will give you a high-level introduction to contracts, and this paper will provide a deep dive into contracts.instruction_categoriesis a list of instruction types that will be tested. Effectively, Revizor uses this list to filter out instructions frombase.json(the file you downloaded viarvzr download_spec).
For a full list of configuration options, see docs.
After a fresh installation, it is normally a good idea to do a quick test run to check that everything works ok.
For example, we can create a configuration file config.yaml with only simple arithmetic instructions. As this instruction set does not include any instructions that would trigger speculation on Intel or AMD CPUs (at least that we know of), the expected contract would be CT-SEQ:
# config.yaml
instruction_categories:
- BASE-BINARY # arithmetic instructions
max_bb_per_function: 1 # no branches!
min_bb_per_function: 1
contract_observation_clause: loads+stores+pc # aka CT
contract_execution_clause:
- no_speculation # aka SEQStart the fuzzer:
rvzr fuzz -s base.json -i 50 -n 100 -c config.yaml -w .This command should terminate with no violations.
Next, we could intentionally make a mistake in a contract to check that Revizor can detect it. To this end, we can modify the config file from the previous example to include instructions that trigger speculation (e.g., conditional branches) but keep the contract the same:
# config.yaml
instruction_categories:
- BASE-BINARY # arithmetic instructions
- BASE-COND_BR # conditional branches
max_bb_per_function: 5 # up to 5 branches per test case
min_bb_per_function: 1
max_successors_per_bb: 2 # enable basic blocks with conditional branches
contract_observation_clause: loads+stores+pc # aka CT
contract_execution_clause:
- no_speculation # aka SEQStart the fuzzer:
rvzr fuzz -s base.json -i 50 -n 1000 -c config.yaml -w .As your CPU-under-test almost definitely implements branch prediction, Revizor should detect a violation within a few minutes, with a message similar to this:
================================ Violations detected ==========================
Contract trace (hash):
0111010000011100111000001010010011110101110011110100000111010110
Hardware traces:
Inputs [907599882]:
.....^......^......^...........................................^
Inputs [2282448906]:
...................^.....^...................................^.^
You can find the violating test case as well as the violation report in the directory named ./violation-*/.
It will contain an assembly file program.asm that surfaced a violation, a sequence of inputs input_*.bin to this program, and some details about the violation in report.txt.
To start a full-scale test, write your own configuration file (see description here and an example config here), and launch the fuzzer.
Below is a example launch command, which will start a 24-hour fuzzing session, with 100 input classes per test case, and which uses big-fuzz.yaml configuration:
rvzr fuzz -s base.json -c demo/big-fuzz.yaml -i 100 -n 100000000 --timeout 86400 -w `pwd` --nonstopIf there is a violation, you can try to reproduce it with the following command:
rvzr reproduce -s base.json -c violation-<timestamp>/reproduce.yaml -t violation-<timestamp>/program.asm -i violation-<timestamp>/input_*.binIf the violation is reproducible, it is useful to minimize it, so that it is easier to understand the root cause (note that minimization uses a different config file):
rvzr minimize -s base.json -c violation-<timestamp>/minimize.yaml -g violation-<timestamp>/program.asm -o violation-<timestamp>/minimized.asm -i 100 --simplify --enable-multipass --find-sourcesThe result of minimization will be stored in violation-<timestamp>/minimized.asm. The further analysis is manual; you can find an example in this guide.
If you find a bug in Revizor, don't hesitate to open an issue.
If something is confusing or you need help in using Revizor, we have a discussion page.
For more details, see the website.
See CONTRIBUTING.md.
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent