Command-Line Usage
==================

Sandroid provides a comprehensive command-line interface for automated analysis and batch processing. This mode is ideal for CI/CD integration, scripted analysis, and headless operation.

Basic Syntax
------------

::

   sandroid [OPTIONS]

All command-line options can be combined for customized analysis workflows.

Configuration Options
---------------------

**Configuration File**::

   sandroid -c config.toml
   sandroid --config /path/to/config.yaml

Specify a custom configuration file (TOML, YAML, or JSON format).

**Environment Selection**::

   sandroid --environment development
   sandroid --environment testing
   sandroid --environment production

Load environment-specific configurations.

**Output File**::

   sandroid -f analysis_results.json
   sandroid --file /path/to/results.json

Specify where to save analysis results (default: ``sandroid.json``).

**Log Level**::

   sandroid --loglevel DEBUG
   sandroid -ll INFO
   sandroid --loglevel WARNING

Set logging verbosity. Options: ``DEBUG``, ``INFO``, ``WARNING``, ``ERROR``, ``CRITICAL``.

Analysis Options
----------------

**Number of Runs**::

   sandroid -n 3
   sandroid --number 5

Run the analysis multiple times for better accuracy. Minimum is 2 runs for comparison.

**Noise Filtering**::

   sandroid --avoid-strong-noise-filter

Disable noise filtering to capture all changes. This will:

- Skip the "dry run" baseline
- Capture more system noise
- Disable intra-file noise detection
- Provide comprehensive but potentially noisy results

Monitoring Options
------------------

**Network Traffic Capture**::

   sandroid --network

Enable comprehensive network monitoring:

- Capture all network connections
- Log DNS queries
- Monitor traffic patterns
- Generate network analysis report

**Process Monitoring**::

   sandroid --no-processes

Disable process monitoring (enabled by default):

- Skip active process tracking
- Reduce system overhead
- Focus on file and network changes

**Socket Monitoring**::

   sandroid --sockets

Monitor listening sockets during analysis:

- Track port bindings
- Monitor service startup
- Detect network service changes

**File System Monitoring**::

   sandroid --show-deleted
   sandroid -d

Perform full filesystem checks to reveal deleted files:

- Deep filesystem analysis
- Detect file deletion patterns
- Higher resource usage but comprehensive coverage

**Screenshot Capture**::

   sandroid --screenshot 5

Take screenshots every N seconds:

- Visual documentation of analysis
- Capture UI changes and behaviors
- Useful for malware analysis and app testing

Specialized Analysis
--------------------

**Hash Calculation**::

   sandroid --hash

Generate MD5 hashes for all changed and new files:

- File integrity verification
- Change detection
- Evidence preservation

**APK Enumeration**::

   sandroid --apk

List all APKs from the emulator with their hashes:

- Inventory installed applications
- Track APK modifications
- Generate application manifest

**TrigDroid Integration**::

   sandroid --trigdroid com.malware.package

Execute malware triggers for the specified package:

- Automated malware activation
- Comprehensive trigger pattern execution
- Behavioral analysis automation

**TrigDroid Configuration**::

   sandroid --trigdroid-ccf I    # Interactive mode
   sandroid --trigdroid-ccf D    # Create default config

Configure TrigDroid Component Coverage Framework:

- ``I`` - Interactive configuration mode
- ``D`` - Generate default configuration file

Network Configuration
---------------------

**Network Speed Simulation**::

   sandroid --degrade-network

Simulate slower network conditions (UMTS/3G):

- Lower bandwidth simulation
- Increased latency
- Test app behavior under poor network conditions

**Whitelist Filtering**::

   sandroid --whitelist /path/to/whitelist.txt

Exclude specific files/paths from analysis results:

- Filter out known system noise
- Focus on application-specific changes
- Customize analysis scope

Advanced Features
-----------------

**AI Analysis**::

   sandroid --ai

Enable AI-powered analysis and summarization:

- Automated threat detection
- Behavioral pattern analysis
- Natural language analysis summaries
- Requires AI optional dependencies

**PDF Report Generation**::

   sandroid --report

Generate comprehensive PDF reports:

- Professional forensic reports
- Visual analysis summaries
- Exportable documentation

**Interactive Mode**::

   sandroid --interactive
   sandroid -i

Start in interactive menu mode (same as running ``sandroid`` without options).

Common Usage Patterns
----------------------

**Basic Analysis**::

   # Simple 2-run analysis
   sandroid --number 2

   # With output file
   sandroid -n 2 -f my_analysis.json

**Comprehensive Analysis**::

   # Full feature analysis
   sandroid --network --sockets --screenshot 3 --hash --apk --report

   # With AI analysis
   sandroid --network --ai --report --screenshot 5

**Malware Analysis**::

   # Automated malware analysis
   sandroid --trigdroid com.malware.sample \
            --network --screenshot 2 \
            --show-deleted --hash \
            --ai --report

   # Manual malware analysis
   sandroid --network --sockets --screenshot 3 \
            --avoid-strong-noise-filter \
            --show-deleted --hash

**App Development Testing**::

   # Performance testing
   sandroid --number 1 --screenshot 5 --degrade-network

   # Feature testing
   sandroid --network --sockets --apk

**Security Audit**::

   # Complete security analysis
   sandroid --network --sockets --show-deleted \
            --hash --apk --ai --report \
            --avoid-strong-noise-filter

Configuration Integration
-------------------------

Command-line options override configuration file settings::

   # Config file sets number_of_runs = 2
   # This overrides to 5 runs
   sandroid --config analysis.toml --number 5

**Environment Variables**

All options can be set via environment variables::

   export SANDROID_LOG_LEVEL=DEBUG
   export SANDROID_ANALYSIS__NUMBER_OF_RUNS=3
   export SANDROID_ANALYSIS__MONITOR_NETWORK=true
   sandroid

**Priority Order**

1. Command-line arguments (highest priority)
2. Environment variables
3. Configuration file
4. Default values (lowest priority)

Output and Results
------------------

**Result Files**

- **Primary Output**: JSON file with complete analysis results
- **Raw Data**: ``results/`` directory with detailed artifacts
- **Screenshots**: Captured device screenshots (if enabled)
- **Network Capture**: PCAP files (if network monitoring enabled)
- **Logs**: Detailed execution logs in ``~/.cache/sandroid/logs/``

**JSON Result Structure**::

   {
     "timestamp": "2024-08-27T10:30:00Z",
     "configuration": {...},
     "Changed Files": [...],
     "New Files": [...],
     "Deleted Files": [...],
     "Network": {...},
     "Processes": [...],
     "APKs": [...],
     "AI Analysis": {...}
   }

Batch Processing
----------------

**Script Integration**::

   #!/bin/bash

   # Batch analysis of multiple APKs
   for apk in *.apk; do
       echo "Analyzing $apk..."
       adb install "$apk"
       sandroid --number 2 --network --report \
                -f "results_$(basename "$apk" .apk).json"
       adb uninstall "$(aapt dump badging "$apk" | grep package | cut -d"'" -f2)"
   done

**CI/CD Integration**::

   # In your CI pipeline
   - name: Android Security Analysis
     run: |
       # Start emulator
       emulator -avd test_device -no-window -no-audio &
       adb wait-for-device

       # Run analysis
       sandroid --network --ai --report \
                --output-file ci_analysis_results.json

       # Archive results
       tar -czf analysis_results.tar.gz results/ *.json *.pdf

**Parallel Analysis**::

   # Multiple simultaneous analyses
   sandroid --config config1.toml -f results1.json &
   sandroid --config config2.toml -f results2.json &
   sandroid --config config3.toml -f results3.json &
   wait

Error Handling
--------------

**Exit Codes**

- ``0`` - Analysis completed successfully
- ``1`` - Analysis failed with errors
- ``2`` - Configuration or setup error

**Common Error Scenarios**::

   # Handle device not found
   sandroid --network || echo "Analysis failed - check device connection"

   # Timeout protection
   timeout 1800 sandroid --network --screenshot 5

   # Resource cleanup
   trap 'kill $(jobs -p)' EXIT
   sandroid --network &

Performance Optimization
------------------------

**Resource Management**::

   # Lightweight analysis
   sandroid --number 1 --no-processes

   # High-performance analysis
   sandroid --avoid-strong-noise-filter --number 1

**Storage Optimization**::

   # Minimal storage usage
   sandroid --number 2  # No screenshots, no network capture

   # Custom output location
   sandroid --config <(echo 'paths.results_path="/tmp/analysis"')

Debugging and Troubleshooting
------------------------------

**Debug Mode**::

   sandroid --loglevel DEBUG --network

**Verbose Output**::

   SANDROID_LOG_LEVEL=DEBUG sandroid --network 2>&1 | tee analysis.log

**Common Issues**

1. **Device not found**::

   # Check ADB connection
   adb devices
   sandroid --loglevel DEBUG

2. **Permission errors**::

   # Ensure device is rooted
   adb shell su -c 'id'

3. **Frida issues**::

   # Test Frida separately
   frida-ps -U

4. **Configuration problems**::

   # Validate configuration
   sandroid-config validate

**Log Analysis**::

   # Find specific errors
   grep -i error ~/.cache/sandroid/logs/sandroid.log

   # Monitor real-time
   tail -f ~/.cache/sandroid/logs/sandroid.log

Integration Examples
--------------------

**Jenkins Pipeline**::

   pipeline {
       agent any
       stages {
           stage('Android Analysis') {
               steps {
                   sh '''
                       sandroid --network --ai --report \
                                --file analysis_${BUILD_NUMBER}.json
                   '''
                   archiveArtifacts artifacts: '*.json,*.pdf,results/**'
               }
           }
       }
   }

**Docker Integration**::

   # Dockerfile
   FROM sandroid:latest
   COPY config.toml /app/
   CMD ["sandroid", "--config", "/app/config.toml", "--network", "--report"]

**GitHub Actions**::

   - name: Run Sandroid Analysis
     uses: actions/setup-python@v2
     with:
       python-version: '3.10'
   - run: |
       pip install sandroid[ai]
       sandroid --network --ai --report
   - uses: actions/upload-artifact@v2
     with:
       name: analysis-results
       path: |
         *.json
         *.pdf
         results/

Best Practices
--------------

1. **Always use multiple runs** (``--number 2`` minimum) for accurate change detection
2. **Enable network monitoring** (``--network``) for comprehensive analysis
3. **Use configuration files** for consistent analysis parameters
4. **Archive results** in structured directories with timestamps
5. **Monitor resource usage** during analysis to avoid system overload
6. **Validate configurations** before batch processing
7. **Use appropriate log levels** for your use case (INFO for production, DEBUG for troubleshooting)

See Also
--------

- :doc:`configuration` - Detailed configuration options
- :doc:`interactive_mode` - Interactive analysis interface
- :doc:`troubleshooting` - Common issues and solutions
- :doc:`api/core` - Python API for custom automation