342 lines
12 KiB
Markdown
342 lines
12 KiB
Markdown
# 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**:
|
|
```python
|
|
# SAFE: Arguments as list, no shell=True
|
|
subprocess.run([adb_path, "-s", device_id, "shell", "ls", path])
|
|
```
|
|
|
|
**Unsafe Pattern** (NOT USED):
|
|
```python
|
|
# 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:
|
|
```bash
|
|
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:
|
|
```bash
|
|
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
|
|
|
|
- [OWASP Command Injection](https://owasp.org/www-community/attacks/Command_Injection)
|
|
- [OWASP Path Traversal](https://owasp.org/www-community/attacks/Path_Traversal)
|
|
- [CWE-78: OS Command Injection](https://cwe.mitre.org/data/definitions/78.html)
|
|
- [CWE-22: Path Traversal](https://cwe.mitre.org/data/definitions/22.html)
|
|
- [Android File System Permissions](https://source.android.com/docs/core/permissions/filesystem)
|
|
|
|
## 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
|