Skip to main content

​
Overview

The TermuxManager class (core/termux_manager.py:8) provides Android-native file operations when running directly on an Android device via Termux, bypassing the need for ADB.

​
Class Definition

core/termux_manager.py
class TermuxManager:
    """
    Manager for Termux environment operations.
    Handles file access directly via filesystem instead of ADB.
    """
    
    WHATSAPP_PACKAGES = {
        'com.whatsapp': 'WhatsApp Messenger',
        'com.whatsapp.w4b': 'WhatsApp Business'
    }

​
Constructor

​
__init__()

def __init__(self, output_dir: str = "backups")
​
output_dir
str
default:"backups"
Directory where backups will be copied
Attributes:
  • output_dir: Output directory for backups
  • os_type: Always set to ‘termux’

​
Key Differences from DeviceManager

No ADB Dependency

Direct filesystem access without ADB bridge

Internal Storage

Access to internal storage with proper permissions

File Operations

Uses shutil.copy2() instead of ADB pull

Local Execution

Runs natively on the Android device itself

​
Device Information

​
get_devices()

Returns localhost as the device (Termux runs locally). 
def get_devices(self) -> List[str]
​
return
List[str]
Always returns [“localhost (Termux)“]

​
get_detailed_device_info()

Retrieves basic device information using Python’s platform module. 
def get_detailed_device_info(self, serial: str) -> dict
​
serial
str
required
Ignored (always localhost)
​
return
dict
Dictionary with limited device info:
  • Serial: ‘localhost’
  • Model, Brand: From platform module
  • Storage: From shutil.disk_usage()
  • Other fields: ‘Unknown’ or placeholder values

​
get_users()

Returns primary user (user 0). 
def get_users(self, device_id: str) -> List[Dict[str, str]]
​
return
List[Dict[str, str]]
Always returns a list with one user: id ‘0’ and name ‘Owner’

​
check_packages()

Returns all known WhatsApp packages (cannot verify without root). 
def check_packages(self, device_id: str) -> List[str]
​
return
List[str]
Returns [‘com.whatsapp’, ‘com.whatsapp.w4b’]

​
Backup Discovery

​
find_backups()

Scans accessible storage locations for WhatsApp backups. 
def find_backups(self, device_id: str, user_id: str, package: str) -> List[Dict[str, str]]
​
device_id
str
required
Ignored (localhost)
​
user_id
str
required
User ID (usually “0”)
​
package
str
required
Package name (com.whatsapp or com.whatsapp.w4b)
​
return
List[Dict[str, str]]
List of backup dictionaries with path, name, and size
Search Locations: 
base_paths = [
    "/sdcard",
    os.path.join(home, "storage/shared"),
    os.path.join(home, "storage/external-1")
]
Search Patterns:
  • WhatsApp: WhatsApp/Databases, Android/media/com.whatsapp/WhatsApp/Databases
  • Business: WhatsApp Business/Databases, Android/media/com.whatsapp.w4b/WhatsApp Business/Databases
Example: 
termux = TermuxManager()
backups = termux.find_backups("localhost", "0", "com.whatsapp")
for backup in backups:
    print(f"{backup['name']}: {backup['size']}")

​
find_media()

Locates WhatsApp Media folder in accessible storage. 
def find_media(self, device_id: str, user_id: str, package: str) -> str
​
device_id
str
required
Ignored (localhost)
​
user_id
str
required
User ID
​
package
str
required
Package name
​
return
str
Path to Media folder, or empty string if not found

​
File Operations

​
dump_backup()

Copies a backup file from storage to output directory. 
def dump_backup(
    self, 
    device_id: str, 
    remote_path: str, 
    user_id: str, 
    package_type: str, 
    verbose: bool = True
) -> str
​
device_id
str
required
Ignored (localhost)
​
remote_path
str
required
Full path to backup file
​
user_id
str
required
User profile ID
​
package_type
str
required
“messenger” or “business”
​
verbose
bool
default:"True"
Print status messages
​
return
str
Local path to copied file, or empty string on failure
Implementation: 
shutil.copy2(remote_path, local_path)
Uses copy2() to preserve metadata (timestamps, permissions).

​
dump_media_with_progress()

Copies Media folder with progress tracking. 
def dump_media_with_progress(
    self, 
    device_id: str, 
    remote_path: str, 
    local_dir: str
) -> bool
​
device_id
str
required
Ignored (localhost)
​
remote_path
str
required
Path to Media folder
​
local_dir
str
required
Local directory to save media
​
return
bool
True if successful, False otherwise
Implementation:
  1. Walk directory tree with os.walk()
  2. Count total files
  3. Copy each file with shutil.copy2()
  4. Show progress with tqdm
  5. Preserve directory structure

​
Storage Access

Termux requires storage permissions to access WhatsApp files. Run termux-setup-storage and grant permissions in Android settings.
Setup Storage Access: 
# In Termux
termux-setup-storage
This creates ~/storage/ symlinks to Android storage:
  • ~/storage/shared → /sdcard
  • ~/storage/dcim → /sdcard/DCIM
  • ~/storage/downloads → /sdcard/Download

​
Usage Example

from core.termux_manager import TermuxManager

# Initialize manager
termux = TermuxManager()

# Get device info
info = termux.get_detailed_device_info("localhost")
print(f"Running on: {info['Model']}")

# Find backups
users = termux.get_users("localhost")
packages = termux.check_packages("localhost")

for user in users:
    for pkg in packages:
        backups = termux.find_backups("localhost", user['id'], pkg)
        
        for backup in backups:
            print(f"Found: {backup['name']}")
            
            # Copy backup
            pkg_type = "messenger" if pkg == "com.whatsapp" else "business"
            local_path = termux.dump_backup(
                "localhost",
                backup['path'],
                user['id'],
                pkg_type
            )
            
            if local_path:
                print(f"Copied to: {local_path}")

​
Environment Detection

The main application detects Termux environment:
main.py:30-32
IS_TERMUX = False
if os.environ.get("PREFIX") and "com.termux" in os.environ.get("PREFIX"):
    IS_TERMUX = True
Based on this flag, the appropriate manager is used:
main.py:34-40
if IS_TERMUX:
    from core.termux_manager import TermuxManager
    ui.update_status("mode", "Termux")
else:
    from core.device_manager import DeviceManager
    ui.update_status("mode", "ADB")

​
Advantages

No PC Required

Run forensic analysis directly on the target device

Internal Storage Access

Access internal storage with proper permissions

Faster Operations

No USB transfer overhead, direct file access

Portable

Entire forensic toolkit on a mobile device

​
Limitations

TermuxManager has limited capabilities compared to DeviceManager:
  • Cannot query detailed hardware info
  • No battery/RAM statistics
  • Cannot verify installed packages without root
  • Requires manual storage permission setup

Android/Termux Guide

Complete setup guide for Termux

DeviceManager

ADB-based device management

Backup Extraction

Extract backups from devices

Troubleshooting

Solve common Termux issues

Build docs developers (and LLMs) love

Get started for freeTalk to us