Skip to main content

A security focused static analysis platform targeting Android.

Project description

Mariana Trench

logo

MIT License .github/workflows/tests.yml

Mariana Trench is a security focused static analysis platform targeting Android.

This guide will walk you through setting up Mariana Trench on your machine and get you to find your first remote code execution vulnerability in a small sample app. These instructions are also available at our website.

Prerequisites

Mariana Trench requires a recent version of Python. On MacOS you can get a current version through homebrew:

$ brew install python3

On a Debian flavored Linux (Ubuntu, Mint, Debian), you can use apt-get:

$ sudo apt-get install python3 python3-pip python3-venv

This guide also assumes you have the Android SDK installed and an environment variable $ANDROID_SDK pointed to the location of the SDK.

For the rest of this guide, we assume that you are working inside of a virtual environment. You can set this up with

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

The name of the virtual environment in front of your shell prompt indicates that the virtual environment is active.

Installing Mariana Trench

Inside your virtual environment installing Mariana Trench is as easy as running

(mariana-trench)$ pip install mariana-trench

Note: pip install is not currently supported for Apple silicon Macs, you can build from source using the instructions in the Developer's Guide.

Running Mariana Trench

We'll use a small app that is part of our documentation. You can get it by running

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

We are now ready to run the analysis

(mariana-trench)$ mariana-trench \
  --system-jar-configuration-path=$ANDROID_SDK/platforms/android-32/android.jar \
  --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/

# ...
INFO Analyzed 68937 models in 7.47s. Found 9 issues!
# ...

The analysis has found 9 issues in our sample app. The output of the analysis is a set of specifications for each method of the application.

Post Processing

The specifications themselves are not meant to be read by humans. We need an additional processing step in order to make the results more presentable. We do this with SAPP PyPi installed for us:

(mariana-trench)$ sapp --tool=mariana-trench analyze .
(mariana-trench)$ sapp --database-name=sapp.db server --source-directory=documentation/sample-app/app/src/main/java
# ...
2021-05-12 12:27:22,867 [INFO]  * Running on http://localhost:13337/ (Press CTRL+C to quit)

The last line of the output tells us that SAPP started a local webserver that lets us look at the results. Open the link and you will see the 4 issues found by the analysis.

Exploring Results

Let's focus on the remote code execution issue found in the sample app. You can identify it by its issue code 1 (for all remote code executions) and the callable void MainActivity.onCreate(Bundle). With only 4 issues to see it's easy to identify the issue manually but once more rules run, the filter functionality at the top right of the page comes in handy.

Single Issue Display

The issue tells you that Mariana Trench found a remote code execution in MainActivity.onCreate where the data is coming from Activity.getIntent one call away, and flows into the constructor of ProcessBuilder 3 calls away. Click on "Traces" in the top right corner of the issue to see an example trace.

The trace surfaced by Mariana Trench consists of three parts.

The source trace represents where the data is coming from. In our example, the trace is very short: Activity.getIntent is called in MainActivity.onCreate directly. Trace Source

The trace root represents where the source trace meets the sink trace. In our example this is the activitie's onCreate method. Trace Root

The final part of the trace is the sink trace: This is where the data from the source flows down into a sink. In our example from onCreate, to onClick, to execute, and finally into the constructor of ProcessBuilder. Trace Sink

Configuring Mariana Trench

You might be asking yourself, "how does the tool know what is user controlled data, and what is a sink?". This guide is meant to quickly get you started on a small app. We did not cover how to configure Mariana Trench. You can read more about that at our website under Configuration.

Contributing

For an in-depth guide on building from source and development on Mariana Trench, see the Developer's Guide at our website.

License

Mariana Trench is licensed under the MIT license.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mariana-trench-1.0.6.tar.gz (6.2 MB view details)

Uploaded Source

Built Distributions

mariana_trench-1.0.6-py3-none-macosx_10_11_x86_64.whl (5.0 MB view details)

Uploaded Python 3 macOS 10.11+ x86-64

File details

Details for the file mariana-trench-1.0.6.tar.gz.

File metadata

  • Download URL: mariana-trench-1.0.6.tar.gz
  • Upload date:
  • Size: 6.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.7

File hashes

Hashes for mariana-trench-1.0.6.tar.gz
Algorithm Hash digest
SHA256 1e60fca54320cbcd5252991999369d0f9da4d1e28a5cdf9b0b59d3536993d33d
MD5 76fe04b96afccef01002d1f4a6568d35
BLAKE2b-256 b8985ab451abaf6dd8313e8dc7052eaaee99c4f742b0c9ebd8f3d3a877daeb81

See more details on using hashes here.

File details

Details for the file mariana_trench-1.0.6-py3-none-manylinux1_x86_64.whl.

File metadata

File hashes

Hashes for mariana_trench-1.0.6-py3-none-manylinux1_x86_64.whl
Algorithm Hash digest
SHA256 7e02f94b48d6d91ef0959e9863076a44c725dbc0059c2bf968ce2297146481d9
MD5 0dd9ccabcf07d8bf2aee2cc889d91db9
BLAKE2b-256 7bd9f4e6dfc315415445fd42a78acebf1f95754a86b601aaa87d3bb617505719

See more details on using hashes here.

File details

Details for the file mariana_trench-1.0.6-py3-none-macosx_10_11_x86_64.whl.

File metadata

File hashes

Hashes for mariana_trench-1.0.6-py3-none-macosx_10_11_x86_64.whl
Algorithm Hash digest
SHA256 bf0f00e32fd186989ffbd828889567d23d350cef85a57a57a6abf290bc669b03
MD5 2d0aa8bf89edc6b604da5213a3720512
BLAKE2b-256 1fc6cd0763e9af2e69b0fcc45d5ec71307b4e2d71da9543e5b471fe79008c745

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page