UzL-ITS / Microwalk
Labels
Projects that are alternatives of or similar to Microwalk
Microwalk
Microwalk is a microarchitectural leakage detection framework, which combines dynamic instrumentation and statistical methods in order to identify and quantify side-channel leakages. For the scientific background, consult the corresponding paper.
Compiling
For Windows, it is recommended to install Visual Studio, as it brings almost all dependencies and compilers, as well as debugging support. The solution can then be built directly in the IDE.
The following guide is mostly for Linux systems and command line builds on Windows.
Main application
The main application is based on .NET Core 3.1, so the .NET Core 3.1 SDK is required for compiling.
Compile command:
cd Microwalk
dotnet build -c Release
Run command:
cd Microwalk
dotnet run <args>
The command line arguments <args>
are documented in Section "Configuration"
Pin tool
Microwalk comes with a Pin tool for instrumenting and tracing x86 binaries. Building the Pin tool requires the full Pin kit, preferably the latest version. It is assumed that Pin's directory path is contained in the variable $pinDir
.
When building through Visual Studio: Edit Settings.props to point to the Pin directory.
Compile command:
cd PinTracer
make PIN_ROOT="$pinDir" obj-intel64/PinTracer.so
Run command (assuming the pin
executable is in the system's PATH
):
pin -t PinTracer/obj-intel64/PinTracer.so -o /path/to/output/file -- /path/to/wrapper/executable
Note that the above run command is needed for testing/debugging only, since Microwalk
calls the Pin tool itself.
Pin wrapper executable
In order to efficiently generate Pin-based trace data, Microwalk needs a special wrapper executable which interactively loads and executes test cases. The PinTracerWrapper
project contains a skeleton program with further instructions ("/*** TODO ***/
").
The wrapper skeleton is C++-compatible and needs to be linked against the target library. It works on both Windows and Linux (GCC).
Alternatively, it is also possible to use an own wrapper implementation, as long as it exports the Pin notification functions and correctly handles stdin
.
Running Microwalk
The general steps for analyzing a library with Microwalk are:
-
Copy and adjust the
PinTracerWrapper
program to load the investigated library, and read and execute test case files. It is advised to test the wrapper with a few dummy test cases, and use debug outputs to verify its correctness. Make to sure to remove these debug outputs afterwards, else they may clutter the I/O pipe which Microwalk uses for communication with the dynamic instrumentation framework, and lead to errors. -
Create a custom test case generator module, or check whether the built-in ones are able to yield the expected input formats. Guidelines for adding custom framework modules can be found in the section "Creating own framework modules".
-
Compose a configuration file which describes the steps to be executed by Microwalk.
Configuration
Microwalk takes a single command line argument, which is the path to a YAML-based configuration file.
Creating own framework modules
Follow these steps to create a custom framework module:
-
Create a new class in the respective
Modules
subfolder, which inherits fromXyzStage
and has a[FrameworkModule]
attribute.XyzStage
here corresponds to one of the framework's pipeline stages:-
TestcaseStage
(TestcaseGeneration
directory): Produces a new testcase on each call. -
TraceStage
(TraceGeneration
directory): Takes a testcases and generates raw trace data. -
PreprocessorStage
(TracePreprocessing
directory): Takes raw trace data and preprocesses it. -
AnalysisStage
(Analysis
directory): Takes preprocessed trace data and updates its internal state for each trace. Yields an analysis result once the finish function is called.
-
-
Implement the module logic.
-
Register the module, by calling the
XyzStage.Register<>
function inMain
(Program.cs). -
Compile Microwalk.
Contributing
Contributions are appreciated! Feel free to submit issues and pull requests.
License
The entire system is licensed under the MIT license. For further information refer to the LICENSE file.