Migration Guide

This guide helps you migrate from the legacy Sandroid installation to the modern PyPI package, and understand the changes introduced in v1.1.0.

Note

Upgrading from 2.0 to 2.1? See MIGRATION.md in the repository root (section Upgrading from 2.0.x to 2.1): Python 3.12+ is required, and the legacy Rich menu (-i), --ai (Gemini) and the TUI views (--view) were removed.

Migration Overview

What Changed in v1.1.0:

  • Complete package restructuring from src/utils/ to proper Python packages

  • Modern PyPI distribution with all analysis modules included

  • New configuration system with sandroid-config CLI tool

  • Dual-mode architecture supporting both legacy and modern usage

  • Fixed the critical “Legacy analysis modules not available” error

Migration Types:

  1. Gradual Migration - Use both systems in parallel (recommended)

  2. Complete Migration - Switch entirely to modern system

  3. Development Migration - Update development workflows

Legacy to Modern Migration

Current State Assessment:

First, determine your current setup:

# Check if you have legacy installation
ls -la ./sandroid  # Legacy script exists?

# Check if you have PyPI installation
which sandroid    # Modern command available?
sandroid --version  # Should show 1.1.0+

Gradual Migration (Recommended):

This approach lets you test the modern system while keeping the legacy system working:

# 1. Keep your existing legacy installation
# Don't remove anything yet

# 2. Install modern PyPI package alongside
pip install sandroid

# 3. Test modern installation
sandroid --version  # Should work without "legacy modules" error
sandroid --help     # Should show full help

# 4. Initialize modern configuration
sandroid-config init

# 5. Test side-by-side
./sandroid --help         # Legacy way (still works)
sandroid --help           # Modern way (now also works)

Configuration Migration:

# 1. Create modern configuration
sandroid-config init

# 2. Migrate settings from legacy hardcoded values
# Check your current settings in src/utils/toolbox.py
grep -r "device_name\|results_path\|number_of_runs" src/utils/

# 3. Set corresponding values in modern config
sandroid-config set emulator.device_name "Your_Current_Device"
sandroid-config set paths.results_path "./results/"
sandroid-config set analysis.number_of_runs 2

Testing Migration:

# Test with identical parameters

# Legacy way:
./sandroid -n 2 --network --screenshot 5

# Modern way:
sandroid --number 2 --network --screenshot 5

# Compare results - they should be identical

Complete Migration:

Once you’re confident the modern system works:

# 1. Archive your legacy installation
tar -czf sandroid_legacy_backup.tar.gz src/ utils/ *.py sandroid

# 2. Update your scripts/aliases
echo "alias sandroid-legacy='./sandroid'" >> ~/.bashrc
echo "alias sandroid='sandroid'"  # Modern version is now default

# 3. Update documentation and workflows
# Replace ./sandroid with sandroid in scripts

Package Structure Migration

Old Structure (Legacy):

Sandroid_core/
├── src/
│   ├── utils/           # Core utilities (15 modules)
│   ├── datagather/      # Analysis modules (10 modules)
│   └── functionality/   # Feature modules (5 modules)
├── sandroid             # Main script
└── install-requirements.sh

New Structure (Modern):

Sandroid_core/
└── src/sandroid/
    ├── core/           # Was: src/utils/ (15 modules)
    ├── analysis/       # Was: src/datagather/ (10 modules)
    ├── features/       # Was: src/functionality/ (5 modules)
    ├── config/         # New: Configuration system
    └── cli.py          # New: Modern CLI entry point

The src/utils/, src/datagather/, src/functionality/ compatibility aliases and the legacy ./sandroid launcher have since been removed entirely; sandroid/sandroid-config (installed via pip install -e .) are the only supported entry points.

Import Path Changes:

If you have custom code importing Sandroid modules:

# Old imports (still work via compatibility layer):
from src.utils.toolbox import Toolbox
from src.datagather.changedfiles import ChangedFiles
from src.functionality.screenshot import Screenshot

# New imports (recommended):
from sandroid.core.toolbox import Toolbox
from sandroid.analysis.changedfiles import ChangedFiles
from sandroid.features.screenshot import Screenshot

Development Workflow Migration

Legacy Development Setup:

git clone https://github.com/fkie-cad/Sandroid_core.git
cd Sandroid_core
./install-requirements.sh
./sandroid --help

Modern Development Setup:

git clone https://github.com/fkie-cad/Sandroid_core.git
cd Sandroid_core

# Install in development mode
pip install -e .[dev]

# Initialize configuration
sandroid-config init

# Test installation
sandroid --version
sandroid --help

CI/CD Migration:

Legacy CI Pipeline:

- name: Setup Sandroid
  run: |
    git clone https://github.com/fkie-cad/Sandroid_core.git
    cd Sandroid_core
    ./install-requirements.sh

- name: Run Analysis
  run: |
    cd Sandroid_core
    ./sandroid --network --report

Modern CI Pipeline:

- name: Setup Sandroid
  run: |
    pip install sandroid[ai]
    sandroid-config init

- name: Run Analysis
  run: |
    sandroid --network --report

Docker Migration:

Legacy Dockerfile:

FROM python:3.10
RUN git clone https://github.com/fkie-cad/Sandroid_core.git
WORKDIR /app/Sandroid_core
RUN ./install-requirements.sh
CMD ["./sandroid"]

Modern Dockerfile:

FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends adb
RUN pip install "sandroid[full]"
CMD ["sandroid"]

(See docker/dockerfile for the maintained, best-effort image.)

Configuration System Migration

Legacy Configuration (Hardcoded):

Previously, configuration was hardcoded in src/utils/toolbox.py:

# Old way - hardcoded values
class Toolbox:
    device_name = "Pixel_6_Pro_API_31"
    results_path = "./results/"
    number_of_runs = 2

Modern Configuration (File-based):

Now configuration uses structured files:

# ~/.config/sandroid/sandroid.toml
log_level = "INFO"
output_file = "sandroid.json"

[emulator]
device_name = "Pixel_6_Pro_API_31"

[analysis]
number_of_runs = 2

[paths]
results_path = "./results/"

Environment Variable Migration:

Legacy:

export RESULTS_PATH="/custom/results"
export RAW_RESULTS_PATH="/custom/raw"

Modern:

export SANDROID_PATHS__RESULTS_PATH="/custom/results"
export SANDROID_PATHS__RAW_RESULTS_PATH="/custom/raw"

API Migration Guide

For Developers Using Sandroid as a Library:

Legacy API Usage:

# Old way
sys.path.append('path/to/Sandroid_core/src')
from utils.toolbox import Toolbox
from datagather.changedfiles import ChangedFiles

# Initialize and run
toolbox = Toolbox()
changed_files = ChangedFiles()
changed_files.gather()

Modern API Usage:

# New way
from sandroid.core.toolbox import Toolbox
from sandroid.analysis.changedfiles import ChangedFiles
from sandroid.config.loader import load_config

# Initialize with configuration
config = load_config()
Toolbox.configure(config)

# Use analysis modules
changed_files = ChangedFiles()
changed_files.gather()

Custom Module Development:

Legacy Custom Module:

# old_custom_module.py
import sys
sys.path.append('src/')
from utils.toolbox import Toolbox
from datagather.datagather import DataGather

class CustomAnalyzer(DataGather):
    def gather(self):
        # Custom logic
        pass

Modern Custom Module:

# modern_custom_module.py
from sandroid.core.toolbox import Toolbox
from sandroid.analysis.base_di import DataGatherBase
from sandroid.config.loader import load_config

class CustomAnalyzer(DataGatherBase):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.config = load_config()

    def gather(self):
        # Custom logic with configuration support
        pass

Breaking Changes and Compatibility

No Breaking Changes for End Users:

  • All CLI commands work identically

  • All analysis results are the same format

  • All interactive menu options unchanged

  • Legacy ./sandroid script still works

Potential Issues for Developers:

  1. Direct File Path Dependencies:

# This might break:
with open('src/utils/config.py') as f:
    content = f.read()

# Use imports instead:
from sandroid.core import config
  1. Hardcoded sys.path Modifications:

# This is no longer needed:
sys.path.append('src/')

# Just use normal imports:
from sandroid.core.toolbox import Toolbox
  1. Assumption About File Structure:

# Don't assume file paths:
config_path = 'src/utils/config.json'  # Bad

# Use proper configuration:
from sandroid.config.loader import find_config_file
config_path = find_config_file()  # Good

Validation and Testing

Migration Validation Checklist:

# 1. Installation validation
sandroid --version  # Should show 1.1.0+
sandroid-config validate  # Should pass

# 2. Basic functionality
sandroid --help  # Should show full help without errors

# 3. Configuration system
sandroid-config show  # Should display configuration

# 4. Analysis capability
sandroid -n 2 --screenshot 10  # Should run without errors

# 5. Compatibility
./sandroid --help  # Legacy script should still work

Regression Testing:

# Test with same APK using both methods

# Legacy method
./sandroid --number 2 --network -f legacy_results.json

# Modern method
sandroid --headless --mode forensic -n 2 --network -f modern_results.json

# Compare results (should be identical)
diff legacy_results.json modern_results.json

Performance Comparison:

# Time both methods
time ./sandroid --number 2
time sandroid --number 2

# Performance should be identical or better

Rollback Plan

If you need to rollback the modern installation:

# 1. Remove PyPI installation
pip uninstall sandroid

# 2. Restore legacy installation (if you have backup)
tar -xzf sandroid_legacy_backup.tar.gz

# 3. Reinstall legacy dependencies
./install-requirements.sh

# 4. Test legacy functionality
./sandroid --version

Common Migration Issues

Issue: “Command not found: sandroid”

# Solution: Check pip installation location
pip show sandroid

# Add to PATH if needed
export PATH=$PATH:~/.local/bin

Issue: “Configuration file not found”

# Solution: Initialize configuration
sandroid-config init

# Or create manually
mkdir -p ~/.config/sandroid
sandroid-config init

Issue: “Import errors in custom code”

# Update import statements
# Old:
from src.utils.toolbox import Toolbox

# New:
from sandroid.core.toolbox import Toolbox

Issue: “Different results between legacy and modern”

# Check configuration differences
sandroid-config show

# Ensure same parameters
sandroid --loglevel DEBUG --number 2

Issue: “Performance degradation”

# Check for conflicting installations
which sandroid
pip list | grep sandroid

# Clear Python cache
find . -name "*.pyc" -delete
find . -name "__pycache__" -delete

Support and Help

Getting Help During Migration:

  1. Check Documentation: - Installation - Modern installation guide - Troubleshooting - Common issues and solutions

  2. Validate Your Setup:

sandroid-config validate
sandroid --version
sandroid --help
  1. Enable Debug Mode:

SANDROID_LOG_LEVEL=DEBUG sandroid --network
  1. Report Issues: - GitHub Issues: https://github.com/fkie-cad/Sandroid_core/issues - Include: Sandroid version, system info, error messages

Pre-Migration Checklist:

  • [ ] Backup current installation

  • [ ] Document current configuration/settings

  • [ ] Test modern installation in parallel

  • [ ] Validate results match between versions

  • [ ] Update scripts and documentation

  • [ ] Train team on new configuration system

Post-Migration Checklist:

  • [ ] All team members can run sandroid --version

  • [ ] Configuration system is working: sandroid-config validate

  • [ ] CI/CD pipelines updated and tested

  • [ ] Documentation reflects modern installation

  • [ ] Legacy backup is archived safely

This migration ensures you get all the benefits of the modern Sandroid system while maintaining complete compatibility with your existing workflows.