TraceForge — Termux & Android Platform Architecture Guide

1. Overview & Android Execution Model

TraceForge provides first-class support for Termux on Android (ARM64, ARMv7, x86_64, i686).

Unlike desktop Linux, Termux operates inside an unprivileged Android userland container without root permissions, standard /usr paths, or standard Linux system services (systemd, sysvinit). TraceForge embraces this model:

Filesystem Prefix: Executables and libraries live under $PREFIX (typically /data/data/com.termux/files/usr/).
Zero-Root Design: All first-party analytical tools, parsing engines, IOC extractors, timeline normalizers, and report generators run without root.
Root/Hardware Boundaries: Features that strictly require kernel monitor-mode drivers or raw packet injection (e.g. Aircrack-NG live monitor mode) are clearly separated from offline file analysis.

                      +-------------------------------+
                      |   Android Host (OS / Kernel)  |
                      +---------------+---------------+
                                      |
                                      v
                      +-------------------------------+
                      |  Termux Application Sandbox   |
                      |       (Non-Root Userland)     |
                      +---------------+---------------+
                                      |
                 +--------------------+--------------------+
                 |                                         |
                 v                                         v
   [ Termux Environment ($PREFIX) ]           [ Android Shared Storage ]
   • Python 3.11+ / isolated venv             • $HOME/storage/shared/
   • Golang (pkg install golang)              • /sdcard/Download/
   • Native Termux pkgs (exiftool, nmap)      • /sdcard/DCIM/
                 |                                         |
                 +--------------------+--------------------+
                                      |
                                      v
                      +-------------------------------+
                      |   TraceForge Analysis Engine  |
                      | (Offline Triage & Reporting)  |
                      +-------------------------------+

2. Prerequisites & Quickstart

Step 1: Install Termux

Install the latest official Termux build from F-Droid or official releases (avoid outdated Play Store releases).

Step 2: Update Packages & Grant Storage

Open Termux and execute:

pkg update -y && pkg upgrade -y
termux-setup-storage

[!IMPORTANT] termux-setup-storage prompts an Android permission dialog to allow access to /sdcard/Download/, /sdcard/DCIM/, etc.

Step 3: Clone & Install TraceForge

pkg install -y git python
git clone https://github.com/paman7647/TraceForge.git
cd TraceForge
./install_all.sh --profile python-go

3. Storage Architecture & Accessing Files

Termux uses an isolated private internal sandbox ($HOME / /data/data/com.termux/files/home/).

To analyze files located in normal Android phone storage:

Storage Path	Access Point in Termux	Description
Downloads	`~/storage/downloads/` or `/sdcard/Download/`	Ingest exported PCAPs, documents, or downloaded forensic artifacts
Camera / Images	`~/storage/dcim/` or `/sdcard/DCIM/`	Media files for EXIF and steganography analysis
Internal Storage	`~/storage/shared/` or `/sdcard/`	General internal phone storage
TraceForge Cases	`~/TraceForge/workspace/`	Isolated local forensic cases and export artifacts

Example Ingestion:

traceforge case add-evidence ~/storage/downloads/suspicious_evidence.pcap --desc "Network capture from field audit"

4. Capability Matrix: Supported vs Root-Required

Investigation Domain	Feature / Tool	Termux Support Tier	Android Root Required?	Notes
Media Forensics	ExifTool, Binwalk, xxd, Steghide, Jhead, FFmpeg	✓ Fully Supported	No	Installed via `pkg install <tool>`. Runs with native speed.
Document Analysis	Poppler (`pdftotext`, `pdfinfo`), Oletools, MAT2	✓ Fully Supported	No	Metadata sanitization and text harvesting unrooted.
IOC Extraction	Streaming IOC regex engine, defanger	✓ Fully Supported	No	Pure Python or compiled Go fast-path.
PCAP Analysis	Offline PCAP file triage (`summarize_pcap`, TShark offline)	✓ Fully Supported	No	Reads capture files from shared storage or downloads.
Network Recon	Nmap service/port scanning (`-sT`, `-sV`), DNS Recon, WHOIS	✓ Fully Supported	No	Standard TCP connect scan operates in userland.
Network Live Capture	Live packet capture via `tshark -i` or `tcpdump -i`	! Limited	Yes	Promiscuous packet capture requires Android root privileges (`su` / `tsu`).
Wireless Injection	Aircrack-NG, HCXtools live 802.11 monitor mode	! Hardware-Dependent	Yes + Hardware	Requires rooted Android kernel with wireless monitor-mode drivers or external USB OTG wireless adapter.
Identity & Breaches	Sherlock, Maigret, Holehe, GHunt, EmailRep	✓ Fully Supported	No	Operates over standard HTTPS REST APIs via Python.
Case Reporting	Markdown, HTML, Relational CSV, STIX 2.1, MISP JSON	✓ Fully Supported	No	Generates standalone reports directly into workspace.

5. Optional Termux:API Integration

TraceForge optionally queries termux-api utilities to enhance host posture diagnostics during endpoint audits:

termux-battery-status: Battery health, temperature, and charging state.
termux-wifi-connectioninfo: Active SSID, BSSID, RSSI signal strength, and link speed.
termux-device-info: Hardware manufacturer, model, and ABI.

To enable Termux:API:

pkg install -y termux-api
# Install Termux:API companion APK from F-Droid

6. Runtime Profiles on Android

Profile	Command	Footprint	Best Use Case
`python-go` (Recommended)	`./install_all.sh --profile python-go`	~1.2 GB	Workstations with Go toolchain for accelerated file indexing
`python`	`./install_all.sh --profile python`	~600 MB	Fast setup; runs pure Python reference engine with zero build steps
`minimal`	`./install_all.sh --profile minimal`	~250 MB	Low-storage Android devices (<2 GB free space)
`full`	`./install_all.sh --profile full`	~3.5 GB	Comprehensive DFIR and OSINT toolset

7. Troubleshooting & FAQs

Q: Why does live packet capture or wireless monitor mode fail?

Android limits raw socket binding (SOCK_RAW) and wireless interface configuration (ioctl) to the root user (uid 0). Live packet capture and Wi-Fi frame injection require a rooted phone with kernel driver support or a compatible USB OTG Wi-Fi card. Offline PCAP file analysis works completely unrooted.

Q: Permission denied when accessing `/sdcard`?

Run termux-setup-storage and grant storage permissions in the Android popup.

Q: Can TraceForge compile Go helpers on ARM64?

Yes. Termux provides the official Go compiler (pkg install golang). TraceForge automatically builds traceforge-native with -trimpath -ldflags="-s -w".