Mariana Trench: finding Android data flows that reach dangerous sinks

The unit of output is a data flow, not a finding

Mariana Trench is described as a security focused static analysis platform targeting Android, and the way it reports things is the thing to understand first.

The output of an analysis is a set of specifications for each method of the application, and those specifications are not meant to be read by humans. What comes out of the tool is a flow: data arriving from a source, travelling through a call chain, and arriving at a sink. The sample application in the project documentation makes this concrete. The analysis finds a remote code execution in `MainActivity.onCreate`, where the data comes from `Activity.getIntent` one call away and flows into the constructor of `ProcessBuilder` three calls away.

That framing is what separates this from a scanner. A scanner that knows a set of dangerous API calls will tell you an app calls `Runtime.exec`. Mariana Trench tells you whether untrusted data can reach that call, and by which path, which is the only question that matters when you are deciding whether to file a bug.

The documentation also points at a companion tool for reading the output. The specifications are processed with SAPP, a separate PyPI package, which produces a local web interface for exploring the results, and a filter at the top right of the page is what you use once there are more issues than you can read one by one.

A trace has three parts, and the root is the one that surprises people

Each reported flow is broken into three components, and the split is the model you have to internalise to read the results.

The source trace is where the data comes from. In the sample app it is very short: `Activity.getIntent` is called in `MainActivity.onCreate` directly. The sink trace is where that data flows down into the dangerous call, and in the example it runs from `onCreate` to `onClick` to `execute`, and finally into the constructor of `ProcessBuilder`.

The trace root is the part in between, where the source trace meets the sink trace. In the example the root is the activity's `onCreate` method. That is the pivot: the source is one call away, the sink is three calls away, and the root is the frame where the two halves connect. For a person reading a report, the root is usually where the fix goes, because a fix at the root cuts the path for every variant of it, whereas a fix at the sink means auditing every call site of that sink.

The issue is identified by an issue code, `1` for all remote code executions in the sample, together with the callable. So a report is a code, a method, and three traces, and the filter in the web interface is what lets you narrow to one code when the run produces a list.

Sources and sinks are yours to define in the rule files

A reasonable question when you first run the tool is how it knows what is user controlled data and what is a sink, and the project documentation answers it by not answering it in the getting started guide.

The guide is explicit that it is meant to get you started quickly on a small app, and that it does not cover how to configure the tool. That work is pointed at the configuration documentation on the project website. The implication is worth stating plainly: the rules are data, not code, and you supply them.

The repository layout supports that. There is a `configuration/` directory at the top level, and the command line in the documentation references specific files inside it, a system jar configuration path at `configuration/default_system_jar_paths.json`, a model generator configuration at `configuration/default_generator_config.json`, lifecycles at `configuration/lifecycles.json`, rules at `configuration/rules.json`, and a model generator search path at `configuration/model-generators/`.

The `rules.json` file is where a source or a sink is declared, and the model generators are what let the tool synthesise models for code it did not analyse, which is how it reasons about calls into libraries and the Android framework. The system jar configuration is what points it at the platform's own classes for the same reason.

The practical consequence is that the tool ships with defaults that suit the sample app, and a real application needs a ruleset that matches its own sources and sinks. A run that reports nothing may mean the analysis is correct and your app is clean, or it may mean the rule set does not cover the APIs your app actually uses. Distinguishing those two is the skill this tool requires.

Install is a pip install, and Apple silicon needs a source build

Setting it up is a short sequence, and the prerequisites are worth reading before you start.

The tool requires a recent version of Python, and on macOS you can get one through homebrew with `brew install python3`. On a Debian flavoured Linux, Ubuntu, Mint or Debian, the equivalent is `sudo apt-get install python3 python3-pip python3-venv`. The guide also assumes the Android SDK is installed and that an environment variable `$ANDROID_SDK` points at it.

Then a virtual environment, so that the tool's dependencies do not collide with the rest of your Python setup:

python3 -m venv ~/.venvs/mariana-trench
source ~/.venvs/mariana-trench/bin/activate

With the environment active, the install is one command:

pip install mariana-trench

The one caveat is a platform one. pip install is not currently supported for Apple silicon Macs, and the fix is to build from source using the instructions in the Developer's Guide. Since the implementation language is C++ and the build is driven by `CMakeLists.txt` with a `cmake/` directory, the source build is a real toolchain requirement rather than a formality.

The developer documentation covers the in-depth build and development workflow, and the repository has a `CONTRIBUTING.md` and a `CODE_OF_CONDUCT.md` alongside a `.github/` directory with a tests workflow.

Running it takes six configuration paths and an APK

The command line is long, and that is informative about what the tool needs to do its job.

The sample run in the documentation points at a small app that ships with the project, cloned from the repository:

git clone https://github.com/facebook/mariana-trench
cd mariana-trench/

The analysis itself then names the configuration files and the artifact to analyse:

mariana-trench \
  --system-jar-configuration-path=configuration/default_system_jar_paths.json \
  --model-generator-configuration-paths=configuration/default_generator_config.json \
  --lifecycles-paths=configuration/lifecycles.json \
  --rules-paths=configuration/rules.json \
  --apk-path=documentation/sample-app/app/build/outputs/apk/debug/app-debug.apk \
  --source-root-directory=documentation/sample-app/app/src/main/java \
  --model-generator-search-paths=configuration/model-generators/

Read the arguments in order and the architecture becomes clear. The system jar configuration points at the Android platform classes. The model generator configuration and search paths tell the tool how to model code it cannot see into, which is how it follows a call into a library and still knows what that library does with the data. The lifecycles file describes the entry points, such as an activity's `onCreate` receiving an Intent, which is how a source gets connected to the flow. The rules file defines the sources and sinks. The APK path is the application to analyse and the source root is where the matching sources live, so that a report can point at a line of code.

The output ends with a count of the models analysed and the issues found, which on the sample app is 9 issues.

So the tool works on the APK rather than on the source tree, and the source tree is there to make the results readable. That is a deliberate design: analysing the compiled artifact is what makes the analysis apply to what actually ships.

SAPP turns the output into something you can read

The specifications Mariana Trench produces are not readable, and the project says so. A separate processing step is needed to make the results presentable, and that step is SAPP, installed from PyPI.

sapp --tool=mariana-trench analyze .
sapp --database-name=sapp.db server --source-directory=documentation/sample-app/app/src/main/java

The first command ingests the analysis output into a database. The second starts a local web server, and the documentation shows it running on `http://localhost:13337/`. Opening that link gives the web interface, where the issues are listed, each one identified by its issue code and callable, and where the filter at the top right of the page becomes the main tool once there are more than a handful of issues.

The `Traces` button in the top right of an issue opens the three-part trace, and clicking through source, root and sink shows the call chain that the report describes.

There is a small discrepancy in the documentation worth noting, since it will confuse a reader who follows it literally. The sample analysis run reports 9 issues, while the text describing the web interface refers to 4 issues being found. The two numbers do not reconcile from the documentation alone. The practical lesson is that the issue count depends on the rule set and the app, so treat any number in a tutorial as an illustration of the shape of the output rather than a target your own run should match.

Where Mariana Trench is the wrong tool

The first case is a codebase you do not have a ruleset for. The tool is only as good as the sources and sinks you declare, and the getting started guide deliberately does not explain how to write them. A team that wants a result in an afternoon will not get one here unless its app resembles the sample, where the defaults happen to cover the interesting calls.

The second case is a small application. For a handful of activities and a few known inputs, reading the code and checking the dangerous calls by hand will be faster and more reliable than configuring a whole flow analysis. The overhead of a taint engine is only worth it once the app is large enough that a flow you did not think of could exist somewhere in it.

The third case is a non-Android target. The project targets Android, the model generation and lifecycle configuration are built around Android concepts such as activity entry points and the platform's own classes, and the analysis takes an APK.

There is one deployment constraint that affects adoption planning rather than correctness. The pip install does not work on Apple silicon, so an organisation standardising on Macs has to run a source build for every developer and for CI, which is a real tax on a tool otherwise distributed as a single package. And a project that wants the results inside an existing security pipeline needs to run SAPP alongside it, since the raw output is machine-oriented by design.

Editorial conclusion

Mariana Trench fits an Android security team that wants whole-app data flow analysis on an application large enough that manual taint tracking stops working, and it does not fit a team that needs results without configuration, because what counts as a source and what counts as a sink is decided by the rule files you supply. Before running it on a real application, read the configuration documentation at mariana-tren.ch/docs/configuration and check the rule set, since the sample run in the project documentation is over a small app and a different rule set will produce a different issue count.

Frequently asked questions

Official sources

1. facebook/mariana-trench on GitHub
2. Issues
3. License: MIT
4. Project website
5. README