How facebook/mariana-trench works
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)