Skip to content

Security: JMR-dev/android_file_handler_adb

Security

Report a vulnerability

docs/SECURITY.md

Security Design Document

Overview

This document describes the security design, threat model, and known limitations of the Android File Handler ADB application. The application implements defense-in-depth security controls to protect against command injection, path traversal, and other common attack vectors.

Threat Model

Assets Protected

  1. Local Filesystem: User's files and directories on the host system
  2. Android Device Data: Files and directories on the connected Android device
  3. System Integrity: Protection against arbitrary command execution
  4. User Privacy: Prevention of unauthorized access to sensitive files

Threat Actors

  1. Malicious Files: Specially-crafted filenames designed to exploit command injection vulnerabilities
  2. Compromised Android Device: A device that may attempt to exploit the host system through malicious file metadata
  3. Malicious Input: User-provided paths or device IDs containing attack payloads
  4. Man-in-the-Middle: Attacks during ADB platform-tools download (partial mitigation)

Attack Vectors

1. Command Injection

Description: Attacker attempts to inject shell commands through user-controlled inputs (paths, device IDs, filenames).

Mitigations:

  • Input sanitization with regex-based dangerous character detection
  • Subprocess execution without shell=True (arguments passed as list, not string)
  • Validation of all user-controlled inputs before use
  • Specific error messages for rejected inputs

Examples Blocked:

/sdcard/file; rm -rf /
/sdcard/$(whoami)
device123; malicious_command

2. Path Traversal

Description: Attacker attempts to access files outside of intended directories using .. or symbolic links.

Mitigations:

  • Path normalization using os.path.normpath() and os.path.realpath()
  • Symlink resolution to detect symlink-based escape attempts
  • Base directory validation for local paths
  • Rejection of null bytes in paths

Examples Blocked:

/tmp/safe/../../../etc/passwd
[symlink from /tmp/safe/escape -> /etc/]
/tmp/file\x00.txt

3. Zip Bomb / Archive Bomb

Description: Maliciously crafted compressed files that expand to consume excessive disk space.

Mitigations:

  • Size limit checks on downloaded files
  • Extraction size validation
  • Disk space checks before download

Implementation: See src/core/platform_tools.py download validation.

4. Redirect Attacks

Description: Malicious redirects during platform-tools download that could lead to downloading malware.

Mitigations:

  • URL validation for redirects
  • HTTPS enforcement
  • Domain validation for official sources

Implementation: See src/core/platform_tools.py download validation.

Security Controls

Input Sanitization Functions

sanitize_path_component(component: str)

Purpose: Validates individual path components (filenames, directory names).

Checks:

  • Non-empty string
  • No null bytes (\x00)
  • No shell metacharacters: ;, |, &, $, `, \n, \r, >, <, (, ), {, }, [, ], !
  • No command substitution patterns: $(, ${

Usage: Used for validating individual filename components.

sanitize_android_path(path: str)

Purpose: Validates full paths on Android devices.

Checks:

  • Non-empty string
  • No null bytes (\x00)
  • No dangerous patterns: ;, |, &, `, \n, \r, $(, ${, &&, ||, >>
  • Allows: Spaces, Unicode characters, forward slashes, dots

Usage: Used for all Android device paths before passing to ADB commands.

Rationale: Android filesystems support Unicode and spaces in filenames. We only block patterns that could enable command injection.

sanitize_local_path(path: str, base_dir: Optional[str])

Purpose: Validates and normalizes local filesystem paths.

Checks:

  • Non-empty string
  • No null bytes (\x00)
  • Path normalization via os.path.normpath(os.path.realpath())
  • Symlink resolution to detect escapes
  • Optional base directory containment validation

Usage: Used for local filesystem paths, especially when restricting operations to specific directories.

Rationale: Using realpath() instead of abspath() ensures symbolic links are resolved before validation, preventing symlink-based path traversal.

validate_device_id(device_id: str)

Purpose: Validates Android device IDs.

Checks:

  • Non-empty string
  • Alphanumeric characters, dots, colons, underscores, hyphens only
  • No shell metacharacters
  • No spaces

Usage: Validates device IDs before using in ADB commands with -s flag.

Valid Examples:

ABC123DEF456          (serial number)
192.168.1.100:5555   (network device)
emulator-5554        (emulator)

Subprocess Execution

Safe Pattern:

# SAFE: Arguments as list, no shell=True
subprocess.run([adb_path, "-s", device_id, "shell", "ls", path])

Unsafe Pattern (NOT USED):

# UNSAFE: Shell=True enables command injection
subprocess.run(f"adb -s {device_id} shell ls {path}", shell=True)

Implementation: All ADB commands use argument lists without shell=True, preventing shell interpretation of metacharacters.

Error Handling

Logging: Validation failures are logged with specific error messages to help detect attack attempts and debug legitimate issues.

User Feedback: Failed operations return descriptive error messages indicating why paths or device IDs were rejected.

Silent Failures: Removed in favor of explicit logging (see src/core/adb_manager.py methods list_files() and get_file_info()).

Known Limitations

1. Android Device Trust

Limitation: The application trusts the connected Android device to return valid data.

Risk: A compromised or malicious device could return crafted data through ADB responses.

Mitigation: Input sanitization is applied to user-provided inputs, but responses from adb shell commands are parsed but not fully sanitized. The subprocess argument list pattern prevents command injection even with malicious device responses.

Residual Risk: Low. Device responses are parsed but not executed as commands.

2. ADB Binary Trust

Limitation: The application trusts the ADB binary downloaded from Google's servers.

Risk: If download is intercepted (MITM) or if Google's servers are compromised, malicious ADB binary could be installed.

Mitigation:

  • HTTPS is used for downloads
  • URL validation for redirects
  • Downloads only from official Google domains

Residual Risk: Low to Medium. Consider adding SHA-256 hash verification in future versions.

3. Local Filesystem Permissions

Limitation: The application runs with the same permissions as the user who launched it.

Risk: If user has write access to system directories, the application could be used to overwrite important files (though not through exploitation).

Mitigation: Application uses standard OS permissions. Users should not run the application with elevated privileges unless necessary.

Residual Risk: Low. This is standard behavior for desktop applications.

4. Unicode Normalization

Limitation: Unicode characters are allowed but not normalized (e.g., no NFC/NFD conversion).

Risk: Different Unicode representations of the same visual character could bypass filters or cause confusion.

Mitigation: Characters are checked for dangerous patterns regardless of Unicode form.

Residual Risk: Very Low. Path validation is performed before use.

5. Race Conditions

Limitation: Time-of-check to time-of-use (TOCTOU) race conditions are possible with filesystem operations.

Risk: A symlink or file could be changed between validation and use.

Mitigation: Paths are validated immediately before use. Symlinks are resolved during validation.

Residual Risk: Very Low. Window for exploitation is extremely small and requires local access.

6. Platform-Specific Behavior

Limitation: Path handling differs between Windows, Linux, and macOS.

Risk: Platform-specific path normalization could behave unexpectedly.

Mitigation:

  • Use of os.path functions for cross-platform compatibility
  • Comprehensive tests for different path formats
  • Separate handling for Windows root paths in file transfer module

Residual Risk: Low. Extensive testing covers common scenarios.

Security Testing

Test Coverage

The security validation suite includes tests for:

  1. Command Injection Prevention

    • Shell metacharacters in paths
    • Command substitution patterns
    • Backtick substitution
    • Newline injection

  2. Path Traversal Prevention

    • .. sequences
    • Absolute path escapes
    • Symlink-based escapes
    • Null byte injection

  3. Unicode Handling

    • Chinese, Russian, Arabic, Emoji characters
    • Accented characters
    • Mixed Unicode and spaces

  4. Edge Cases

    • Very long paths (100+ directory levels)
    • Very long filenames (255+ characters)
    • Paths with multiple dots
    • Hidden files (leading dot)

  5. Cross-Platform

    • Windows-style paths (C:\Users\...)
    • Unix-style paths (/tmp/...)
    • Mixed path separators
    • Platform-specific normalization

  6. Device ID Validation

    • Serial numbers
    • Network addresses with ports
    • Emulator IDs
    • Invalid characters

Test Location

All security tests are located in: tests/utils/test_security_utils.py

Run tests with:

poetry run pytest tests/utils/test_security_utils.py -v

Security Maintenance

Regular Reviews

Security controls should be reviewed:

  • When adding new features that accept user input
  • When modifying path handling or subprocess execution
  • After discovering vulnerabilities in similar applications
  • At least annually

Dependency Updates

Keep dependencies updated to patch security vulnerabilities:

poetry update
poetry run pytest  # Verify no regressions

Vulnerability Reporting

Security issues should be reported via GitHub Issues with the security label.

Compliance and Best Practices

OWASP Guidelines

This implementation follows OWASP recommendations for:

  • Input validation (positive security model where possible)
  • Output encoding (subprocess argument lists)
  • Command injection prevention
  • Path traversal prevention

Python Security Best Practices

  • No use of eval(), exec(), or compile()
  • No shell=True in subprocess calls
  • Type hints for all security-critical functions
  • Comprehensive error handling

Defense in Depth

Multiple layers of security:

  1. Input validation (first line of defense)
  2. Subprocess argument lists (prevent shell interpretation)
  3. Path normalization (prevent traversal)
  4. Symlink resolution (prevent escapes)
  5. Logging (detection and debugging)

Future Enhancements

Recommended Improvements

  1. SHA-256 Hash Verification: Verify ADB binary downloads against known-good hashes
  2. Code Signing: Sign application binaries for distribution
  3. Sandboxing: Consider running ADB operations in a restricted environment
  4. Rate Limiting: Prevent brute-force attempts on path validation
  5. Audit Logging: Enhanced logging for security-relevant events
  6. Unicode Normalization: Normalize Unicode strings to prevent bypass attempts

Not Recommended

  1. Filename Whitelisting: Too restrictive for international users
  2. Path Length Limits: Android supports long paths; artificial limits harm usability
  3. Blocking All Special Characters: Many legitimate filenames use special characters

References

Version History

  • v1.0 (2025-10-15): Initial security design documentation
    • Command injection prevention
    • Path traversal prevention
    • Symlink resolution
    • Comprehensive test coverage
    • Error logging for validation failures

There aren’t any published security advisories