Development Guide

This section provides comprehensive guidance for developers who want to extend, modify, or contribute to Dexray Intercept.

Creating Custom Hooks

Overview

Dexray Intercept is designed to be extensible at multiple levels:

Hook Development: Create new TypeScript hooks to monitor specific Android behaviors not covered by built-in hooks.
Parser Development: Extend Python parsers to process new event types and extract meaningful insights.
Core Development: Modify the core instrumentation engine, CLI interface, or analysis capabilities.
Integration Development: Build tools and integrations that consume Dexray Intercept profiles for specialized analysis workflows.

Architecture for Developers

Understanding the System Flow

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   CLI Frontend  │    │  Core Services  │    │ Frida Backend   │
│                 │    │                 │    │                 │
│ • ammm.py       │    │ • AppProfiler   │    │ • TypeScript    │
│ • Argument      │◄──►│ • HookManager   │◄──►│   Hooks         │
│   Parsing       │    │ • ProfileData   │    │ • am_send()     │
│ • Hook Config   │    │ • EventParsers  │    │ • Java.perform  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
        │                       │                       │
        ▼                       ▼                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Target Android Process                       │
│                                                                 │
│  JavaScript hooks execute in target process context             │
└─────────────────────────────────────────────────────────────────┘

Key Integration Points:

TypeScript → JavaScript: frida-compile converts TypeScript hooks to JavaScript (via frida-compile agent/hooking_profile_loader.ts -o src/dexray_intercept/profiling.js)
JavaScript → Python: am_send() passes structured event data to Python
Python Processing: Events are parsed, formatted, and stored in profiles
CLI Integration: New hooks require CLI parameter additions

Development Environment Setup

Prerequisites

# Install development dependencies
npm install
python3 -m pip install -e ".[dev]"

# Install development tools
npm install -g typescript
npm install -g @types/node

Recommended Development Tools:

VS Code with TypeScript and Python extensions
Android Studio for APK analysis
Frida DevTools for live debugging
Wireshark for network analysis validation

Project Structure

Sandroid_Dexray-Intercept/
├── agent/                          # TypeScript hooks
│   ├── hooking_profile_loader.ts   # Main hook orchestrator
│   ├── crypto/                     # Cryptography hooks
│   ├── network/                    # Network hooks
│   ├── security/                   # Anti-analysis bypass hooks
│   └── utils/                      # Shared utilities
├── src/dexray_intercept/          # Python package
│   ├── ammm.py                     # CLI entry point
│   ├── appProfiling.py             # Main profiler class
│   ├── parsers/                    # Event parsers
│   ├── models/                     # Data models
│   └── services/                   # Core services
├── docs/                           # Documentation
├── tests/                          # Test suite
└── package.json                    # Node.js dependencies

Development Workflow

Standard Development Cycle

# 1. Make changes to TypeScript hooks
vim agent/my_category/my_hooks.ts

# 2. Compile to JavaScript
npm run build

# 3. Test with target application
dexray-intercept --enable-my-hooks com.test.app

# 4. Validate JSON output
cat profile_com.test.app_*.json | jq .

# 5. Run tests
python3 -m pytest tests/

# 6. Commit changes
git add .
git commit -m "Add new hook category: my_hooks"

Hook Development Cycle

# Development mode with auto-compilation
npm run watch &                     # Auto-compile on changes

# Test iteration
while true; do
    dexray-intercept -v --enable-my-hooks com.test.app
    # Review output, make changes, repeat
done

Core Development Areas

Hook Categories

Existing Categories:

agent/crypto/ - Cryptographic operations
agent/network/ - Network communications
agent/file/ - File system operations
agent/ipc/ - Inter-process communication
agent/process/ - Process and runtime monitoring
agent/services/ - Android system services
agent/security/ - Anti-analysis bypass

Creating New Categories:

Create directory under agent/
Implement hook functions following established patterns
Add to hooking_profile_loader.ts for integration
Create corresponding Python parsers
Add CLI support in dexray-intercept.py

Parser Development

Parser Structure:

# src/dexray_intercept/parsers/my_category.py
from .base import BaseParser
from ..models.events import Event

class MyCategoryEvent(Event):
    def __init__(self, event_type: str, timestamp: str):
        super().__init__(event_type, timestamp)
        self.custom_field = None

    def get_event_data(self):
        return {
            "event_type": self.event_type,
            "custom_field": self.custom_field,
            "timestamp": self.timestamp
        }

class MyCategoryParser(BaseParser):
    def parse_json_data(self, data: dict, timestamp: str):
        event = MyCategoryEvent(data.get('event_type'), timestamp)
        event.custom_field = data.get('custom_field')

        # Add metadata for enhanced analysis
        event.add_metadata('category', 'my_category')
        event.add_metadata('severity', 'medium')

        return event

Parser Registration:

# src/dexray_intercept/parsers/factory.py
from .my_category import MyCategoryParser

def _register_default_parsers(self):
    self._parsers["MY_CATEGORY"] = MyCategoryParser()

Testing and Validation

Unit Testing

# tests/test_my_parser.py
import unittest
from dexray_intercept.parsers.my_category import MyCategoryParser

class TestMyCategoryParser(unittest.TestCase):
    def setUp(self):
        self.parser = MyCategoryParser()

    def test_parse_json_data(self):
        test_data = {
            'event_type': 'my_category.test',
            'custom_field': 'test_value'
        }

        event = self.parser.parse_json_data(test_data, '2024-08-20T10:30:00Z')

        self.assertEqual(event.event_type, 'my_category.test')
        self.assertEqual(event.custom_field, 'test_value')

Integration Testing

# Test hook integration
python3 tests/integration/test_hook_integration.py

# Test with real app (requires device)
python3 tests/integration/test_real_app.py com.example.testapp

Manual Testing

# Test specific hook categories
dexray-intercept -v --enable-my-hooks com.test.app

# Test with malware samples (use caution)
dexray-intercept --hooks-bypass --enable-my-hooks malware.apk

# Validate output format
python3 -c "
import json
with open('profile.json') as f:
    data = json.load(f)
    print(f'Events: {data.get(\"_metadata\", {}).get(\"total_events\", 0)}')
"

Performance Testing

# tests/performance/test_hook_performance.py
import time
from dexray_intercept import AppProfiler

def test_hook_performance():
    start_time = time.time()

    # Run profiler with hooks
    profiler = AppProfiler(session, hook_config={'my_hooks': True})
    profiler.start_profiling()

    # Let app run for measured time
    time.sleep(30)

    profiler.stop_profiling()
    duration = time.time() - start_time

    # Validate performance impact
    assert duration < 35  # Should not add more than 5s overhead

Documentation Standards

Code Documentation

TypeScript Hooks:

/**
 * Install hooks for monitoring custom Android behavior
 *
 * This function hooks into com.example.CustomClass methods to track
 * sensitive operations and data access patterns.
 *
 * Events generated:
 * - custom.method.called: When sensitiveMethod is invoked
 * - custom.data.access: When data access occurs
 *
 * @example
 * // Enable in hook config
 * hook_config = { 'custom_hooks': true }
 */
export function install_custom_hooks(): void {

Python Classes:

class CustomEvent(Event):
    """Event representing custom Android behavior.

    This event captures information about custom operations
    including method calls, data access, and timing information.

    Args:
        event_type: Specific event identifier (e.g., 'custom.method.called')
        timestamp: ISO 8601 timestamp when event occurred

    Example:
        >>> event = CustomEvent('custom.method.called', '2024-08-20T10:30:00Z')
        >>> event.method_name = 'sensitiveMethod'
        >>> event.get_event_data()
        {'event_type': 'custom.method.called', 'method_name': 'sensitiveMethod'}
    """

API Documentation

All public APIs should include:

Purpose and behavior description
Parameter documentation with types
Return value documentation
Usage examples
Exception handling notes

User Documentation

New features require:

CLI usage examples in user guide
Hook configuration documentation
Event format specifications
Integration examples

Contributing Workflow

Development Process

Fork and Clone

git clone https://github.com/your-username/Sandroid_Dexray-Intercept.git
cd Sandroid_Dexray-Intercept

Create Feature Branch

git checkout -b feature/my-new-hook-category
git checkout -b fix/parser-bug
git checkout -b docs/improve-api-reference

Development and Testing

# Make changes
vim agent/my_category/my_hooks.ts
vim src/dexray_intercept/parsers/my_category.py

# Test changes
npm run build
python3 -m pytest tests/
dexray-intercept --enable-my-category com.test.app

Documentation

# Update documentation
vim docs/user-guide/hook-configuration.rst
vim docs/api/typescript-api.rst

# Build and verify docs
cd docs/
make html

Commit and Push

git add .
git commit -m "Add new hook category for monitoring XYZ behavior"
git push origin feature/my-new-hook-category

Create Pull Request - Describe changes and motivation - Include testing instructions - Reference related issues

Code Standards

TypeScript Style:

Use TypeScript strict mode
Follow established naming conventions
Include comprehensive error handling
Document complex logic with comments

Python Style:

Follow PEP 8 conventions
Use type hints for function signatures
Include docstrings for public methods
Handle exceptions appropriately

Testing Requirements:

Unit tests for new parsers
Integration tests for new hook categories
Performance testing for potentially heavy hooks
Documentation examples should be tested

Quality Assurance

Pre-commit Checks

# Run before committing
npm run build                    # Ensure TypeScript compiles
python3 -m pytest tests/        # Run test suite
ruff check .                     # Python linting
python3 -m mypy src/            # Type checking

Continuous Integration

The project uses automated testing for:

TypeScript compilation validation
Python unit and integration tests
Code quality and style checks
Documentation build verification

Release Process

# Version bump
npm version patch|minor|major

# Update changelog
vim CHANGELOG.md

# Tag release
git tag -a v0.3.1 -m "Release version 0.3.1"
git push origin v0.3.1

Common Development Tasks

Adding a New Hook Category

See detailed guide: Creating Custom Hooks

Adding CLI Parameters

# In src/dexray_intercept/ammm.py

# Add argument
hooks.add_argument("--enable-my-feature", action="store_true",
                   help="Enable my feature monitoring")

# Add to individual hooks mapping
individual_hooks = {
    'enable_my_feature': 'my_feature_hooks'
}

Debugging Hook Issues

# Enable verbose mode
dexray-intercept -v --enable-problematic-hook com.test.app

# Check JavaScript compilation
cat src/dexray_intercept/profiling.js | grep "my_hook_function"

# Test with minimal app
dexray-intercept --enable-problematic-hook com.android.calculator

# Validate JSON output
python3 -m json.tool profile_*.json

Extending Event Types

# Create new event class in src/dexray_intercept/models/events.py
class MyCustomEvent(Event):
    def __init__(self, event_type: str, timestamp: str):
        super().__init__(event_type, timestamp)
        self.custom_property = None

# Update parser to use new event type
# Update factory registration
# Add to __all__ exports

Next Steps

Choose your development focus:

Creating new hooks: Creating Custom Hooks
Understanding build process: building
Contributing guidelines: contributing

For questions or discussions:

GitHub Issues: Technical questions and bug reports
GitHub Discussions: Development discussions and feature requests
Pull Requests: Code contributions and improvements