Hammertime: a software suite for testing, profiling and simulating the rowhammer DRAM defect.
While still a work in progress, the following components make up Hammertime:
libramses
: a library that handles address translation for the entire memory stack.libperfev-util
: a library providing a more human-friendly interface to Linux's performance event API.- Probes for monitoring memory access behaviour of running programs.
- Predictors that decide whether a certain memory access behaviour triggers rowhammer.
- Glue code to tie all this together and effect bit flips in memory.
- Fliptables: example profiles of rowhammer-vulnerable DRAM chips, usable by a dedicated predictor.
- Various cool tools and utilities:
tools/profile
: a tool to test a running system's vulnerability to rowhammer. For more information, check out its own README file undertools/profile/README
. NOTE: this tool is still an experimental bundle of spaghetti code which will get rewritten at some point. Therefore do not consider any part of it a stable API until this notice is removed.py/prettyprofile.py
converts aprofile
output into something more human-friendly.py/hammerprof.py
converts aprofile
output into a fliptable.py/common_flips.py
processes multipleprofile
results selecting only bit flips common to all. Useful for finding bit flips that can be reliably triggered.py/pyramses
is a Python interface tolibramses
.py/hammertime/
contains Python interfaces to work with profile results and fliptables.py/hammertime/estimate.py
is a framework for rapidly estimating Rowhammer attack effectiveness, based on exploit models and profile results.ramses/tools/msys_detect.py
is an interactive tool for detecting current system memory configuration.
For an in-depth view of how these components fit together and the overall architecture of Hammertime check out DESIGN.md
and browse the source code.
Header files are particularly explanation-rich.
NOTE: a singular application providing user-friendly access to Hammertime's features is planned. Until then, Hammertime is intended to be more like a toolbox you use from your own programs.
The main intended use case is as a bit flip simulator for arbitrary programs. That would, in principle, involve the following sequence of activities:
- Setup and attach a probe to a task / PID / system
- Collect probe output and feed it into a predictor
- Respond to events generated by the predictor
- Produce bit flips when instructed by the predictor
- Go back to step 2 for as long as you feel like
The demo
program presents a proof-of-concept implementation of a rowhammer bit flip simulator for various run scenarios.
In addition tools/profile
is a powerful rowhammer testing and profiling tool.
- Linux kernel >= 3.18 with headers
glibc
with pthread supportlibpfm4
- Python >= 3.2 --- used by tools
Run make
in the root directory to build all Hammertime components and tools, except for the demo binary.
make demo
will build the demo binary.
make all
will build everything there is to build.
make clean
removes all previously built files except for fliptables.
make cleanall
removes all built files.
A memory configuration (i.e. .msys
) file includes information about the memory controller, physical address router, DRAM geometry and optional on-chip remapping.
Figuring these out by hand is tedious; here's where a tool comes in.
Run ramses/tools/msys_detect.py
, ideally as a superuser.
It will try to auto-detect most parameters and ask you for the others.
The output file it produces can now be used by other Hammertime components.
The profile tool requires elevated permissions.
Either run it as root or run make cap
as root in its directory to set the necessary capabilities on the binary.
Example run with only the essential arguments:
tools/profile/profile -s 256m spam.msys
will run a basic double-sided rowhammer attack over 256MiB of RAM using spam.msys
as memory configuration file.
The output may seem a bit cryptic. To remedy this, use the prettifying script:
tools/profile/profile -s 256m spam.msys | py/prettyprofile.py -
as a shell pipeline or
tools/profile/profile -s 256m spam.msys myprof.res
py/prettyprofile.py myprof.res
by using a temporary file (the .res
extension stands for "result"; it's the default one expected by the fliptable build system. More on that later)
Check out profile
's own README file for more options and how to read its raw output.
The demo
program is a good place to start.
The program is not intended as a proper component of Hammertime, rather more like a runnable "What's new" showcase.
- Read the source code in
demo.c
andglue.c
to get an idea of how to get Hammertime's components working together. - (Optionally) Edit
demo.c
to suit your needs (tweaking thresholds, input file paths, etc.) - Run
make demo
- Run
demo
as root:./demo <PID>
attaches to the main thread of a running process specified by PID./demo -e <PROGRAM> [ARGS]
launches PROGRAM with ARGS as arguments and attaches to it; this also monitors all spawned threads./demo -s
attaches to the entire running system. NOTE: Requires an unrestricted/dev/mem
, which means you most probably have to recompile your kernel withCONFIG_STRICT_DEVMEM=n
The fliptables/
directory contains some example fliptables based on profile runs of real DRAM chips.
Rowhammer attack patterns of single-sided, double-sided, adjacent (a.k.a. "amplified") and double-sided under memory pressure are provided.
.msys
files describing the memory layout of tested modules are also included.
Say you have found bit flips running profile
and want to use them with the simulator.
Simply run
py/hammerprof.py myprof.res myprof.fliptbl
to convert the profile
output myprof.res
into a binary fliptable.
Alternatively just place your .res
file(s) under fliptables/
and run make fliptables
.
The build system will take care of the rest.
Great! Include your changes under ramses/
and send a pull request.
Take care not to break the ramses ABI though.
Currently, AMD memory controller mapping support is missing and would be greatly appreciated. The specs are out there in AMD's BIOS and Kernel Developer's Guide (BKDG): AMD Developer Manuals. Search for "DRAM Address Mapping".
Include your changes under the appropriate directory and send a pull request. Try to stick to the generic interface for your component so it won't require custom glue code.
Report it on the bug tracker here.
Get in touch with me. See e-mail below.
Have a question, suggestion, comment? Drop me an e-mail at andrei.ttr@gmail.com .