# Mariana Trench
[](http://choosealicense.com/licenses/mit/)
[](https://github.com/facebook/mariana-trench/actions/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](https://mariana-tren.ch/docs/getting-started).
## Prerequisites
Mariana Trench requires a recent version of [Python](https://www.python.org/downloads/). On MacOS you can get a current version through [homebrew](https://brew.sh/):
```shell
$ brew install python3
```
On a Debian flavored Linux (Ubuntu, Mint, Debian), you can use `apt-get`:
```shell
$ sudo apt-get install python3 python3-pip python3-venv
```
This guide also assumes you have the [Android SDK](https://developer.android.com/studio) 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](https://docs.python.org/3/tutorial/venv.html). You can set this up with
```shell
$ 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
```shell
(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](https://mariana-tren.ch/docs/contribution#building-from-source).
## Running Mariana Trench
We'll use a small app that is part of our documentation. You can get it by running
```shell
(mariana-trench)$ git clone https://github.com/facebook/mariana-trench
(mariana-trench)$ cd mariana-trench/
```
We are now ready to run the analysis
```shell
(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](https://github.com/facebook/sapp) PyPi installed for us:
```shell
(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.
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.
The *trace root* represents where the source trace meets the sink trace. In our example this is the activitie's `onCreate` method.
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`.
## 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](https://mariana-tren.ch/docs/configuration).
## Contributing
For an in-depth guide on building from source and development on Mariana Trench, see the [Developer's Guide](https://mariana-tren.ch/docs/contribution) at our website.
## License
Mariana Trench is licensed under the MIT license.
Raw data
{
"_id": null,
"home_page": "https://mariana-tren.ch/",
"name": "mariana-trench",
"maintainer": "Facebook",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "pyre@fb.com",
"keywords": "security,taint,flow,static,analysis,android,java",
"author": "Facebook",
"author_email": "pyre@fb.com",
"download_url": "https://files.pythonhosted.org/packages/46/44/2f543cfa8458520f7b60bc4a22c4be379f978561f5eb9dc32dfff3cf37a0/mariana-trench-1.0.5.tar.gz",
"platform": null,
"description": "# Mariana Trench\n\n\n\n[](http://choosealicense.com/licenses/mit/)\n[](https://github.com/facebook/mariana-trench/actions/workflows/tests.yml)\n\nMariana Trench is a security focused static analysis platform targeting Android.\n\nThis 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](https://mariana-tren.ch/docs/getting-started).\n\n## Prerequisites\nMariana Trench requires a recent version of [Python](https://www.python.org/downloads/). On MacOS you can get a current version through [homebrew](https://brew.sh/):\n\n```shell\n$ brew install python3\n```\n\nOn a Debian flavored Linux (Ubuntu, Mint, Debian), you can use `apt-get`:\n\n```shell\n$ sudo apt-get install python3 python3-pip python3-venv\n```\n\nThis guide also assumes you have the [Android SDK](https://developer.android.com/studio) installed and an environment variable `$ANDROID_SDK` pointed to the location of the SDK.\n\nFor the rest of this guide, we assume that you are working inside of a [virtual environment](https://docs.python.org/3/tutorial/venv.html). You can set this up with\n\n```shell\n$ python3 -m venv ~/.venvs/mariana-trench\n$ source ~/.venvs/mariana-trench/bin/activate\n(mariana-trench)$\n```\n\nThe name of the virtual environment in front of your shell prompt indicates that the virtual environment is active.\n\n## Installing Mariana Trench\nInside your virtual environment installing Mariana Trench is as easy as running\n\n```shell\n(mariana-trench)$ pip install mariana-trench\n```\n\nNote: pip install is not currently supported for Apple silicon Macs, you can build from source using the instructions in the [Developer's Guide](https://mariana-tren.ch/docs/contribution#building-from-source).\n\n## Running Mariana Trench\nWe'll use a small app that is part of our documentation. You can get it by running\n\n```shell\n(mariana-trench)$ git clone https://github.com/facebook/mariana-trench\n(mariana-trench)$ cd mariana-trench/\n```\n\nWe are now ready to run the analysis\n\n```shell\n(mariana-trench)$ mariana-trench \\\n --system-jar-configuration-path=$ANDROID_SDK/platforms/android-32/android.jar \\\n --model-generator-configuration-paths=configuration/default_generator_config.json \\\n --lifecycles-paths=configuration/lifecycles.json \\\n --rules-paths=configuration/rules.json \\\n --apk-path=documentation/sample-app/app/build/outputs/apk/debug/app-debug.apk \\\n --source-root-directory=documentation/sample-app/app/src/main/java \\\n --model-generator-search-paths=configuration/model-generators/\n\n# ...\nINFO Analyzed 68937 models in 7.47s. Found 9 issues!\n# ...\n```\n\nThe 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.\n\n## Post Processing\nThe 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](https://github.com/facebook/sapp) PyPi installed for us:\n\n```shell\n(mariana-trench)$ sapp --tool=mariana-trench analyze .\n(mariana-trench)$ sapp --database-name=sapp.db server --source-directory=documentation/sample-app/app/src/main/java\n# ...\n2021-05-12 12:27:22,867 [INFO] * Running on http://localhost:13337/ (Press CTRL+C to quit)\n```\n\nThe 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.\n\n## Exploring Results\nLet'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.\n\n\n\nThe 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.\n\nThe trace surfaced by Mariana Trench consists of three parts.\n\nThe *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.\n\n\nThe *trace root* represents where the source trace meets the sink trace. In our example this is the activitie's `onCreate` method.\n\n\nThe 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`.\n\n\n## Configuring Mariana Trench\nYou 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](https://mariana-tren.ch/docs/configuration).\n\n## Contributing\nFor an in-depth guide on building from source and development on Mariana Trench, see the [Developer's Guide](https://mariana-tren.ch/docs/contribution) at our website.\n\n## License\nMariana Trench is licensed under the MIT license.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A security focused static analysis platform targeting Android.",
"version": "1.0.5",
"project_urls": {
"Download": "https://github.com/facebook/mariana-trench",
"Homepage": "https://mariana-tren.ch/"
},
"split_keywords": [
"security",
"taint",
"flow",
"static",
"analysis",
"android",
"java"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "02348af1aafa5656af4bf4e72cd9f92716bfa8074f13e3be88287551df8b16e9",
"md5": "71fed47d66fb4be2a2dae8e84d9fc16f",
"sha256": "d751ed6d383bd99f1c6ed7201f9314e1fbd35efa1a93317a2ae108274100b594"
},
"downloads": -1,
"filename": "mariana_trench-1.0.5-py3-none-macosx_10_11_x86_64.whl",
"has_sig": false,
"md5_digest": "71fed47d66fb4be2a2dae8e84d9fc16f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 4779517,
"upload_time": "2023-10-16T11:27:07",
"upload_time_iso_8601": "2023-10-16T11:27:07.601208Z",
"url": "https://files.pythonhosted.org/packages/02/34/8af1aafa5656af4bf4e72cd9f92716bfa8074f13e3be88287551df8b16e9/mariana_trench-1.0.5-py3-none-macosx_10_11_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fbed80026728f17af2855b0a9b971cb1c1cc2ed65d3f6cd8b27dba6ac8e1c3ac",
"md5": "29d5a007c2c77d05644297d100089768",
"sha256": "828c60ce9480cceb024815abf5072a5a199afe5a717acf16af96fedde5af8987"
},
"downloads": -1,
"filename": "mariana_trench-1.0.5-py3-none-manylinux1_x86_64.whl",
"has_sig": false,
"md5_digest": "29d5a007c2c77d05644297d100089768",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 6022837,
"upload_time": "2023-10-16T11:27:09",
"upload_time_iso_8601": "2023-10-16T11:27:09.531095Z",
"url": "https://files.pythonhosted.org/packages/fb/ed/80026728f17af2855b0a9b971cb1c1cc2ed65d3f6cd8b27dba6ac8e1c3ac/mariana_trench-1.0.5-py3-none-manylinux1_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "46442f543cfa8458520f7b60bc4a22c4be379f978561f5eb9dc32dfff3cf37a0",
"md5": "0ccebad19cc04770de8aca28beac024f",
"sha256": "6bde13d5b70738850f58ced0507703605e095dd617d9e5b3e9b23fc193a41daa"
},
"downloads": -1,
"filename": "mariana-trench-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "0ccebad19cc04770de8aca28beac024f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 5970449,
"upload_time": "2023-10-16T11:27:11",
"upload_time_iso_8601": "2023-10-16T11:27:11.387972Z",
"url": "https://files.pythonhosted.org/packages/46/44/2f543cfa8458520f7b60bc4a22c4be379f978561f5eb9dc32dfff3cf37a0/mariana-trench-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-16 11:27:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "facebook",
"github_project": "mariana-trench",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mariana-trench"
}
JSON
