# facebook/mariana-trench architecture

> Architecture diagram of the GitHub repository facebook/mariana-trench, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/facebook/mariana-trench
- Repository: https://github.com/facebook/mariana-trench

## Overview

##### Project Type and Purpose
- Mariana Trench is an open‐source, security‐focused static analysis platform targeting Android.
- It comprises a command‐line interface (CLI), a Python shim layer, a high-performance C++ analysis core, model‐generation infrastructure, configuration artifacts, and documentation/website components.

##### File Structure
- Top‐level components
– .github/workflows: CI pipelines for tests, PyPI publishing, website builds
– cmake/…, CMakeLists.txt: build system for the C++ core
– configuration/: JSON configs for system jars, rules, filters, model generators, lifecycles
– desugar/: Java utility to preprocess/transform bytecode before analysis
– documentation/sample-app: example Android app used for demos
– documentation/website: Docusaurus site source for docs and blog
– scripts/: Python and shell scripts for building, testing, model‐inspection
– shim/: Python shim that wraps the C++ binary and exposes the CLI entrypoint
– source/: C++ code, subdivided into
· core analysis (taint tracking, call graphs, CFGs, alias analysis, type analysis)
· model‐generator modules (JSON template engines, feature/sanitizer/sink generators)
· shim‐generator modules
· test suites (unit tests, integration tests, JSON‐model generator tests)
- Notice the separation of concerns: configuration files drive analysis rules and model generation; the C++ core is invoked via Python; test code heavily covers both C++ and model‐generator behavior.

##### README for Additional Insights
- The Python CLI (“mariana-trench” command) parses arguments, locates configuration paths, invokes the compiled C++ binary.
- Output from analysis is a set of raw specifications that must be post‐processed by SAPP to produce human‐readable web output.
- The docs site and sample app illustrate how users run the tool end‐to‐end.

##### Main Components and Their Interactions

A. CLI & Python Shim (Python)
– Entrypoint: parses flags (system-jar-paths, model configs, lifecycles, rules, apk path, source root)
– Invokes the C++ analysis binary (Mariana Trench core) via a subprocess or Python binding
– Loads JSON model config files, lifecycles, rule definitions before invocation

B. C++ Analysis Core (Built with CMake)
– Modules:
- Frontend: desugar integration for Java bytecode processing
- Call graph & CFG builder, alias and type analysis, taint‐tracking engine
- Model validator, origin tracing, exploitability rule evaluator
– Consumes:
- System JARs (Android platform types)
- Configuration JSON (sources, sinks, sanitizers, filters, lifecycles, rules)
- Generated models (from model generators)
– Produces raw analysis output (spec files, JSON traces, exit codes)

C. Model Generation Infrastructure
– Scripts and C++ model-generator modules that read templates and JSON config
– Emit per‐API or per‐pattern source/sink/sanitizer models into JSON for the core to consume

D. Post‐Processing & Presentation
– SAPP tool: reads raw specs, loads into a SQLite database, starts a web server
– Docusaurus website: static site generator for user docs, blogs, examples

E. Sample Application (for demos)
– A minimal Android app whose APK and source root serve as input to the analysis

##### Architectural Patterns & Design Principles
- Layered architecture:
1. Presentation/configuration (Python CLI, JSON files)
2. Orchestration (Python shim scripts)
3. Core business logic (C++ analysis modules)
4. Post‐processing & reporting (SAPP, web docs)
- Plugin/extension points: model generators and shims modules allow adding new source/sink rules without changing core
- Separation of concerns: build (CMake), runtime (Python + binary), documentation (Docusaurus), CI (GitHub Actions)

##### Technologies & Frameworks to Label
- Python 3 (CLI, shim, scripts)
- C++17 (analysis core, model/shim generators)
- CMake (build system)
- JSON (configuration, model definitions, output)
- Redex (bytecode transformation via desugar integration)
- SAPP (post‐processing)
- Docusaurus/React (website)
- Android SDK (system JARs, sample-app APK)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Python CLI & Shim
    subgraph "CLI & Python Shim"
        direction TB
        CLIShim["Python CLI & Shim"]:::python
        ShimPy["shim.py"]:::python
        PackagePy["package.py"]:::python
        ConfigPy["configuration.py"]:::python
        ExitPy["exit_codes.py"]:::python
    end

    %% C++ Analysis Core
    subgraph "C++ Analysis Core"
        direction TB
        CMakeLists["CMakeLists.txt"]:::cpp
        CMakeDir["cmake/"]:::cpp
        SourceDir["source/"]:::cpp
    end

    %% Model Generation Infrastructure
    subgraph "Model Generation Infrastructure"
        direction TB
        ModelModules["source/model-generator/"]:::cpp
        ModelConfigTemplates["configuration/model-generators/"]:::config
        ModelGenTests["source/tests/integration/json-model-generator/"]:::test
    end

    %% Configuration Artifacts
    Configuration["configuration/"]:::config

    %% Bytecode Desugaring
    Desugar["desugar/com/facebook/marianatrench/"]:::external

    %% Post-Processing & Presentation
    subgraph "Post-Processing & Presentation"
        direction TB
        SAPP["PostprocessTraces.cpp/.h"]:::cpp
        BrowsableResults["Web UI (SAPP)"]:::external
        Docusaurus["Docusaurus Site"]:::external
    end

    %% Sample Application
    SampleApp["Sample Android App"]:::external

    %% CI Pipelines
    subgraph "CI Pipelines"
        direction TB
        PublishPyPI["publish_pypi.yml"]:::script
        TestsCI["tests.yml"]:::script
        WebsiteCI["website.yml"]:::script
    end

    %% Supporting Scripts & Utilities
    subgraph "Supporting Scripts & Utilities"
        direction TB
        BuildStatic["build_static_binary.py"]:::script
        CMakeShimScript["cmake_shim.py"]:::script
        CompareModels["compare_models.py"]:::script
        ConvertJar["convert_jar_for_analysis.sh"]:::script
        ExploreModels["explore_models.py"]:::script
        SetupPy["setup.py"]:::script
        UpdateIntegration["update_expected_integration_test_outputs.sh"]:::script
    end

    %% Relationships
    SampleApp -->|"APK & source root input"| CLIShim
    Configuration -->|"load JSON configs"| CLIShim
    Configuration -->|"load JSON configs"| SourceDir
    ModelModules -->|"generate models"| SourceDir
    ModelConfigTemplates -->|"template inputs"| ModelModules
    ModelGenTests -->|"validate models"| ModelModules
    Desugar -->|"preprocess bytecode"| SourceDir
    CLIShim -->|"invoke binary, pass paths & configs"| SourceDir
    CMakeLists --> SourceDir
    CMakeDir --> SourceDir
    SourceDir -->|"raw JSON output"| SAPP
    SAPP -->|"serve processed results"| BrowsableResults
    BrowsableResults --> Docusaurus

    %% Click Events
    click ShimPy "https://github.com/facebook/mariana-trench/blob/main/shim/shim.py"
    click PackagePy "https://github.com/facebook/mariana-trench/blob/main/shim/package.py"
    click ConfigPy "https://github.com/facebook/mariana-trench/blob/main/shim/configuration.py"
    click ExitPy "https://github.com/facebook/mariana-trench/blob/main/shim/exit_codes.py"
    click CMakeLists "https://github.com/facebook/mariana-trench/blob/main/CMakeLists.txt"
    click CMakeDir "https://github.com/facebook/mariana-trench/tree/main/cmake/"
    click SourceDir "https://github.com/facebook/mariana-trench/tree/main/source/"
    click ModelModules "https://github.com/facebook/mariana-trench/tree/main/source/model-generator/"
    click ModelConfigTemplates "https://github.com/facebook/mariana-trench/tree/main/configuration/model-generators/"
    click ModelGenTests "https://github.com/facebook/mariana-trench/tree/main/source/tests/integration/json-model-generator/"
    click Configuration "https://github.com/facebook/mariana-trench/tree/main/configuration/"
    click Desugar "https://github.com/facebook/mariana-trench/tree/main/desugar/com/facebook/marianatrench/"
    click SAPP "https://github.com/facebook/mariana-trench/blob/main/source/PostprocessTraces.cpp"
    click SAPP "https://github.com/facebook/mariana-trench/blob/main/source/PostprocessTraces.h"
    click Docusaurus "https://github.com/facebook/mariana-trench/tree/main/documentation/website/"
    click SampleApp "https://github.com/facebook/mariana-trench/tree/main/documentation/sample-app/"
    click PublishPyPI "https://github.com/facebook/mariana-trench/blob/main/.github/workflows/publish_pypi.yml"
    click TestsCI "https://github.com/facebook/mariana-trench/blob/main/.github/workflows/tests.yml"
    click WebsiteCI "https://github.com/facebook/mariana-trench/blob/main/.github/workflows/website.yml"
    click BuildStatic "https://github.com/facebook/mariana-trench/blob/main/scripts/build_static_binary.py"
    click CMakeShimScript "https://github.com/facebook/mariana-trench/blob/main/scripts/cmake_shim.py"
    click CompareModels "https://github.com/facebook/mariana-trench/blob/main/scripts/compare_models.py"
    click ConvertJar "https://github.com/facebook/mariana-trench/blob/main/scripts/convert_jar_for_analysis.sh"
    click ExploreModels "https://github.com/facebook/mariana-trench/blob/main/scripts/explore_models.py"
    click SetupPy "https://github.com/facebook/mariana-trench/blob/main/scripts/setup.py"
    click UpdateIntegration "https://github.com/facebook/mariana-trench/blob/main/scripts/update_expected_integration_test_outputs.sh"

    %% Styles
    classDef python fill:#e8f4fc,stroke:#0366d6,color:#0366d6;
    classDef cpp fill:#e6ffed,stroke:#22863a,color:#22863a;
    classDef config fill:#fff5b1,stroke:#d1a21e,color:#d1a21e;
    classDef external fill:#f0f0f0,stroke:#6a737d,color:#6a737d;
    classDef script fill:#faebd7,stroke:#b45f06,color:#b45f06;
    classDef test fill:#ffeef0,stroke:#cb2431,color:#cb2431;
```
