Sandroid Framework
Sandroid provides a powerful Android sandbox framework that enables automated analysis of Android applications. It combines both static and dynamic techniques to help security researchers, forensic analysts, and malware analysts better understand how apps behave in a controlled environment.
By using this framework, you can:
- Extract forensic artifacts generated by Android apps and identify which app created them.
- Analyze malware behavior through automated static and dynamic analysis.
- Uncover security vulnerabilities and misconfigurations in Android applications.
- Gain deeper insights into app behavior without manual reverse engineering.
The framework is designed to simplify the process of forensic investigations, mobile threat detection, and security testing by providing a streamlined, automated environment for analysis. Whether you're investigating malicious apps, assessing security flaws, or collecting digital evidence, this solution helps you quickly identify and understand what happens inside Android applications.
Requirements
- Python 3.12 or 3.13 (Python 3.10/3.11 are no longer supported as of 2.1).
- Android SDK platform-tools (
adb) and the Android Emulator (e.g. via Android Studio).sandroid-config initauto-detects both. - A rooted Android emulator (AVD). Sandroid needs root on the device (it runs
adb root, pushes and startsfrida-server, and sets SELinux to permissive withsetenforce 0itself). Two setups are known to work:- a Google APIs system image (
google_apis, notgoogle_apis_playstore) —adb rootworks out of the box; or - a Google Play system image rooted with rootAVD (Magisk) plus the Magisk
adb_rootmodule, so thatadbditself runs as root. This is how the Sandroid team's own AVDs are set up.
- a Google APIs system image (
- AVD snapshots must be enabled — the record/play workflow and the Snapshots tab rely on them. Do not start the emulator with
-no-snapshot; if you do not want the emulator to overwrite its quick-boot snapshot on exit use-no-snapshot-save(or simply start it viasandroid-config avd start). - Physical devices are only partially supported: they must be rooted, and everything that relies on the emulator (snapshots, emulator-console network capture/degradation,
-no-snapshot-*boot modes) is unavailable. - Linux and macOS are the primary platforms; Windows works best via WSL2.
Quick Start
# Install from PyPI
pip install sandroid
# Initialize configuration (detects the Android SDK and lets you pick/create an AVD)
sandroid-config init
# Start your AVD (keeps snapshots enabled)
sandroid-config avd start
# Launch the interactive TUI
sandroid
See SETUP.md for all installation possibilities.
Interactive TUI
Sandroid's default interface is an interactive terminal UI (Textual). It consists of a glance band at the top (device, frida-server, proxy and spotlight state at a glance), an activity log, a row of always-on tool tabs, and an optional AI Chat dock:
| Tool tab | What it does |
|---|---|
| Spotlight | The app under investigation: start / resume (Enter), attach (A), start paused (P), restart (R), kill (K), clear (X), and toggle the Frida bypass categories 1–5 (SSL, Root, Frida, Debug, Integrity). |
| Network | Two sub-tabs: Mitmproxy (embedded mitmweb, device/app proxies, CA injection — see below) and friTap (TLS key extraction status + live log tail). |
| Snapshots | AVD snapshot list: create (c), load (l), delete (d), assign to a slot (a). Globally, 0 opens the tab, 1–8 (pressed twice) load a slot and Ctrl+1–Ctrl+8 save into a slot (8 slots per AVD). Ctrl+digit only reaches Sandroid in terminals with the kitty keyboard protocol (kitty, WezTerm, foot, Ghostty, recent iTerm2); in Terminal.app, GNOME Terminal/VTE or tmux press S and then the slot digit instead. |
| Files | Three sub-tabs: Monitor (live filesystem events), Watchlist (Spotlight Files: pull/diff selected files) and Diffs (Record → Play run history, see below). |
Navigation: Ctrl+B focuses the tool tabs, Shift+←/→ cycles tabs/sub-tabs, Shift+↑/↓ moves between tab levels. ? opens the help & keybinding editor (every action grouped by category; rebind any key with live conflict detection, persisted to tui.keybindings), Ctrl+Shift+P opens the command palette, Ctrl+Y toggles the AI Chat dock, D switches devices and q quits. Common operations are a single keypress (e.g. y proxy settings, w network capture, o file monitor, f frida-server, s screenshot, n install APK, Ctrl+P toggle SSL unpinning).
The 2.0 "views" (Forensic / Malware / Security, switched with
TAB) are gone — all actions live in one flat catalog. Fully non-interactive runs are available via--headless.
Record → Play and run history
From any panel, r records your interactions with the device (Esc/Enter in the recording window stops and saves) and p plays them back, landing on Files → Diffs: Sandroid reverts the emulator to the snapshot taken before recording, replays the recording, measures background noise with a dry run of the same duration (unless --avoid-strong-noise-filter) and diffs the filesystem, so only artifacts caused by your action remain (changed / new / deleted files with inline diffs, processes, sockets, network). Every Play is stored as a self-contained run bundle under <results_path>/runs/<run_id>/ (run.json manifest, recording.txt, the raw pull tree) and listed in the Diffs tab's run history, scoped to the active device. Runs are never deleted automatically.
File monitor (kprobe)
The Monitor sub-tab (o) streams filesystem events from the device. The default backend (tui.monitor_backend = "kprobe") uses kernel tracefs kprobes: kernel-verified per-PID attribution, following the whole child-process tree, path-scoped capture, and no binary pushed to the device. On kernels without the required support it falls back to the fsmon binary automatically (or set monitor_backend = "fsmon").
Usage
Usage: sandroid [OPTIONS]
Sandroid: Extract forensic and malware artifacts from Android Virtual Devices.
Core Options:
-c, --config PATH Configuration file path
-e, --environment TEXT Environment name (development, testing, production)
-f, --file PATH Save output to the specified file
-ll, --loglevel [DEBUG|INFO|WARNING|ERROR|CRITICAL]
Set the log level
--fresh Start as if running for the first time
--version Show the version and exit
Analysis Options:
-n, --number INTEGER Run action n times (minimum 2)
--avoid-strong-noise-filter Disable dry run and intra-file noise detection
--network Capture traffic and show connections
-d, --show-deleted Reveal deleted files via full filesystem checks
--no-processes Do not monitor active processes
--sockets Monitor listening sockets
--screenshot INTERVAL Take a screenshot each INTERVAL seconds
--trigdroid PACKAGE_NAME Execute malware triggers for PACKAGE_NAME
--hash Create MD5 hashes of changed and new files
--apk List all APKs and their hashes
--degrade-network Simulate UMTS/3G network conditions
--whitelist FILE Exclude paths from outputs
Headless Mode:
--headless Run without interactive UI
--batch CONFIG_FILE Batch processing config (JSON)
--mode [forensic|malware|security|network]
Analysis mode for headless operation (default: malware)
Dexray & Advanced Tools:
--dexray PACKAGE Start Dexray-Intercept monitoring for PACKAGE
--dexray-hooks HOOKS Comma-separated hook groups (aes,web,socket,filesystem,database,dex,java_dex)
--dexray-fritap Enable FriTap during dexray monitoring
--fritap PACKAGE Start FriTap SSL/TLS key extraction for PACKAGE
--fridump PACKAGE Dump memory of PACKAGE using Fridump
--duration SECONDS Network capture duration (headless, default: 60)
--with-fritap PACKAGE Combine network capture with FriTap keylog
Device Management:
--proxy IP:PORT Set HTTP proxy on device
--proxy-clear Clear HTTP proxy settings
--install-apk PATH Install APK on device
--import-action PATH Replay a run bundle's recording.txt headless
--device-settings FILE Apply device settings from JSON file
--preset CODE Apply country preset (e.g., de, us, ru, cn)
Output & Debugging:
--report Generate PDF report
--debug Enable debug/verbose mode
--log Show log messages in terminal
Note:
--modeonly affects headless runs. Removed since 2.0:-i/--interactive(legacy Rich menu),--ai(Gemini video summary) and the TUI view switch (--view). Results of a session are written to./results/<timestamp>/(sandroid.json,sandroid.log, per-device raw data and screenshots).
Network Interception & Bypass
Sandroid can route a target app's traffic through an embedded mitmproxy instance and defeat the common defences that get in the way of inspection. Everything lives in Network → Mitmproxy; each step is its own keystroke, so none has a surprising side effect on the others:
| Key | Action |
|---|---|
Enter |
start / stop mitmweb (proxy on 127.0.0.1:8080, web UI on http://127.0.0.1:8081/); start does not touch the device unless mitmproxy.auto_device_proxy = true |
Ctrl+D |
toggle the Device Proxy (global http_proxy setting → our mitmproxy) |
Ctrl+N |
install the mitmproxy CA into the device's system trust store |
y |
Proxy Settings modal: Device Proxy, App Proxies and CA in one place |
Ctrl+R |
restart mitmweb and re-apply device + app proxies |
Ctrl+O / Ctrl+A |
open the web UI / manage addons |
Requires mitmweb on PATH (pip install mitmproxy).
Ports come from [mitmproxy] in the config (proxy_port, web_port). mitmproxy listens on 127.0.0.1 only (mitmproxy.listen_host), so intercepted traffic is not exposed to the LAN. That is enough for emulators (the device reaches the host loopback as 10.0.2.2) and for USB devices routed via adb reverse (Proxy Settings, y). Only a physical device on Wi-Fi needs listen_host = "0.0.0.0". Starting mitmproxy leaves the device alone by default; set mitmproxy.auto_device_proxy = true to also point the Device Proxy at it on Enter. The Device Proxy Sandroid set is cleared when mitmproxy stops and when Sandroid exits.
App Proxies. Besides the global device proxy, individual apps can be routed through a proxy per UID: Sandroid pushes a small gost redirector to the device and adds iptables REDIRECT rules for that app only — either to Sandroid's mitmproxy or to an external proxy such as Burp or ZAP. QUIC (UDP/443) is blocked for proxied apps by default (focus.block_quic) so they fall back to interceptable TCP/TLS. On emulators the host IP is detected automatically; an adb reverse fallback is offered when the device cannot reach the host.
CA certificate injection. Sandroid auto-detects the host CA certificate from mitmproxy (~/.mitmproxy/mitmproxy-ca-cert.pem), HTTP Toolkit, or Burp Suite (a custom path is also accepted) and injects it into the device's system trust store. On Android 14+ (API ≥ 34) it bind-mounts the certificate into the Conscrypt APEX trust store; on Android 10–13 it injects into the Zygote mount namespace (after confirmation, since this restarts Zygote). It also writes the Chrome command-line flags needed to bypass Certificate Transparency enforcement.
Certificate-pinning & detection bypass — EXPERIMENTAL. Sandroid ships a Frida-based bypass suite with five categories — SSL unpinning, Root, Frida, Debug and Integrity (PairIP / licensing / attestation gates) detection — toggled with 1–5 in the Spotlight tab (Ctrl+P is a global shortcut for SSL unpinning). SSL unpinning is tiered: Java (SSLContext, OkHttp CertificatePinner, Conscrypt, WebView, TrustKit, Certificate Transparency), native BoringSSL, Chromium/cronet BoringSSL (including stripped, symbol-less builds), and mbedTLS / Meta Network Stack, with early-init hooks and a spawn-reliability ladder for hardened apps. All categories live in a single resident, flag-gated Frida script, so toggling one is instant and never leaves the app momentarily un-hooked. These bypasses are under active development: expect individual apps to defeat them, and verify results independently.
These bypasses require a rooted AVD with
frida-serverrunning and a target app attached or spawned first.
Custom mitmproxy addons. You can load your own mitmproxy addons alongside Sandroid's built-in traffic logger. An addon is a standard mitmproxy script — a Python file that defines event hooks like def response(flow): ..., optionally a class exposing addons = [...]. Sandroid scans two drop-in folders for top-level *.py files (an examples/ subdirectory is ignored):
~/.config/sandroid/mitm_addons/— per-user; created on first run with aREADME.mdand anexamples/example_logger.pytemplate../mitm_addons/in the current working directory — handy for shipping addons together with a project.
To enable addons, press Ctrl+A in the Mitmproxy sub-tab for the addon manager — a checklist of every discovered addon. Tick the ones to load (or type a custom path directly); the selection is saved to your config under mitmproxy.enabled_addons and restored on the next run. A minimal addon looks like this:
# ~/.config/sandroid/mitm_addons/log_urls.py
def response(flow):
print(f"[my-addon] {flow.request.pretty_url} -> {flow.response.status_code}")
Editing an already-loaded addon file hot-reloads it live — no restart, no dropped traffic. Changing which addons are enabled restarts mitmweb (which briefly resets the live flow counters).
Addons run as arbitrary, unsandboxed Python with the proxy process's privileges. Only enable scripts you trust.
With its modular architecture, Sandroid integrates multiple companion tools to cover a wide range of analysis capabilities — from cryptographic key extraction to TLS interception and network traffic decryption.
Related Projects within the Sandroid Sandbox
Sandroid integrates and builds upon several companion projects that extend its capabilities. These tools are developed under the same sandbox ecosystem and are designed to work together for comprehensive Android analysis:
| Project | Description | Status |
|---|---|---|
| TrigDroid | Dynamic tracing and Frida-based interception for Android apps, enabling enhanced runtime analysis. | ✅ Integrated |
| Dexray Insight | A static analysis tool focused on DEX files, helping to uncover cryptographic usage, API patterns, and potential vulnerabilities. | ✅ Integrated |
| Dexray Intercept | Dynamic hooking framework for intercepting sensitive data flows, network traffic, and runtime behaviors in Android apps. | ✅ Integrated |
| friTap | TLS key extraction and decrypted traffic interception for Android, enabling advanced network analysis in sandboxed environments. | ✅ Integrated |
AI Chat (EXPERIMENTAL)
Sandroid includes an LLM-backed chat assistant that can drive the same device and analysis actions as the TUI, talking to any OpenAI-compatible chat-completions endpoint you configure. The feature is experimental: tool behaviour, prompts and configuration may change between minor releases.
Data egress. Everything the assistant sees — your prompts, the live device/session context Sandroid attaches to every turn, and the output of the tools it calls (file listings, file contents, captured flows, package data, …) — is sent to the configured endpoint. When analysing sensitive evidence or customer data, use a local endpoint (e.g. Ollama, LM Studio, llama.cpp server or vLLM) instead of a cloud provider.
Configuration. Chat is inert until you set three connection fields — base_url, api_key, and model. Set the API key via an environment variable rather than the config file:
# recommended: secrets via environment variables
export SANDROID_AI__API_KEY="sk-..."
# ~/.config/sandroid/sandroid.toml -- example for a local Ollama instance
[ai]
base_url = "http://localhost:11434/v1"
model = "qwen2.5:14b" # any tool-calling capable model you have pulled
# api_key: Ollama ignores it, but Sandroid requires a non-empty value -> export SANDROID_AI__API_KEY=ollama
SANDROID_AI__BASE_URL and SANDROID_AI__MODEL work as environment variables as well. A key written into the config file is stored in plaintext (sandroid-config show only redacts it for display).
Opening it. Press Ctrl+Y to open the Chat dock (a non-modal panel; the binding is rebindable like every other action — see ?).
What it can do. Around 76 native tools spanning app/process lifecycle control, device/network/flow queries, certificate and environment control, host↔device file transfer, file monitoring and record/replay — plus two subagent tools that spawn read-only or (with approval) fully privileged background investigations, and anything exposed by MCP servers you configure under [mcp]. Host file access is confined to ai.data_share_path (default ~/Sandroid/ai_share/), the current session's results directories and any ai.extra_host_paths.
Safety. Every tool call passes a permission gate — read-only calls run automatically, state-changing calls prompt for approval (allow once / always / never, persisted) — and a resource arbiter keeps the assistant and any concurrent subtasks from colliding on shared device resources such as the proxy, mitmproxy, frida-server, and snapshots. Still: review what you approve; the model can be wrong or manipulated by content it reads (e.g. strings inside an analysed app).
The bundled
sandroid-dummyMCP server is a demo only: everything it returns (e.g. its sample threat-intel lookup) is fabricated data, not a real result.
Ground Truth APK
The framework also includes a custom Android app for testing and calibration. This app is designed to create specific forensic artefacts with pinpoint accuracy at the user's command, while being as minimal as possible to avoid unintended artefacts. To use it, simply install it on the emulator using Sandroid's built-in APK installer and open the app.
Supported Artefacts
The app shows ten buttons; nine of them create an artefact (button label in quotes):
- "Create a new file" –
files/file_<n>.txt - "Add Database Entry" – row in
GroundTruth.db - "Delete Database Entry" – row removed from
GroundTruth.db - "Update Database Entry" – row updated in
GroundTruth.db - "Send 42 Bytes to 'fkie.fraunhofer.de'" – 42 bytes over TCP to
fkie.fraunhofer.de:443 - "Start process 'yes'" – a running
yesprocess - "Add XML Entry" – entry in
GroundTruth.xml - "Delete XML Entry" – entry removed from
GroundTruth.xml - "Update XML Entry" – entry updated in
GroundTruth.xml
The tenth button, "Download APK", is a placeholder and currently does nothing (no artefact). Simply press the corresponding button to generate the artefact.
Some considerations
- Values added to the XML file and the Database will be the current unix time on the emulator. It can deviate from the actual time but will be automatically be highlighted in the output.
- The first time the application is launched after installation, the XML file and database will be initialised, and Android will create a profile for the application, so it is recommended that you open the application first, and only then start any analysis.
- The XML and database files are called
GroundTruth.xmlandGroundTruth.dbrespectively and are stored in the applications directory.GroundTruth.dbis only created by the first database button, and SQLite keeps fresh writes inGroundTruth.db-wal(with-shm) until a checkpoint, so expect those files in the diff as well.
Documentation
- SETUP.md - Complete setup guide (requirements, AVD rooting, configuration)
- MIGRATION.md - Upgrading from older versions
- CHANGELOG.md - Detailed release notes and version history
- Online documentation - Sphinx docs (built from
docs/)
Installation
pip install sandroid # core
pip install "sandroid[full]" # + optional static-analysis extras (dexray-insight, androguard)
sandroid-config init
sandroid --help
sandroid # start the interactive TUI (default)
Docker images (
docker/dockerfile) are provided on a best-effort basis and are not tested in CI; the emulator always runs on the host. See docs/advanced/docker_deployment.rst.
Configuration Management
The installation includes a configuration system (TOML by default):
# Initialize configuration
sandroid-config init
# View configuration
sandroid-config show
# Modify settings
sandroid-config set -k analysis.capture_network -v true
sandroid-config set -k emulator.device_name -v "Pixel_8_Pro_API_34"
# Validate configuration
sandroid-config validate
Configuration files (sandroid.toml, also .yaml/.yml/.json) are discovered in this order — sandroid-config paths prints the exact list for your system:
./sandroid.toml(current directory, highest priority)~/.config/sandroid/sandroid.toml(user config)- the platform config directory (e.g.
~/Library/Application Support/sandroid/on macOS) - Environment variables with the
SANDROID_prefix override file values; nested keys use a double underscore, e.g.SANDROID_AI__MODEL.
sandroid-config Subcommands
# AVD Management
sandroid-config avd list # List available AVDs
sandroid-config avd start # Start an AVD (interactive or --avd-name, --boot-mode)
sandroid-config avd stop # Stop running AVDs
sandroid-config avd rename # Rename an AVD
sandroid-config avd create # Create a new AVD
# TUI Theme
sandroid-config theme list # List available themes
sandroid-config theme set <id> # Set TUI theme
sandroid-config theme show # Show current theme
# IOC Management (for MVT forensic scanning)
sandroid-config ioc show # Show IOC configuration
sandroid-config ioc set-path <p> # Set IOC file/directory path
sandroid-config ioc set-url <url> # Set IOC download URL
sandroid-config ioc download # Download IOC files
sandroid-config ioc validate # Validate IOC files
# Device Management
sandroid-config devices # List connected devices
Screenshots
Welcome screen
Spawning a target app for instrumentation
Attaching to a running app
Contributing
We welcome contributions to Sandroid! Before contributing:
-
Review Coding Guidelines: Please read our comprehensive CODING_GUIDELINES.md which covers:
- Python code style standards (PEP 8 compliance)
- Architecture patterns specific to Sandroid
- Testing requirements and best practices
- Security considerations for forensic tools
- Documentation standards
- The release process
-
Development Setup:
git clone git@github.com:fkie-cad/Sandroid_core.git cd Sandroid_core git checkout dev pip install -e ".[dev,full]" pytest # ~1100 tests; never touch a real device (see tests/conftest.py)
-
Submit Changes: Fork the repository, create a feature branch off
dev, ensure tests andruff check .pass, and submit a pull request againstdev.
For detailed contribution instructions, see docs/development/contributing.rst.
Contact
Developed and maintained by Fraunhofer FKIE.
For inquiries or collaboration, please contact:
Metadata
Release files for Sandroid 2.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sandroid-2.1.0.tar.gz | 1.5 MB | With provenance | Details for sandroid-2.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sandroid-2.1.0-py3-none-any.whl | Python 3 | none | any | Details for sandroid-2.1.0-py3-none-any.whl |
Total release size: 3.2 MB
Release files / sandroid-2.1.0.tar.gz
| Download URL | sandroid-2.1.0.tar.gz |
|---|---|
| Size | 1.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
31be798c6c08be9976e52926dc38c810ebd740dfa405a6493812a2b8cf844497
|
|
BLAKE2b-256 checksum How to use checksums |
d218f6a18ea46a251131e70ac7cff908f8572879b8de9de18ff2e4f137ab2bba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / sandroid-2.1.0-py3-none-any.whl
| Download URL | sandroid-2.1.0-py3-none-any.whl |
|---|---|
| Size | 1.7 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c7ab01ea0205783b719bfc026f79deaf01fc3984375b2381b1547c56fd280c9c
|
|
BLAKE2b-256 checksum How to use checksums |
1bafc5906a30b37cb4aa2bf8461bb15b71bd0ac4e74aa0288fee6bdf0a3683cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for Sandroid 2.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for sandroid-2.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.