trigdroid 2.0.0__py3-none-any.whl

trigdroid-2.0.0.dist-info/METADATA

@@ -0,0 +1,1150 @@
+Metadata-Version: 2.4
+Name: trigdroid
+Version: 2.0.0
+Summary: Android Sandbox Payload Trigger Framework for Security Research
+Project-URL: Homepage, https://github.com/fkie-cad/Sandroid_TrigDroid
+Project-URL: Documentation, https://fkie-cad/Sandroid_TrigDroid
+Project-URL: Repository, https://github.com/fkie-cad/Sandroid_TrigDroid.git
+Project-URL: Bug Tracker, https://github.com/fkie-cad/Sandroid_TrigDroid/issues
+Project-URL: Changelog, https://github.com/fkie-cad/Sandroid_TrigDroid/blob/main/CHANGELOG.md
+Author-email: Daniel Baier <daniel.baier@fkie.fraunhofer.de>, Simon Hüsch <simon.huesch@smail.inf.h-brs.de>
+Maintainer-email: TrigDroid Team <contact@trigdroid.org>
+License: MIT License
+        
+        Copyright (c) 2025 FKIE-CAD
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: android,frida,malware-analysis,mobile-security,penetration-testing,reverse-engineering,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Other Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: JavaScript
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: click>=8.1.0
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: termcolor>=2.3.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: isort>=5.12.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
+Requires-Dist: pylint>=2.17.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
+Requires-Dist: types-requests>=2.31.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-click>=0.8.0; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.0.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.22.0; extra == 'docs'
+Provides-Extra: frida
+Requires-Dist: frida-tools>=12.0.0; extra == 'frida'
+Requires-Dist: frida>=16.0.0; extra == 'frida'
+Provides-Extra: full
+Requires-Dist: appium-python-client>=3.0.0; extra == 'full'
+Requires-Dist: frida-tools>=12.0.0; extra == 'full'
+Requires-Dist: frida>=16.0.0; extra == 'full'
+Requires-Dist: numpy>=1.24.0; extra == 'full'
+Requires-Dist: pillow>=9.0.0; extra == 'full'
+Requires-Dist: selenium>=4.0.0; extra == 'full'
+Provides-Extra: lint
+Requires-Dist: black>=23.0.0; extra == 'lint'
+Requires-Dist: isort>=5.12.0; extra == 'lint'
+Requires-Dist: mypy>=1.0.0; extra == 'lint'
+Requires-Dist: pylint>=2.17.0; extra == 'lint'
+Requires-Dist: ruff>=0.1.0; extra == 'lint'
+Provides-Extra: test
+Requires-Dist: coverage[toml]>=7.0.0; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# TrigDroid 🤖
+
+**Android Sandbox Payload Trigger Framework for Security Research**
+
+[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)]()
+[![Coverage](https://img.shields.io/badge/coverage-90%25-green.svg)]()
+
+TrigDroid is a modern Android security testing framework designed to trigger payloads in potentially malicious Android applications through sophisticated environmental manipulation. Built for security researchers, malware analysts, and penetration testers, it provides both a powerful command-line interface and a flexible Python API. It is part of the Android Sandbox Sandroid.
+
+## 🎯 Key Features
+
+- **🔍 Payload Trigger Detection**: Sophisticated environmental manipulation to trigger hidden malicious behaviors
+- **📱 Multi-Device Support**: Works with physical devices and emulators
+- **🔧 Dual Interface**: Both CLI and Python API for maximum flexibility  
+- **⚡ Frida Integration**: Advanced runtime instrumentation with TypeScript hooks
+- **🌐 Network Manipulation**: WiFi, mobile data, and Bluetooth state changes
+- **📊 Sensor Simulation**: Accelerometer, gyroscope, light, pressure, and more
+- **🔋 Battery Simulation**: Dynamic battery level and charging state changes
+- **📈 Comprehensive Reporting**: Detailed test results with timing and metrics
+- **🏗️ Modern Architecture**: Built with SOLID principles and type safety
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Install TrigDroid with full features
+pip install trigdroid[full]
+
+# Install minimal version
+pip install trigdroid
+
+# Install with specific features
+pip install trigdroid[frida]  # Just Frida support
+pip install trigdroid[dev]    # Development tools
+```
+
+### Prerequisites
+
+- **Python 3.9+**
+- **Android Debug Bridge (ADB)**
+- **Android device or emulator** with USB debugging enabled
+- **Node.js** (optional, for TypeScript Frida hooks)
+
+### Basic Usage
+
+```bash
+# Test an Android app with basic payload triggers
+trigdroid -p com.example.app
+
+# Advanced testing with sensor manipulation
+trigdroid -p com.suspicious.app --acceleration 8 --battery 3 --wifi
+
+# List available Android devices
+trigdroid devices
+
+# Get detailed app information
+trigdroid info com.example.app
+```
+
+## 📋 Command Line Interface
+
+### Core Commands
+
+```bash
+# Basic app analysis
+trigdroid -p <package_name>
+
+# Advanced options
+trigdroid -p com.example.app \
+  --acceleration 5 \           # Sensor elaborateness (0-10)
+  --battery 3 \               # Battery rotation level (0-4)
+  --wifi \                    # Enable WiFi state changes
+  --data \                    # Enable mobile data changes
+  --frida \                   # Enable Frida hooks
+  --timeout 600               # Test timeout in seconds
+```
+
+### Device Management
+
+```bash
+# List all connected devices
+trigdroid devices
+
+# Get detailed device information
+trigdroid devices --verbose
+
+# Test specific device
+trigdroid -p com.example.app -d emulator-5554
+```
+
+### Configuration Files
+
+```bash
+# Create configuration template
+trigdroid --create-config default
+
+# Use configuration file
+trigdroid test-config config.yaml
+```
+
+### Example Configuration (config.yaml)
+
+```yaml
+package: "com.example.app"
+acceleration: 5
+sensors:
+  - accelerometer
+  - gyroscope
+  - light
+network_states:
+  - wifi
+  - data
+battery_rotation: 3
+frida_hooks: true
+timeout: 300
+verbose: true
+```
+
+## 🐍 Python API
+
+### Simple Usage
+
+```python
+from trigdroid import quick_test
+
+# Quick test with default settings
+result = quick_test("com.example.app")
+print(f"Test successful: {result.success}")
+```
+
+### Advanced Usage
+
+```python
+from trigdroid import TrigDroidAPI, TestConfiguration
+
+# Create detailed configuration
+config = TestConfiguration(
+    package="com.suspicious.app",
+    acceleration=8,                    # High sensor activity
+    sensors=["accelerometer", "gyroscope", "light"],
+    network_states=["wifi", "data"],   # Network state changes
+    battery_rotation=3,                # Battery level simulation
+    frida_hooks=True,                  # Enable runtime instrumentation
+    timeout=600,                       # 10 minute timeout
+    verbose=True
+)
+
+# Run comprehensive test
+with TrigDroidAPI() as trigdroid:
+    trigdroid.configure(config)
+    result = trigdroid.run_tests()
+    
+    # Analyze results
+    if result.success:
+        print(f"✅ Test completed in {result.duration_seconds:.1f}s")
+        print(f"📊 Tests run: {result.total_tests}")
+        print(f"✅ Passed: {result.passed_tests}")
+        print(f"❌ Failed: {result.failed_tests}")
+    else:
+        print(f"❌ Test failed: {result.error}")
+        
+    # Check for suspicious behavior
+    if result.app_crashed:
+        print("⚠️  App crashed during testing")
+    if result.frida_errors:
+        print(f"🔍 Frida instrumentation issues: {result.frida_errors}")
+    
+    # Access detailed metrics
+    print(f"📱 Sensor tests: {len(result.sensor_tests_executed)}")
+    print(f"🌐 Network changes: {len(result.network_state_changes)}")
+    print(f"🔋 Background time: {result.app_background_time:.1f}s")
+```
+
+### Device Management API
+
+```python
+from trigdroid import DeviceManager, scan_devices
+
+# Scan for available devices
+devices = scan_devices()
+for device in devices:
+    print(f"Device: {device['id']} ({device['status']})")
+
+# Advanced device management
+manager = DeviceManager()
+device = manager.connect_to_device("emulator-5554")
+
+if device:
+    print(f"Connected to: {device.device_id}")
+    info = device.get_device_info()
+    print(f"Model: {info.get('model', 'Unknown')}")
+    print(f"Android: {info.get('version', 'Unknown')}")
+```
+
+### Environment Validation
+
+```python
+from trigdroid.api.quick_start import validate_environment, setup_environment
+
+# Check if environment is ready
+status = validate_environment()
+if all(status.values()):
+    print("🎉 Environment is ready!")
+else:
+    print("❌ Issues found:")
+    for check, result in status.items():
+        if not result:
+            print(f"  • {check}")
+
+# Automatically setup environment
+if setup_environment():
+    print("✅ Environment setup complete")
+```
+
+## 🔧 Advanced Features
+
+### Sensor Manipulation
+
+TrigDroid can simulate various Android sensors to trigger environment-dependent payloads:
+
+- **Accelerometer**: Motion detection triggers
+- **Gyroscope**: Rotation-based activations  
+- **Light Sensor**: Ambient light conditions
+- **Pressure**: Atmospheric pressure changes
+- **Magnetometer**: Magnetic field variations
+- **Proximity**: Near/far object detection
+
+```bash
+# Fine-tuned sensor testing
+trigdroid -p com.example.app \
+  --acceleration 7 \
+  --gyroscope 5 \
+  --light 3 \
+  --pressure 4
+```
+
+### Network State Manipulation
+
+Simulate different connectivity scenarios:
+
+```bash
+# Test with network state changes
+trigdroid -p com.example.app --wifi --data --bluetooth
+```
+
+### Frida Runtime Instrumentation
+
+TrigDroid includes sophisticated Frida hooks written in TypeScript:
+
+- **Method interception**: Hook critical Android APIs
+- **Parameter modification**: Alter method arguments and return values
+- **Behavior monitoring**: Track app interactions with system APIs
+- **Anti-analysis detection**: Identify evasion techniques
+
+### Battery and System Simulation
+
+```bash
+# Simulate battery level changes and system states
+trigdroid -p com.example.app \
+  --battery 4 \              # Maximum battery simulation
+  --background-time 30 \     # 30 seconds in background
+  --min-runtime 5            # Minimum 5 minutes runtime
+```
+
+## 📊 Understanding Results
+
+### Test Result Structure
+
+```python
+# Example result analysis
+result = api.run_tests()
+
+# Basic status
+print(f"Success: {result.success}")
+print(f"Phase: {result.phase}")  # setup, execution, teardown
+print(f"Duration: {result.duration_seconds}s")
+
+# Test statistics
+print(f"Total tests: {result.total_tests}")
+print(f"Success rate: {result.success_rate:.1f}%")
+
+# App behavior analysis
+print(f"App started: {result.app_started}")
+print(f"App crashed: {result.app_crashed}")
+print(f"Background time: {result.app_background_time}s")
+
+# Instrumentation results
+print(f"Frida hooks loaded: {result.frida_hooks_loaded}")
+print(f"Frida hooks active: {result.frida_hooks_active}")
+
+# Sensor test results
+for sensor, changed in result.sensor_values_changed.items():
+    print(f"Sensor {sensor}: {changed} value changes")
+
+# Export results
+result_dict = result.to_dict()
+summary = result.summary()  # Human-readable summary
+```
+
+### Interpreting Security Findings
+
+**🔍 Suspicious Indicators:**
+- App crashes during sensor manipulation
+- Unexpected network activity during state changes
+- Frida hook detection or evasion attempts
+- Unusual battery usage patterns
+- Background behavior changes
+
+**✅ Normal Behavior:**
+- Consistent app performance across all tests
+- No crashes or errors
+- Predictable sensor responses
+- Standard network usage patterns
+
+## 🛠️ Development and Integration
+
+### Third-Party Project Integration
+
+```python
+# In your security analysis tool
+from trigdroid import TrigDroidAPI, TestConfiguration
+
+def analyze_apk(package_name: str) -> dict:
+    """Analyze an APK for malicious behavior."""
+    config = TestConfiguration(
+        package=package_name,
+        acceleration=8,  # High intensity testing
+        timeout=600,
+        frida_hooks=True
+    )
+    
+    with TrigDroidAPI() as trigdroid:
+        result = trigdroid.run_tests()
+        
+        return {
+            "malicious": not result.success,
+            "confidence": result.success_rate,
+            "indicators": {
+                "crashed": result.app_crashed,
+                "evasion_detected": len(result.frida_errors) > 0,
+                "suspicious_network": len(result.network_state_changes) > 5
+            },
+            "report": result.summary()
+        }
+
+# Usage
+analysis = analyze_apk("com.suspicious.app")
+if analysis["malicious"]:
+    print(f"⚠️  Malicious behavior detected (confidence: {analysis['confidence']:.1f}%)")
+```
+
+### CI/CD Integration
+
+```yaml
+# .github/workflows/security-scan.yml
+name: Android Security Scan
+
+on: [push, pull_request]
+
+jobs:
+  security-scan:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v3
+    
+    - name: Setup Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.9'
+        
+    - name: Install TrigDroid
+      run: pip install trigdroid[frida]
+      
+    - name: Setup Android Emulator
+      uses: reactivecircus/android-emulator-runner@v2
+      with:
+        api-level: 29
+        script: |
+          adb devices
+          trigdroid devices
+          
+    - name: Security Analysis
+      run: |
+        trigdroid -p com.example.testapp \
+          --acceleration 5 \
+          --timeout 300 \
+          --frida
+```
+
+## 🔒 Security Considerations
+
+**⚠️ Important**: TrigDroid is designed for **defensive security research** and **malware analysis** only.
+
+### Ethical Usage Guidelines
+
+- ✅ **Authorized Testing**: Only test applications you own or have explicit permission to analyze
+- ✅ **Research Purposes**: Use for academic research, security analysis, and malware detection
+- ✅ **Controlled Environment**: Run tests in isolated environments or sandboxes
+- ❌ **No Malicious Use**: Do not use to enhance or create malicious capabilities
+- ❌ **No Unauthorized Testing**: Do not test third-party applications without permission
+
+### Privacy and Legal Compliance
+
+- Ensure compliance with local laws and regulations
+- Respect application privacy policies and terms of service
+- Use appropriate data handling and retention practices
+- Consider ethical implications of security research
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+**Device Not Found**
+```bash
+# Check ADB connection
+adb devices
+
+# Restart ADB server
+adb kill-server && adb start-server
+
+# Enable USB debugging on device
+# Developer options → USB debugging
+```
+
+**Frida Hooks Fail to Load**
+```bash
+# Check Frida installation
+python -c "import frida; print(frida.__version__)"
+
+# Reinstall Frida
+pip install --upgrade frida frida-tools
+
+# Check device architecture
+adb shell getprop ro.product.cpu.abi
+```
+
+**TypeScript Compilation Errors**
+```bash
+# Check Node.js installation
+node --version && npm --version
+
+# Rebuild TypeScript hooks
+cd frida-hooks
+rm -rf node_modules dist
+npm install && npm run build
+```
+
+**Permission Errors**
+```bash
+# Grant app permissions manually
+adb shell pm grant com.example.app android.permission.READ_PHONE_STATE
+
+# Use TrigDroid's permission management
+trigdroid -p com.example.app --grant-permission android.permission.CAMERA
+```
+
+### Getting Help
+
+- **Documentation**: Full documentation at [docs.trigdroid.org](https://docs.trigdroid.org)
+- **Issues**: Report bugs at [GitHub Issues](https://github.com/trigdroid/trigdroid/issues)
+- **Discussions**: Join the community at [GitHub Discussions](https://github.com/trigdroid/trigdroid/discussions)
+
+## 🤝 Contributing
+
+We welcome contributions from the security research community!
+
+```bash
+# Development setup
+git clone https://github.com/trigdroid/trigdroid.git
+cd trigdroid
+pip install -e ".[dev]"
+
+# Run tests
+pytest tests/
+
+# Code quality checks
+black src/ tests/
+mypy src/
+ruff check src/ tests/
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.
+
+## 📄 License
+
+TrigDroid is released under the [MIT License](LICENSE). See LICENSE file for details.
+
+## 🛠️ Development Guide
+
+### Modern Architecture Overview
+
+TrigDroid has been completely refactored following **SOLID principles** with a clean dual-layer architecture:
+
+```
+├── src/                   # 🆕 New Refactored Code (SOLID Architecture)
+│   ├── trigdroid/          # Modern Public API Layer (lowercase)
+│   │   ├── api/            # External interface with context managers
+│   │   │   ├── main.py     # TrigDroidAPI class
+│   │   │   ├── config.py   # Type-safe TestConfiguration
+│   │   │   ├── results.py  # Comprehensive TestResult classes
+│   │   │   ├── devices.py  # Device management wrapper
+│   │   │   ├── runners.py  # Test runner wrapper
+│   │   │   └── quick_start.py  # Convenience functions
+│   │   ├── cli/            # Rich CLI interface using Click
+│   │   │   └── main.py     # Modern CLI with subcommands
+│   │   ├── core/           # Core utilities and enums
+│   │   │   ├── enums.py    # Type-safe enumerations
+│   │   │   └── cleanup.py  # Resource management
+│   │   └── exceptions.py   # Exception hierarchy
+│   └── TrigDroid_Infrastructure/  # 🏗️ Infrastructure Layer (SOLID)
+│       ├── interfaces/     # Protocol-based abstractions
+│       │   └── __init__.py # ILogger, ITestRunner, IAndroidDevice, etc.
+│       ├── infrastructure/ # Dependency injection + implementations
+│       │   ├── dependency_injection.py  # DI container
+│       │   ├── configuration.py         # Config providers
+│       │   ├── logging.py              # Logger implementations
+│       │   └── android.py              # Device management
+│       ├── application/    # Application orchestration
+│       │   └── orchestrator.py # Main workflow coordinator
+│       └── test_runners/   # Test execution implementations
+├── src/                    # 🏛️ Legacy Code (Original Implementation)
+│   └── TrigDroid/          # Legacy TrigDroid (preserved for compatibility)
+│       ├── logger/         # Original logging utilities
+│       ├── interaction/    # Legacy UI components  
+│       ├── utils/          # Legacy utility functions
+│       ├── frida/          # Legacy JavaScript hooks
+│       └── ...             # Other legacy components
+├── frida-hooks/            # 🔧 TypeScript Frida Hooks (New)
+│   ├── main.ts            # Hook entry point
+│   ├── hooks/             # Individual hook modules
+│   │   ├── android-sensors.ts
+│   │   └── android-build.ts
+│   ├── types.ts           # TypeScript type definitions
+│   ├── utils.ts           # Common hook utilities
+│   ├── package.json       # Node.js build configuration
+│   └── tsconfig.json      # TypeScript compiler settings
+├── scripts/               # 🚀 Build and installation scripts
+│   ├── build.py          # Cross-platform build script
+│   └── install.sh        # Automated installation
+├── pyproject.toml        # Modern Python packaging (PEP 621)
+└── Makefile             # Development workflow commands
+```
+
+### SOLID Principles Implementation
+
+#### **1. Single Responsibility Principle**
+Each class has one reason to change:
+- `AndroidDevice`: Only handles device operations
+- `StandardLogger`: Only handles logging
+- `SensorTestRunner`: Only executes sensor tests
+
+#### **2. Open/Closed Principle**
+Extend functionality without modifying existing code:
+```python
+# Add new test runner without changing existing ones
+class CustomTestRunner(TestRunnerBase):
+    def can_run(self, test_type: str) -> bool:
+        return test_type == "custom"
+        
+    def _execute_internal(self, context: ITestContext) -> TestResult:
+        # Custom test logic
+        return TestResult.SUCCESS
+
+# Register in DI container
+container.register_transient(ITestRunner, CustomTestRunner, "custom")
+```
+
+#### **3. Liskov Substitution Principle**
+All implementations follow their interfaces:
+```python
+# Any ILogger implementation works seamlessly
+logger: ILogger = StandardLogger()  # or FilteredLogger()
+logger.info("Test message")  # Works the same way
+```
+
+#### **4. Interface Segregation Principle**
+Small, focused interfaces instead of large monolithic ones:
+```python
+class ILogger(Protocol):
+    def debug(self, message: str) -> None: ...
+    def info(self, message: str) -> None: ...
+    
+class IConfigurationProvider(Protocol):
+    def get_value(self, key: str) -> ConfigValue: ...
+    def set_value(self, key: str, value: ConfigValue) -> None: ...
+```
+
+#### **5. Dependency Inversion Principle**
+Depend on abstractions, inject dependencies:
+```python
+class SensorTestRunner(TestRunnerBase):
+    def __init__(self, logger: ILogger, device: IAndroidDevice):
+        super().__init__(logger)
+        self._device = device  # Injected dependency
+```
+
+### Development Environment Setup
+
+#### **Quick Development Setup**
+```bash
+# 1. Clone and setup development environment
+git clone https://github.com/trigdroid/trigdroid.git
+cd trigdroid
+
+# 2. Use our automated installer
+./scripts/install.sh --mode dev
+
+# 3. Alternative: Manual setup
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+pip install -e ".[full,dev,test,docs]"
+
+# 4. Build TypeScript hooks
+cd frida-hooks
+npm install && npm run build
+cd ..
+
+# 5. Verify installation
+trigdroid --version
+pytest tests/ -v
+```
+
+#### **Development Workflow Commands**
+```bash
+# Development commands (see Makefile)
+make setup-dev-env        # Initial environment setup
+make dev-install          # Install in development mode
+make build               # Build all components (Python + TypeScript)
+
+# Code quality
+make format              # Auto-format with black + isort
+make lint               # Type checking with mypy + ruff
+make check              # Run all quality checks
+make pre-commit         # Format + lint + fast tests
+
+# Testing
+make test               # All tests
+make test-unit          # Unit tests only
+make test-integration   # Integration tests
+make test-fast          # Skip slow tests
+make coverage           # Generate coverage report
+
+# Build and distribution
+make package            # Build wheel/sdist
+make hooks              # Build TypeScript hooks only
+make clean              # Clean build artifacts
+```
+
+### Adding New Features
+
+#### **1. Create New Test Runner**
+```python
+# src2/TrigDroid_Infrastructure/test_runners/custom_test_runner.py  
+from ..interfaces import ITestRunner, ITestContext, TestResult, TestRunnerBase
+
+class CustomTestRunner(TestRunnerBase):
+    """Example custom test runner."""
+    
+    def can_run(self, test_type: str) -> bool:
+        return test_type == "custom"
+    
+    def _execute_internal(self, context: ITestContext) -> TestResult:
+        # Implement your test logic
+        self._logger.info("Running custom test")
+        
+        # Access dependencies through context
+        device = context.device
+        config = context.config
+        package = context.package_name
+        
+        # Your test implementation
+        success = self._run_custom_test(device, package)
+        
+        return TestResult.SUCCESS if success else TestResult.FAILURE
+    
+    def _run_custom_test(self, device, package) -> bool:
+        # Custom test implementation
+        return True
+
+# Register in dependency_injection.py
+container.register_transient(ITestRunner, CustomTestRunner, "custom")
+```
+
+#### **2. Add New Configuration Provider**
+```python
+# src2/TrigDroid_Infrastructure/infrastructure/configuration.py
+class DatabaseConfigProvider(ConfigurationProviderBase):
+    """Load configuration from database."""
+    
+    def _load_configuration(self) -> Dict[str, ConfigValue]:
+        # Load from database
+        return {"custom_setting": "value"}
+
+# Register in configure_container()
+container.register_transient(IConfigurationProvider, DatabaseConfigProvider, "database")
+```
+
+#### **3. Create TypeScript Frida Hook**
+```typescript
+// frida-hooks/hooks/custom-hook.ts
+import { HookManager } from '../utils';
+
+export class CustomHook extends HookManager {
+    public hookCustomAPI(): void {
+        const SomeClass = Java.use("com.example.SomeClass");
+        
+        SomeClass.someMethod.implementation = function(...args) {
+            console.log("[TrigDroid] Custom hook triggered");
+            this.logToChangelog("SomeClass.someMethod", "original", "hooked");
+            
+            // Call original method
+            return this.someMethod.apply(this, args);
+        };
+    }
+}
+
+// Add to main.ts
+import { CustomHook } from './hooks/custom-hook';
+
+function main() {
+    const customHook = new CustomHook();
+    customHook.hookCustomAPI();
+}
+```
+
+### TypeScript Hook Development
+
+#### **Building Hooks**
+```bash
+# Build hooks automatically during pip install
+pip install -e .
+
+# Manual hook building
+cd frida-hooks
+npm install      # Install dependencies
+npm run build    # Compile TypeScript to JavaScript
+npm run watch    # Watch mode for development
+
+# Using make
+make hooks       # Build hooks only
+```
+
+#### **Hook Development Patterns**
+```typescript
+// frida-hooks/hooks/android-example.ts
+import { AndroidSensorType } from '../types';
+import { HookUtils } from '../utils';
+
+export class AndroidExampleHook {
+    private hookUtils: HookUtils;
+    
+    constructor() {
+        this.hookUtils = new HookUtils();
+    }
+    
+    public hookSensorManager(): void {
+        try {
+            const SensorManager = Java.use("android.hardware.SensorManager");
+            
+            SensorManager.getDefaultSensor.implementation = function(type) {
+                const originalSensor = this.getDefaultSensor(type);
+                
+                // Log the hook for debugging
+                this.hookUtils.logHookExecution("SensorManager.getDefaultSensor", {
+                    sensorType: type,
+                    timestamp: Date.now()
+                });
+                
+                // Record change in changelog
+                this.hookUtils.writeToChangelog(
+                    "SensorManager.getDefaultSensor",
+                    "original_behavior",
+                    "hooked_behavior",
+                    `Sensor type ${type} intercepted`
+                );
+                
+                return originalSensor;
+            };
+            
+        } catch (error) {
+            console.error(`[TrigDroid] Hook failed: ${error}`);
+        }
+    }
+}
+```
+
+### Dependency Injection Usage
+
+#### **Registering Services**
+```python
+# In configure_container()
+from .my_service import MyService
+
+# Singleton (same instance every time)
+container.register_singleton(IMyService, MyService)
+
+# Transient (new instance every time)  
+container.register_transient(IMyService, MyService)
+
+# Factory function
+container.register_singleton(IMyService, lambda: MyService(config="custom"))
+
+# Specific instance
+container.register_instance(IMyService, my_service_instance)
+```
+
+#### **Resolving Dependencies**
+```python
+# Method 1: Through container
+container = configure_container()
+logger = container.resolve(ILogger)
+
+# Method 2: Service Locator (global access)
+ServiceLocator.set_container(container)
+logger = ServiceLocator.get_service(ILogger)
+
+# Method 3: Constructor injection
+@inject(logger=ILogger, device=IAndroidDevice)
+class MyTestRunner:
+    def __init__(self, logger: ILogger, device: IAndroidDevice):
+        self._logger = logger
+        self._device = device
+```
+
+### Code Quality Standards
+
+#### **Type Safety**
+```python
+# Use type hints everywhere
+def process_config(config: TestConfiguration) -> TestResult:
+    return TestResult.SUCCESS
+
+# Use protocols for interfaces
+class IMyService(Protocol):
+    def do_something(self, value: str) -> bool: ...
+
+# Use enums for constants
+class TestPhase(Enum):
+    SETUP = "setup"
+    EXECUTION = "execution"
+    TEARDOWN = "teardown"
+```
+
+#### **Error Handling**
+```python
+# Proper exception hierarchy
+class TrigDroidException(Exception):
+    """Base exception for TrigDroid."""
+    pass
+
+class DeviceConnectionError(TrigDroidException):
+    """Device connection failed."""
+    pass
+
+# Use try/catch with specific exceptions
+try:
+    device.connect()
+except DeviceConnectionError as e:
+    logger.error(f"Failed to connect: {e}")
+    return TestResult.FAILURE
+```
+
+#### **Logging Best Practices**
+```python
+# Use structured logging
+logger.info("Test started", extra={
+    "package": package_name,
+    "phase": "setup",
+    "timestamp": time.time()
+})
+
+# Use appropriate log levels
+logger.debug("Detailed debugging info")      # Development only
+logger.info("Important user information")    # Normal operation
+logger.warning("Something might be wrong")   # Potential issues
+logger.error("Something failed")             # Errors that don't stop execution
+logger.critical("System cannot continue")    # Fatal errors
+```
+
+### Testing Framework
+
+#### **Unit Tests**
+```python
+# tests/unit/test_sensor_runner.py
+import pytest
+from unittest.mock import Mock
+from TrigDroid_Infrastructure.test_runners import SensorTestRunner
+from TrigDroid_Infrastructure.interfaces import ILogger, ITestContext, TestResult
+
+def test_sensor_runner_success():
+    # Arrange
+    mock_logger = Mock(spec=ILogger)
+    mock_context = Mock(spec=ITestContext)
+    runner = SensorTestRunner(mock_logger)
+    
+    # Act
+    result = runner.execute(mock_context)
+    
+    # Assert
+    assert result == TestResult.SUCCESS
+    mock_logger.info.assert_called()
+```
+
+#### **Integration Tests**
+```python
+# tests/integration/test_full_workflow.py
+@pytest.mark.integration
+@pytest.mark.requires_device
+def test_full_testing_workflow(test_device):
+    """Test complete workflow with real device."""
+    config = TestConfiguration(
+        package="com.example.testapp",
+        acceleration=3,
+        timeout=60
+    )
+    
+    with TrigDroidAPI() as api:
+        api.configure(config)
+        api.set_device(test_device.device_id)
+        result = api.run_tests()
+        
+    assert result.success
+    assert result.total_tests > 0
+```
+
+### Performance Optimization
+
+#### **Fast Development Cycle**
+```bash
+# Skip TypeScript build during development
+SKIP_HOOKS=1 pip install -e .
+
+# Run only fast tests
+make test-fast
+
+# Use parallel testing
+pytest -n auto tests/
+
+# Quick format and lint check
+make pre-commit
+```
+
+#### **Build Optimization**
+```bash
+# Build only what changed
+make hooks-if-changed
+
+# Use cached dependencies
+pip install --cache-dir ~/.cache/pip -e .
+
+# Parallel hook compilation
+cd frida-hooks && npm run build:parallel
+```
+
+### Contributing Guidelines
+
+#### **Code Standards**
+- **Readable**: Code should read like well-written prose
+- **Self-documenting**: Use clear variable and function names
+- **Consistent**: Follow established patterns
+- **Simple**: Prefer simple solutions over clever ones
+- **DRY**: Extract common functionality
+- **YAGNI**: Don't over-engineer
+
+#### **Pull Request Process**
+```bash
+# 1. Development workflow
+git checkout -b feature/new-feature
+make dev-install
+make pre-commit  # Format + lint + fast tests
+
+# 2. Before committing
+make test        # Full test suite
+make build       # Ensure everything builds
+make check       # Final quality check
+
+# 3. Create pull request
+git push origin feature/new-feature
+# Open PR with detailed description
+```
+
+#### **Code Review Checklist**
+- [ ] Follows SOLID principles
+- [ ] Has proper type annotations
+- [ ] Includes unit tests (>90% coverage)
+- [ ] Updated documentation if needed
+- [ ] No hardcoded values or magic numbers
+- [ ] Proper error handling
+- [ ] TypeScript hooks built successfully
+- [ ] All quality checks pass
+
+### Debugging and Troubleshooting
+
+#### **Development Issues**
+```bash
+# TypeScript compilation fails
+cd frida-hooks
+rm -rf node_modules dist
+npm install && npm run build
+
+# Python import errors
+pip uninstall trigdroid
+pip install -e ".[full]"
+
+# Dependency injection issues
+# Check container registration in configure_container()
+container.has_service(IMyService)  # Should return True
+
+# Test runner not found
+# Verify registration with correct name
+container.resolve(ITestRunner, "my_runner")
+```
+
+#### **Runtime Debugging**
+```python
+# Enable debug logging
+import logging
+logging.basicConfig(level=logging.DEBUG)
+
+# Use dependency injection debug mode
+container = configure_container()
+if container.has_service(IMyService):
+    service = container.resolve(IMyService)
+    
+# Check service registration
+print(f"Registered services: {list(container._services.keys())}")
+```
+
+This development guide provides comprehensive information for contributing to and extending TrigDroid's modern architecture.
+
+## 🙏 Acknowledgments
+
+- Built on the foundation of the [Evadroid](https://github.com/evadroid/evadroid) project
+- Powered by [Frida](https://frida.re/) dynamic instrumentation toolkit
+- Uses [Click](https://click.palletsprojects.com/) for command-line interface
+- Enhanced with [Rich](https://rich.readthedocs.io/) for beautiful terminal output
+
+---
+
+**Made with ❤️ for the security research community**
+
+*TrigDroid helps security researchers and malware analysts understand and detect sophisticated Android threats through intelligent payload triggering and environmental manipulation.*

trigdroid-2.0.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+trigdroid-2.0.0.dist-info/METADATA,sha256=9pSwOrwb5-IjdLy5rL5b6lUfTeEJvlUOc35WTM6Xg9E,35985
+trigdroid-2.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+trigdroid-2.0.0.dist-info/entry_points.txt,sha256=X1hWIdaKfwFXxsMMbjkX589do-IJjuVDshe7IHOT3Kk,340
+trigdroid-2.0.0.dist-info/licenses/LICENSE,sha256=1h287Q1gIUpNY2h3QaCowIlE6DoiBmw3WE6wn6bClkM,1065
+trigdroid-2.0.0.dist-info/RECORD,,

trigdroid-2.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

trigdroid-2.0.0.dist-info/entry_points.txt

@@ -0,0 +1,10 @@
+[console_scripts]
+trigdroid = trigdroid.cli.main:main
+trigdroid-legacy = TrigDroid.__main__:main
+
+[trigdroid.hooks]
+typescript = frida-hooks.main:main
+
+[trigdroid.test_runners]
+frida = TrigDroid_Infrastructure.test_runners.frida_test_runner:FridaTestRunner
+sensor = TrigDroid_Infrastructure.test_runners.sensor_test_runner:SensorTestRunner

trigdroid-2.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 FKIE-CAD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.