Mariana Trench is highly configurable and we recommend that you invest time into adjusting the tool to your specific use cases. At Facebook, we have dedicated security engineers that will spend a significant amount of their time adding new rules and model generators to improve the analysis results.
This page will cover the more important, non-trivial configuration options. Note that you will spend most of your time configuring Mariana Trench writing model generators. These are covered in the next section.
Command Line Options
You can get a full set of options by running
mariana-trench --help. The following is an abbreviated version of the output.
$ mariana-trench --help
--apk-path APK_PATH The APK to analyze.
The directory to store results in.
A JSON configuration file with a list of paths to the system jars.
A `;`-separated list of rules files and directories containing rules files.
The root of the repository. Resulting paths will be relative to this.
The root where source files for the APK can be found.
A `;`-separated list of paths specifying JSON configuration files. Each file is a list of paths to JSON model generators relative to the
configuration file or names of CPP model generators.
A `;`-separated list of paths where we look up JSON model generators.
Limits the distance of sources and sinks from a trace entry point.
Mariana Trench analyzes Dalvik bytecode. You provide it with the android app (APK) to analyze.
The output of the analysis is a file containing metadata about the particular run in JSON format as well as sharded files containing data flow specifications for every method in the APK. These files need to be processed by SAPP (see Getting Started) after the analysis. The flag specifies where these files are saved.
This path points to a json file containing a list of
.jar files that the analysis should include in the analysis. It's important that this contains at least the
android.jar on your system. This file is typically located in your android SDK distribution at
$ANDROID_SDK/platforms/android-30/android.jar. Without the
android.jar, Mariana Trench will not know about many methods from the standard library that might be important for your model generators.
; separated search path pointing to files and directories containing rules files. These files specify what taint flows Mariana Trench should look for. Check out the
rules.json that's provided by default. It specifies that we want to find flows from user controlled input (
CodeExecution sinks and that this constitutes a remote code execution.
Mariana Trench will do a source indexing path before the analysis. This is because Dalvik/Java bytecode does not contain complete location information, only filenames (not paths) and line numbers. The index is later used to emit precise locations.
; separated set of files containing the names of model generators to run. See
default_generator_config.json for an example.
; separated search path where Mariana Trench will try to find the model generators specified in the generator configuration.
For performance reasons it can be useful to limit the maximum length of a trace Mariana Trench tries to find (note that longer traces also tend to be harder to interpret). Due to the modular nature of the analysis the value specified here limits the maximum length from the trace root to the source, and from the trace root to the sink. This means found traces can have length of
2 x MAXIMUM_SOURCE_SINK_DISTANCE.