Changelog
Changelog
All notable changes to the Sandroid project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[2.1.0] - 2026-11-17
Sandroid 2.1 redesigns the TUI around always-on tool tabs, adds an mitmproxy-based network interception stack with per-app proxies and CA injection, a tiered Frida bypass suite, a kprobe filesystem monitor, a rewritten analysis engine with persistent run history, and an experimental AI Chat assistant.
⚠️ Breaking Changes
Python 3.12 or newer is required (3.12 and 3.13 are tested in CI); Python 3.10/3.11 support was dropped.
Legacy Rich interactive mode removed:
sandroid -i/--interactiveno longer exist — use the Textual TUI (sandroid) or--headless.--airemoved: the Gemini-based video summarisation feature and its API-key setting are gone, superseded by the new (experimental) AI Chat.TUI views removed: the Forensic / Malware / Security views (
TAB) were replaced by a single flat action catalog;--viewandanalysis.default_viewno longer have any effect in the TUI (--modefor--headlessis unchanged).TUI layout changed: the
Ctrl+Bbottom panel was replaced by always-on tool tabs (Spotlight / Network / Snapshots / Files) withShift+Arrownavigation; Record/Play results live in Files → Diffs (r/pwork from every panel). Global1–8must be pressed twice to load a snapshot slot; Snapshots refresh isCtrl+R, Watchlist pull isu/U.The internal
ActionQ/DataGatheranalysis pipeline was replaced byAnalysisEngine; third-party code importing those internals must be updated.The on-device proxy redirector changed from
ipt2sockstogost.
Added
TUI
Glance band: permanent, boxed status strip (device, frida-server, mitmproxy engine, device/app proxies, spotlight) derived from live device state.
Always-on tool tabs: Spotlight, Network (Mitmproxy + friTap sub-tabs), Snapshots and Files (Monitor / Watchlist / Diffs sub-tabs), unified under
Shift+Arrownavigation.Help & keybinding editor (
?): browse every action by category and rebind any key (incl.Ctrlcombos) with live conflict detection; persisted totui.keybindings.Snapshots tab with an 8-slot snapshot memory per AVD (
1–8load,Ctrl+1–Ctrl+8save,aassign).friTap panel with status header and live log tail.
Startup device picker and real-time device shutdown/reconnect detection (
adb host:track-devices).Monitor settings tab (kprobe/fsmon source, multiple paths, per-category event visibility).
Theming of the chat/tool panels and the chat transcript; compact form widgets.
Analysis engine & run history
AnalysisEnginereplaces the ActionQ/DataGather pipeline (samesandroid.jsonkeys).Run history / run bundles: every Play is stored as a self-contained bundle (
<results_path>/runs/<run_id>/withrun.json,recording.txt, raw pull tree), listed in Files → Diffs, scoped per device; Record/Play UX fixes and a redesigned Diffs layout.Unified Files tab: fsmon/kprobe monitor stream, Spotlight-Files watchlist and Play diffing in one place, with grouped, de-duplicated event display.
kprobe filesystem monitor (
tui.monitor_backend = "kprobe", default): kernel tracefs kprobes with per-process/child-tree attribution and path-scoped capture, no binary pushed to the device; automatic fallback tofsmon.Replay settle time (
analysis.replay_settle_seconds, default 8 s, also in Settings → Analysis): every replay’s capture window stays open that much longer so slow network responses and late writes land in the run; the dry run waits the same extra time, so noise subtraction still compares equal windows.Network reset after snapshot loads (
analysis.network_reset_after_snapshot,"airplane"(default) |"svc"|"off", also in Settings → Analysis): after every snapshot load that precedes a replay or the dry run, the device network is briefly cycled and Sandroid waits for a default network, so connections restored from the snapshot (whose emulator NAT state is gone) fail at once and the app reconnects. Recordings started with the app already open now replay with working network instead of “Cannot connect … timeout”. With the reset off, starting a recording in the open spotlight app shows a warning. The mode is recorded inrun_settings.mitmproxy.auto_device_proxyis editable in Settings → Network & Frida.
Network interception
mitmproxy integration (Network → Mitmproxy): start/stop
mitmweb, live flow and TLS-failure tail, flow log.Device Proxy and per-app App Proxies in one Proxy Settings modal (
y); App Proxies route individual apps (by UID) through Sandroid’s mitmproxy or an external proxy (Burp/ZAP) via an on-devicegostredirector; optional QUIC (UDP/443) blocking; emulator-aware host IP detection, device-reachability probe andadb reversefallback.CA certificate injection into the system trust store (APEX bind-mount on Android 14+, Zygote mount namespace on Android 10–13, with confirmation before restarting Zygote); CA status reported on start.
Custom mitmproxy addons from
~/.config/sandroid/mitm_addons/and./mitm_addons/, managed withCtrl+A, hot-reloaded on edit.
Bypass suite (EXPERIMENTAL)
Flag-gated, single resident Frida script with SSL, Root, Frida, Debug and new Integrity (PairIP / licensing / attestation) categories; instant toggles without un-hooked gaps; auto-reload and package validation.
SSL unpinning tiers: Java/Conscrypt/OkHttp/WebView/TrustKit/CT, native BoringSSL, Chromium/cronet BoringSSL (incl. stripped, symbol-less libraries), mbedTLS / Meta Network Stack; pre-init constructor interposition and a spawn-reliability ladder for hardened apps.
AI Chat (EXPERIMENTAL)
sandroid.ai: streaming OpenAI-compatible client, tool-calling loop, MCP client bridge, concurrent subtasks with a device-resource arbiter.Chat dock (
Ctrl+Y) with markdown rendering, ambient device/session context on every turn and ~76 tools (app/process lifecycle, device/network/flow queries, certificate/environment control, file transfer with host-path confinement, file monitor, record/replay).Per-tool permission gate (allow once / always / never, persisted).
New
[ai]and[mcp]config sections with secret redaction insandroid-config show. Note: prompts, device context and tool output are sent to the configured endpoint — prefer a local endpoint (e.g. Ollama) and set the key viaSANDROID_AI__API_KEY.
Evidence documentation & reporting
SHA-256 alongside MD5 for artifacts and APKs (new JSON keys; existing keys unchanged), keyed by full device path.
Run Metadatain every results JSON: Sandroid/frida/friTap/dexray versions, host, device serial, AVD, Android version/API level, build fingerprint, ISO-8601 start/end timestamps with timezone, and the (secret-free) analysis settings.Evidence manifest:
manifest.json+SHA256SUMSover the whole result folder (verifiable withsha256sum -c/shasum -a 256 -c); its own hash is logged.sandroid --report-from <dir>verifies the manifest and (re)generates the PDF for an existing result folder;Pin Files → Diffs does the same for a run;report.generate_pdfcreates it after every Play. Verification runs first: on a mismatch nothing is written (exit code 2). Existing files are never overwritten: the PDF is written asSandroid_Forensic_Report_regenerated_<UTC>.pdfand recorded inSHA256SUMS.addendum-<UTC>(checked together withSHA256SUMS) plus a line insandroid_report.log; the originalSHA256SUMSstays unchanged.PDF reports never fail on long diffs: diffs continue over several table rows, lines over 400 characters and diffs over 200 lines are shortened with a visible note, and a section that still cannot be laid out is replaced by a note instead of aborting the report.
PDF title page with run metadata, readable wrapping tables, deterministic timeline.
Device selection & safety defaults
Emulator memory guard: the qemu process of the active emulator is watched; above
emulator.max_host_memory_gb(default 10 GB) it is shut down (memory_guard_action = "warn"only logs). Sandroid warns when an emulator was started without-feature -Vulkan.--serial/-s,$ANDROID_SERIALandemulator.serialselect the device; every adb call is pinned to it.AI Chat is off unless configured, accepts only local endpoints unless
ai.allow_remote = true, shows a data-egress notice naming endpoint and model, and no MCP server is enabled by default (the bundled demo server returns clearly marked fake data only).All bypass categories are labelled experimental and off by default.
Tooling
Hermetic test suite (~1300 tests);
tests/conftest.pyblocks all real adb/emulator/frida access.CI runs ruff and pytest on Python 3.12 and 3.13 for
mainanddev, and checks the built distribution.Releases are tagged
v<version>with notes taken from this changelog.
Changed
friTap 2.0 compatibility; tested with friTap 2.6.7, AndroidFridaManager 2.0.7 (verified frida-server downloads), dexray-intercept 1.0.1.9, objection 1.12.5, mvt 2026.11, frida 17.26.
Dependencies have upper bounds for fast-moving packages;
mcp,mitmproxy,androguardandpsutilare core dependencies (.[ai]is kept as an empty alias).Package metadata now states the actual license (GPL-3.0).
Simplified app picker (system apps toggle on
Ctrl+S).Spotlight header self-heals a stale “paused” state against the live process.
Configuration is saved to
~/.config/sandroid/again instead of the platformdirs location.ABX (binary XML) files are decoded in-process instead of shelling out.
Documentation brought up to date (requirements, rooted-AVD setup, TOML configuration, new features).
Docker image installs Sandroid from
pyproject.toml(best effort, not tested in CI).
Fixed
frida-server start failures are reported honestly instead of always “started”; clean frida install prompt and Java bridge restored on frida 17.
CA injection on Android 10–13; mitmproxy start/stop no longer deadlocks the TUI when triggered from AI Chat;
start_mitmproxycan retry on another port.Glance band never updating from panels; tab-bar visibility; startup logo wobble.
Shared-global ADB serial race between devices; zombie retries capped;
DeviceManagerProtocoldrift.kprobe backend: off-thread setup, path-mode scoping, preflight self-check hang, noisy teardown warnings.
ADB_PATHis quoted when building shell commands (paths with spaces, Windows).ChangedFiles
.xmlbranch reuses the joined pull paths.Intra-file diffs restored: the first pull after the action was always empty, so changed SQLite databases and XML/ABX files showed “Not enough data for intra file analysis” instead of row/attribute diffs.
Network results: capture files are located on disk (the last capture was skipped with the noise filter off or N=1), TCP/UDP targets and IPv6 are reported with their DNS names, and a missing noise capture no longer wipes the result.
Record→Play from the TUI now runs the same gatherers as the CLI (processes, sockets, network per
[analysis]settings) and writes the full results JSON; processes/sockets polling stops with the action.Snapshot loads that fail abort the run; the guest clock is resynced to the host after every snapshot load (it drifted minutes behind).
Noise: ART profiles,
package-dex-usage,monotonic_clock.xml, battery history are always filtered; the dry run also subtracts deleted files.Artifact hashes are computed over the full pull tree (they were empty) and split APKs are hashed per part.
adb root+setenforce 0are applied on every path that needs them (--install-apk,--dexray,--fritap, …);--install-apkno longer prints “too many values to unpack”.The TUI starts without the AI dependencies; the forensic APK manager no longer crashes on a missing
WarningModal;features/screenshot.pyimports cleanly; several silently broken imports fixed; importing Sandroid never parsessys.argv.Headless: the CLI configuration is kept (wrong device name in reports), forensic mode forwards
--networkand no longer needs a package.TUI results are stored in one place under
paths.results_path(previously split between the CWD and the run bundle); quitting no longer hangs on leftover helper threads.PDF report: logo shipped as package data, no crash without
RAW_RESULTS_PATH, no empty file-name rows, no ANSI escape codes in PDF or JSON; the screenshot grid no longer converts/deletes the original PNGs.friTap: spawned targets are resumed (Android killed them after 10 s), hooks of dead jobs are unregistered, the panel shows when capturing stopped, and
fritap_output.jsonis written on close.dexray-intercept: fixed a deadlock during script load (“TransportError … timeout”) and stop not stopping the job.
objection command lines fixed for objection 1.12;
frida.server_auto_startis honoured; frida-server download errors (offline, rate limit, digest mismatch) are explained; MVT IOC download fallback fixed;mitmwebis found next to the Python interpreter.AI Chat: tools from external MCP servers and evidence deletion always require confirmation; the API key is never written to logs, results or the config file from the environment.
json_encoderno longer recurses on duck-typed objects.Every Sandroid-launched emulator (incl.
sandroid-config avd start, headless) disables guest Vulkan: SwiftShader Vulkan leaked host memory on each snapshot load, growing qemu to tens of GB over a session.System noise filter: well-known Android/GMS/Play background files (package-restrictions, netstats, usagestats, Wellbeing, Gboard, clearcut, …) are hidden from Changed/New/Deleted Files after the dry-run subtraction; the analysed app’s files are never filtered and every hidden path is listed under
Other Data → Filtered Noise(analysis.system_noise_filter,noise_patterns,protected_packages).XML/ABX diffs match elements by key (
name/key/id/…) instead of position, so additions, updates and deletions are reported as such ([ADDED]/[UPDATED]/[DELETED]).Network results list every DNS name seen for an IP plus the TLS SNI; IPv6 attempts without a reply are labelled as such.
PDF: long diffs (e.g. BLOB rows) are split across rows and capped instead of raising a ReportLab
LayoutError; a failing section degrades on its own.Headless prints a short summary instead of the full JSON, exits non-zero (3) when a requested report/manifest could not be written, announces each action window with a countdown;
--import-actionreplays a run bundle’srecording.txt.TUI: no more
NoActiveAppErrorcrash (and lost results) on the second recording of a session; results are persisted even if the UI fails; replays can be cancelled and are stopped on quit; Enter on a focused Cancel/Discard button no longer starts playback;Escnever opens Quit; stale frida device handles are reset after snapshot loads.dexray-intercept from the TUI no longer stalls for minutes, resumes its spawned app and removes its temporary snapshot; the hook modal only changes groups the user toggled; failure reasons are shown.
frida-server auto-start (
frida.server_auto_start) works at TUI startup, on device change and in headless--dexray/--fritap; stalefrida-helper-*.dexfiles are removed before a server (re)start.friTap stop completes with one keypress and finalizes the keylog and
fritap_output.jsoneven when the agent unload blocks.Network noise by volume: a destination also seen in the dry run is only subtracted when its traffic is comparable to the background (3× + floor on bytes/packets/connections); otherwise it is reported with an “also seen in background” note. Subtracted destinations and DNS names are listed under
Filtered Noise. Payload sizes come from IP/UDP length fields.Files and directories with spaces (
Session Storage,Web Data, …) are pulled correctly and no longer truncated by thelsparser; alladb pull/pushpaths are quoted.Device selection is strict: an explicitly requested serial (
--serial,ANDROID_SERIAL,emulator.serial) that is not connected is an error (exit 1) in headless/batch modes — no evidence files are written and Frida never falls back to another device; every adb call keeps-sacross brief device drop-outs;Run Metadataonly records a device name confirmed by the device.Headless runs follow the
[analysis]configuration (network, processes, dry run, number of runs) andRun Metadatarecords the settings actually used.mitmproxy: the device-reachability probe waits for the device to settle after the Zygote restart of CA injection and re-probes automatically; the CA status recognises an existing injection by fingerprint.
friTap no longer crashes the app on re-attach: attach mode refuses a process that already carried a friTap/Frida agent (restart the app or use spawn mode) and re-resolves a stale spotlight PID. When the target dies, friTap stops itself, finalizes its outputs and clears the PID. Each session writes its own
fritap_keylog_<timestamp>.log,fritap_output_<timestamp>.jsonandfritap_capture_<timestamp>_1.pcap(the capture now stops with friTap). A previous session’s detach no longer marks a new spawn as “target process gone”, and the Spotlight shows the PID of a process re-spawned by friTap or dexray.mitmproxy listens on
127.0.0.1by default (mitmproxy.listen_host), the status shows the configured port while stopped, the device-reachability probe no longer reports false errors, and only a device proxy Sandroid set is cleared on stop/exit (mitmproxy.auto_device_proxysets it on start).Evidence integrity: SQLite diffs integrate
-wal/-journalfiles and runsqldiffon temporary copies, so pulled databases underraw/are no longer rewritten (VACUUM, WAL checkpoint,-shm) before they are hashed.Changed Files: one file whose diff fails (non-UTF-8
.txt, malformed ABX) is listed with a “could not analyse” note instead of emptying the whole section.Diff failures (missing/failed
sqldiff, unparsable XML/ABX, missing pull) are reported as such and never shown as “No changes” or dropped as “ITS ALL NOISE”; CLI/headless warn at startup whensqldiffis missing.Failed runs are no longer sealed as clean: fatal and per-step errors (incl. failed result sections) are stored as
Run Errorsin the results JSON andRun Metadata(run_status), shown as a banner on the PDF’s first page, and make--trigdroid/--headless/--batchexit with code 3.Device file names that are not valid UTF-8 no longer abort the filesystem scan (they are kept byte-exact for pulls, JSON and
SHA256SUMS); the scan timeout is 300 s (SANDROID_SCAN_TIMEOUT), and an empty or failed baseline scan aborts the run instead of producing empty results.--trigdroidwrites its results, PDF and manifest into the session folder instead of the base results directory.--batch: every package gets its own result folder (raw pulls, JSON, PDF, manifest) instead of sharing one session folder; per-path diff caches are reset per run.Renaming a run in Files → Diffs no longer rewrites the sealed
run.json(the label is kept inruns/labels.json/index.json), so the bundle still verifies.A result folder whose
SHA256SUMSwas deleted is verified againstmanifest.jsonand reported as failed instead of being treated as unsealed; the--report-frommessage reflects an addendum.Artifact hashes include files that also changed in the dry run.
Files hidden as structural noise (ART profiles, package-manager bookkeeping) or dry-run noise are listed under
Other Data → Filtered Noisewith their reason, and the PDF has a compact Filtered Noise appendix.Changed/New Files and SQLite update columns are reported in a deterministic order.
pcap analysis is streamed and bounded: a dup-ACK/FIN storm on a half-open connection restored from the snapshot (1.3 M packets, 94 MB per capture) made the network analysis take ~4 min and >11 GB RAM. Captures are now read packet by packet into per-flow totals (same results, ~7 s for two such captures), repeated zero-payload TCP segments are not counted as traffic, progress is logged, and a capture over 5 M packets is cut with an “analysis truncated after N packets” note in the results.
friTap: when the agent cannot unload (an app thread stuck in a hooked SSL call, which left the app permanently “isn’t responding”), a spawned app is force-stopped after 19 s; for an attached app the log says it is likely frozen and how to recover. The routine “agent still unloading” note is no longer a warning.
The header’s App PID is re-checked while other tabs are shown, so an app restarted outside Sandroid no longer shows its dead PID as running.
A replayed recording’s run gets a distinct label (
<label> · play 2) instead of a duplicate in the Runs rail.The dry run’s start, window length and end are logged (headless output showed no sign of it).
Settings keep the live configuration: saving in the TUI Settings screen (or changing mitmproxy addons) no longer reloads the config from disk, which silently dropped
--config/--environment/CLI flags (results path,--network/--hash). Changes are validated against the whole config first (e.g. Number of Runs < 2 is refused with an error in the screen instead of breaking every later start), applied in place and written to the config file actually in use (the--configfile if given) — only the changed keys, including sections missing from a minimal file. The Settings screen shows the values actually in effect.sandroid --config FILE(and--environment/SANDROID_*-only setups) no longer fail with “No configuration found!” when no config file is auto-discovered.sandroid-config initwithout-ono longer overwrites an existing user config without--force;sandroid-config set KEY VALUE/get KEYaccept positional arguments (as the built-in hints and docs show), besides-k/-v.Config discovery no longer picks up
sandroid.json(the default results file) orconfig.*from the working directory, and saves never write to such files.qand the command palette’s Quit go through the same path asCtrl+C(stop running tasks / confirm) —qused to exit immediately and the palette entry did nothing; theQuitCommandno longer logs a misleading “Exiting application…”.Snapshot slots can be saved with
Sthen1–8in every terminal;Ctrl+1–8only work in terminals with the kitty keyboard protocol (documented).Switching views with Shift+Arrows never leaves focus in a text field (Watchlist’s “Add path” swallowed the next
⇧P), and Shift+Arrows also work when nothing is focused.--trigdroid-ccf(never functional with the current TrigDroid API) is hidden and fails with a clear error;--trigdroid … -f dir/out.jsonalso writes the results todir/out.json(the directory was dropped) and prints the final path.Importing the TUI module no longer registers a terminal reset at exit, which printed escape sequences /
sttyerrors after headless andsandroid-configruns.Docs: non-working commands fixed (
--output→-f,--number 1→-n 2, CI/Docker/script examples use--headless), exit-code table matches the code (1 = analysis/config error, 2 = invalid command line, 3 = documentation failed).The device proxy and app-proxy lanes are bound to the device they were set on: switching devices releases them on the old device, and later cleanup never runs against the newly selected one; “already proxied” is checked per device.
Emulator memory guard: the qemu behind a serial is found by its console port socket (emulators started without
-portget auto-assigned ports), so with two emulators the guard no longer measures or stops the wrong one; ambiguous cases are left alone with a warning.Starting an AVD from the TUI disables guest Vulkan like the CLI; detached emulators log to
~/.cache/sandroid/emulator/<avd>.loginstead of a pipe that stalled them after ~64 KiB of output; “Restart emulator” relaunches the running AVD with the safe flags and only reports success once it has booted.Deleting a snapshot the console rejects (
KO: …) is reported as a failure.Creating, loading or slot-saving a snapshot that fails (e.g. an invalid name) shows an error toast instead of “Created snapshot …”; invalid names are rejected before any adb call.
After the CA install restarts Zygote (and with it system_server), a running frida-server is restarted and cached frida handles are dropped, so the next spawn no longer fails with
DeadSystemException; at startup a frida-server older than system_server is restarted instead of reported as “already running”.TUI replays record
replay_settle_secondsinrun_settings(only headless runs did).Watchlist: after adding a path, focus returns to the list (the next
n/awas typed into the field); re-expanding a wildcard no longer logs “already in spotlight files” for every known match or toasts “new file(s)” when nothing is new, and expanded files that disappear are dropped quietly instead of erroring on every auto-mode tick.The startup CA-status probe no longer logs two ADB WARNINGs when the CA is simply not installed yet (one INFO line instead).
Headless API network capture starts tcpdump detached on the device (it blocked for 30 s), honours
output_file, and stops exactly its own tcpdump PID instead ofpkill tcpdump.
Security
Host command injection from the device or the AI: values that reach
adbthrough the host shell — device filenames (watchlist auto-refresh, wildcard spotlight files), package names, PIDs, snapshot names, emulator-console arguments, root/kprobe command wrappers — are now quoted for both the host and the device shell or validated (Android package format,[A-Za-z0-9._-]snapshot names, positive integer PIDs). Previously a device file named$(cmd)or a READ_ONLY AI tool call such asget_process_detail(pid="1;cmd")rancmdon the analyst’s machine without approval.AI tool arguments are type-checked against each tool’s JSON schema before dispatch;
set_spotlight_app,enable_app_proxyand the spotlight service reject invalid package names;get_file_diffaccepts only one absolute path without wildcards.The tool-approval prompt no longer hides arguments past 300 characters: long arguments are flagged and shown in full (scrollable), model-supplied markup is escaped, and an omitted package shows the spotlight app it resolves to.
Removed
Legacy Rich interactive menu (
-i), Gemini video summarisation (--ai), TUI view modes, theipt2socksredirector, the staledocker/requirements.txt.
[2.0.0] - 2026-03-17
Complete Rewrite: Textual TUI, Click CLI, and Three Analysis Views
This release represents a complete rewrite of Sandroid’s user interface and CLI, introducing a modern terminal user interface, a new Click-based command-line interface, and three specialized analysis views.
Added
Textual TUI
Modern terminal user interface using the Textual framework replacing the Rich-based menu
Three analysis views: Forensic, Malware, and Security (early stage) — switch with TAB
Status bar showing Frida server status, HTTP proxy, spotlight app, and spotlight files
Activity log with real-time command output and status messages
Theme system with 8 built-in themes (default, dark, light, high_contrast, cyberpunk, nord, dracula, solarized)
Custom CSS support for TUI customization
Welcome dialog for first-time users
Click-Based CLI
Migrated from argparse to Click with hyphenated flags (e.g.,
--avoid-strong-noise-filter)View selection:
--view forensic|malware|securityHeadless mode:
--headlesswith--batchfor batch processingLegacy mode:
sandroid -ifor the classic Rich interactive menu
New Analysis Tools
Dexray-Intercept integration for dynamic hooking and malware monitoring (
--dexray)Dexray-Insight integration for static analysis (replacing asam)
Fridump integration for memory dumping (
--fridump)FriTap headless mode for SSL/TLS key extraction (
--fritap)Objection integration with resume support
MVT (Mobile Verification Toolkit) forensic evidence scanning
Device Management
HTTP proxy management:
--proxy,--proxy-clearAPK installation:
--install-apkAction import:
--import-actionDevice settings:
--device-settings,--presetCountry presets (de, us, ru, cn, etc.)
Configuration Management
AVD management commands:
sandroid-config avd list|start|stop|rename|createTheme management:
sandroid-config theme list|set|showIOC management:
sandroid-config ioc show|set-path|set-url|download|validateDevice listing:
sandroid-config devicesTOML as default configuration format (replacing YAML)
New TUI Commands
C— Spawn spotlight applicationE— Device settings and presetsF— Forensic evidence scan (MVT)G— Manage forensic APKsk— Reconfigure Frida hooksO— Resume objection session
Changed
Default mode:
sandroidnow launches the Textual TUI (previously Rich menu)Legacy mode: Rich interactive menu available via
sandroid -iTrigDroid: Now fully integrated (previously marked as not fully integrated)
Frida handling: Smart per-command requirement with modal prompts instead of manual install-first workflow
Command registry: 12 command categories across 3 views replacing 5 static menu sections
Removed
AM3 (Android Malware Motion Monitor): Replaced by Dexray-Intercept
asam: Renamed to Dexray-Insight
[1.1.9] - 2025-09-15
Updated Fridump class to work with frida >= 17.0
[1.1.0] - 2025-08-27
Complete Package Migration: PyPI Distribution Now Feature-Complete
This release resolves the critical “Legacy analysis modules not available” error and makes the PyPI installation fully feature-complete with the legacy version.
Fixed
Package Migration: Migrated 32 analysis modules from
src/utils/,src/datagather/, andsrc/functionality/to proper pip-installable packagesImport Errors: Fixed “No module named ‘src’” errors that prevented PyPI installation from working
Module Structure: Reorganized code into modern package structure:
src/utils/→src/sandroid/core/(15 modules)src/datagather/→src/sandroid/analysis/(10 modules)src/functionality/→src/sandroid/features/(5 modules)
Added
Dual-Mode Architecture: Both legacy (
./sandroid) and modern (sandroid) CLI work identicallyCompatibility Layer: Transparent import redirection maintains 100% backward compatibility
Code Quality: Comprehensive linting configuration with security rule exemptions for forensic tools
Modern Dependencies: Updated Frida to v17+ and frida-tools to v14+
Changed
Package Structure: Migrated to modern Python packaging while preserving all functionality
Import Paths: Fixed hardcoded
from src.imports throughout the codebaseBuild Configuration: Updated
pyproject.tomlto include all migrated packages
Technical Details
32 Modules Migrated: Complete analysis framework now properly packaged
Circular Import Resolution: Fixed complex interdependencies between modules
Linting Compliance: Resolved F403, TID252, F405, and security (S*) linting issues
Type Safety: Fixed Pydantic v2 API compatibility (
regex→pattern)
[1.0.0] - 2025-01-21
🚀 Major Release: Modern PyPI Package with Advanced Configuration
This release represents a complete modernization of the Sandroid framework while maintaining full backward compatibility. The project now offers professional-grade packaging, configuration management, and development workflows.
Added
PyPI Package Infrastructure
Modern pyproject.toml with comprehensive dependency management
Entry points for CLI commands (
sandroid,sandroid-config)Optional dependencies for different use cases (
[ai,dev,docs])Development tools integration (black, isort, pytest, mypy, flake8)
Build system using modern setuptools backend
Proper package structure under
src/sandroid/
Advanced Configuration System
Pydantic-based configuration schema with full type validation
Multi-format support: TOML, YAML, JSON configuration files
XDG Base Directory compliance for standard config file locations
Hierarchical configuration loading: CLI args > env vars > config files > defaults
Environment variable support with
SANDROID_prefix and nested configurationConfiguration validation with clear error messages and helpful suggestions
Configuration CLI tool (
sandroid-config) for easy management
Modern CLI Interface
Rich console output with colors, tables, and syntax highlighting
Click framework for robust argument parsing and help system
Interactive configuration management commands
Environment-specific configurations for development, testing, production
Comprehensive help system with examples and detailed descriptions
Configuration Management Features
sandroid-config init- Create default configuration files (YAML format)sandroid-config show- Display current configuration with formattingsandroid-config validate- Validate configuration filessandroid-config set/get- Modify individual configuration valuessandroid-config paths- Show configuration file search locationsConfiguration file discovery in standard XDG directories
Template configurations for different use cases
YAML-first approach with support for TOML and JSON
Secure credentials section for API keys and tokens
Documentation Suite
SETUP.md - Comprehensive setup guide for new users
MIGRATION.md - Detailed migration guide from legacy to modern installation
Updated development documentation - Modern development workflows and installation methods
Configuration examples for basic analysis, security analysis, and development
Environment variable reference with complete configuration mapping
Troubleshooting guides for common setup and configuration issues
Development Infrastructure
Modern testing framework with pytest and coverage reporting
Code quality tools with black, isort, flake8, mypy configurations
Type hints throughout the configuration system
Mock testing infrastructure for ADB and emulator interactions
CI/CD ready configurations for automated testing and building
Enhanced
CLI Experience
Backward compatible command-line interface preserving all existing arguments
Enhanced help system with detailed descriptions and examples
Rich formatting for error messages and output
Configuration integration allowing CLI arguments to override config files
Environment detection with automatic configuration loading
Configuration Management
Replaced hardcoded values with configurable options throughout the system
Path management with automatic directory creation and validation
Security improvements with environment variable support for sensitive data
Extensibility through custom configuration sections
Validation preventing invalid configurations from being used
Developer Experience
Modern package structure following Python packaging best practices
Development mode installation with
pip install -e .[dev]Comprehensive testing with unit, integration, and configuration tests
Documentation generation with Sphinx support
Code formatting with automatic black and isort integration
Changed
Installation Method
Primary installation now via PyPI:
pip install sandroidOptional dependencies for different use cases
Simplified setup with automatic dependency resolution
Configuration initialization as separate step for better user control
Configuration Architecture
Moved from hardcoded values to external configuration files
Standardized configuration locations following XDG specification
Environment variable standardization with
SANDROID_prefixHierarchical loading allowing multiple configuration sources
Type validation preventing configuration errors
Project Structure
New package layout under
src/sandroid/for proper packagingSeparated configuration system into dedicated module
Modern CLI entry points while preserving legacy script
Documentation organization with dedicated setup and migration guides
Maintained
Backward Compatibility
Legacy installation method still fully supported
Existing CLI arguments work unchanged
Legacy scripts (
./sandroid) continue to functionExisting workflows require no immediate changes
Gradual migration path with comprehensive guides
Core Functionality
All analysis capabilities preserved without modification
Frida integration unchanged
Android emulator support maintained
Output formats (JSON, PDF) unchanged
Ground truth APK functionality preserved
Dependencies
Core dependencies remain the same
Analysis modules work without modification
Frida manager integration preserved
ADB communication unchanged
Technical Details
Configuration Schema
# Example modern configuration
log_level = "INFO"
output_file = "sandroid.json"
[emulator]
device_name = "Pixel_6_Pro_API_31"
android_emulator_path = "~/Android/Sdk/emulator/emulator"
[analysis]
number_of_runs = 2
monitor_network = false
monitor_processes = true
[paths]
results_path = "./results/"
cache_path = "~/.cache/sandroid/"
Environment Variables
# All configuration can be set via environment variables
export SANDROID_LOG_LEVEL="DEBUG"
export SANDROID_EMULATOR__DEVICE_NAME="Custom_Device"
export SANDROID_ANALYSIS__NUMBER_OF_RUNS=5
export SANDROID_PATHS__RESULTS_PATH="/custom/results"
CLI Commands
# Modern installation and usage
pip install sandroid[ai,dev]
sandroid-config init
sandroid-config validate
sandroid --config production.toml --network --ai --report
# Configuration management
sandroid-config show --format toml
sandroid-config set analysis.monitor_network true
sandroid-config get emulator.device_name
Migration Path
For New Users
Install via PyPI:
pip install sandroidInitialize configuration:
sandroid-config initCustomize configuration as needed
Run analysis:
sandroid --help
For Existing Users
Continue using legacy installation (no changes required)
When ready, install PyPI package alongside legacy
Use migration guide to transfer settings
Switch to modern CLI when convenient
Remove legacy installation when comfortable
Dependencies
New Dependencies
pydantic>=2.0.0- Configuration validation and type safetyplatformdirs>=3.0.0- XDG directory compliancerich>=13.0.0- Enhanced console output and formattingtomli>=2.0.1(Python <3.11) - TOML file parsingtomli-w>=1.0.0- TOML file writingpyyaml>=6.0- YAML configuration support
Optional Dependencies
[ai]- Google Generative AI support[dev]- Development tools (pytest, black, isort, mypy, flake8)[docs]- Documentation generation tools (sphinx, themes)
Breaking Changes
None - This release maintains full backward compatibility.
Security
Secure credentials management with dedicated configuration section
API key extraction from source code to configuration files
Environment variable support for sensitive configuration (API keys)
Configuration validation prevents invalid or dangerous settings
Path validation ensures secure file operations
Input sanitization in configuration loading
GitLab token management moved from hardcoded values to secure configuration
Performance
Lazy loading of configuration only when needed
Cached configuration parsing for repeated access
Optimized dependency loading with optional imports
Efficient file discovery using XDG standard locations
Documentation Updates
Complete SETUP.md with step-by-step installation guide
Comprehensive MIGRATION.md for upgrading from legacy
Updated development documentation with modern development workflows
Configuration examples for different use cases
Environment variable reference documentation
Troubleshooting guides for common issues
API documentation for configuration schema
Previous Versions
[0.x.x] - Legacy Versions
Original hardcoded configuration system
Manual installation via
install-requirements.shDirect script execution with
./sandroidLimited configuration options
Basic CLI interface
Migration Notes
From Legacy to Modern
No immediate action required - legacy installation continues to work
Try modern installation alongside legacy for evaluation
Use migration guide when ready to switch
Gradual migration - move configurations over time
Full backward compatibility ensures no functionality loss
Configuration Migration
Use
sandroid-config initto create modern configurationTransfer hardcoded values from
toolbox.pyto config filesReplace custom environment variables with
SANDROID_prefixed versionsValidate new configuration with
sandroid-config validate
Development Migration
Install development dependencies:
pip install -e .[dev]Use modern testing:
pytestinstead of custom test scriptsApply code formatting:
black src/andisort src/Add type hints using configuration schema as example
Acknowledgments
This modernization maintains the core forensic analysis capabilities of Sandroid while providing a professional, maintainable foundation for future development. The extensive backward compatibility ensures existing users can migrate at their own pace while new users benefit from modern Python packaging and configuration practices.