Analysis Modules API

Dexray Insight provides a comprehensive set of analysis modules for examining different aspects of Android APK files. Each module implements the BaseAnalysisModule interface and focuses on specific analysis domains.

APK Overview Module

Extracts basic APK metadata, permissions, components, and native libraries. This is typically the first module to run and provides foundational information used by other modules.

Analysis Capabilities:

APK metadata (package name, version, size, signatures)
Android permissions analysis
Application components (activities, services, receivers, providers)
Native library detection (.so files)
Framework detection (Flutter, React Native, Xamarin, Cordova)

Key Methods:

extract_apk_metadata() - Extract APK file information and signatures
extract_permissions() - Analyze declared and used permissions
extract_components() - Extract activities, services, and other components
extract_native_libraries() - Detect and extract native .so files

Usage Example:

# Native library extraction with fallback
native_libs = androguard_obj.get_libraries()
has_so_files = any(lib.endswith('.so') for lib in native_libs)

if not has_so_files and temporal_paths:
    # Fallback to directory parsing
    lib_dir = temporal_paths.unzipped_dir / 'lib'
    so_files = list(lib_dir.rglob('*.so'))
    native_libs = [f.name for f in so_files]

Result Structure:

{
    'package_name': 'com.example.app',
    'version_name': '1.0.0',
    'version_code': 1,
    'permissions': ['android.permission.INTERNET'],
    'activities': ['MainActivity', 'SettingsActivity'],
    'native_libraries': ['libexample.so', 'libcrypto.so'],
    'framework': 'Native'  # or Flutter, React Native, etc.
}

Permission Analysis Module

class dexray_insight.modules.permission_analysis.PermissionAnalysisModule(config: Dict[str, Any])[source]

Bases: BaseAnalysisModule

Permission analysis module for detecting critical Android permissions

DEFAULT_CRITICAL_PERMISSIONS = ['SEND_SMS', 'SEND_SMS_NO_CONFIRMATION', 'CALL_PHONE', 'RECEIVE_SMS', 'RECEIVE_MMS', 'READ_SMS', 'WRITE_SMS', 'RECEIVE_WAP_PUSH', 'READ_CONTACTS', 'WRITE_CONTACTS', 'READ_PROFILE', 'WRITE_PROFILE', 'READ_CALENDAR', 'WRITE_CALENDAR', 'READ_USER_DICTIONARY', 'READ_HISTORY_BOOKMARKS', 'WRITE_HISTORY_BOOKMARKS', 'ACCESS_FINE_LOCATION', 'ACCESS_COARSE_LOCATION', 'ACCESS_MOCK_LOCATION', 'USE_SIP', 'GET_ACCOUNTS', 'AUTHENTICATE_ACCOUNTS', 'USE_CREDENTIALS', 'MANAGE_ACCOUNTS', 'RECORD_AUDIO', 'CAMERA', 'PROCESS_OUTGOING_CALLS', 'READ_PHONE_STATE', 'WRITE_EXTERNAL_STORAGE', 'READ_EXTERNAL_STORAGE', 'WRITE_SETTINGS', 'GET_TASKS', 'SYSTEM_ALERT_WINDOW', 'SET_ANIMATION_SCALE', 'PERSISTENT_ACTIVITY', 'MOUNT_UNMOUNT_FILESYSTEMS', 'MOUNT_FORMAT_FILESYSTEMS', 'WRITE_APN_SETTINGS', 'SUBSCRIBED_FEEDS_WRITE', 'READ_LOGS', 'SET_DEBUG_APP', 'SET_PROCESS_LIMIT', 'SET_ALWAYS_FINISH', 'SIGNAL_PERSISTENT_PROCESSES', 'REQUEST_INSTALL_PACKAGES', 'ADD_VOICEMAIL', 'ACCEPT_HANDOVER', 'ANSWER_PHONE_CALLS', 'BODY_SENSORS', 'READ_CALL_LOG', 'READ_PHONE_NUMBERS', 'WRITE_CALL_LOG', 'ACCESS_BACKGROUND_LOCATION', 'ACCESS_MEDIA_LOCATION', 'ACTIVITY_RECOGNITION', 'MANAGE_EXTERNAL_STORAGE', 'READ_PRECISE_PHONE_STATE', 'BLUETOOTH_ADVERTISE', 'BLUETOOTH_CONNECT', 'BLUETOOTH_SCAN', 'BODY_SENSORS_BACKGROUND', 'NEARBY_WIFI_DEVICES', 'POST_NOTIFICATIONS', 'READ_MEDIA_AUDIO', 'READ_MEDIA_IMAGES', 'READ_MEDIA_VIDEO', 'READ_MEDIA_VISUAL_USER_SELECTED', 'UWB_RANGING']

__init__(config: Dict[str, Any])[source]

get_dependencies() → List[str][source]: No dependencies for permission analysis

analyze(apk_path: str, context: AnalysisContext) → PermissionAnalysisResult[source]

Perform permission analysis on the APK

Parameters:

apk_path – Path to the APK file
context – Analysis context

Returns:

PermissionAnalysisResult with analysis results

validate_config() → bool[source]: Validate module configuration

Analyzes Android permissions for security implications and identifies critical or dangerous permissions.

Analysis Capabilities:

Critical permission identification
Permission categorization (normal, dangerous, signature)
Custom permission analysis
Permission combination risk assessment

Configuration:

modules:
  permission_analysis:
    enabled: true
    critical_permissions_file: null  # Custom critical permissions list
    use_default_critical_list: true

Critical Permissions Detected:

Location permissions (ACCESS_FINE_LOCATION, ACCESS_COARSE_LOCATION)
Privacy permissions (READ_CONTACTS, READ_SMS, CAMERA)
System permissions (WRITE_EXTERNAL_STORAGE, SYSTEM_ALERT_WINDOW)
Network permissions (INTERNET, ACCESS_NETWORK_STATE)
Device permissions (READ_PHONE_STATE, RECORD_AUDIO)

String Analysis Module

class dexray_insight.modules.string_analysis.StringAnalysisModule(config: Dict[str, Any])[source]

Bases: BaseAnalysisModule

String extraction and analysis module.

Phase 8 TDD Refactoring: Refactored to use specialized extractors and filters from dedicated submodules following SRP.

__init__(config: Dict[str, Any])[source]

get_dependencies() → List[str][source]: Dependencies: May use results from dotnet and native analysis if available

analyze(apk_path: str, context: AnalysisContext) → StringAnalysisResult[source]

Perform string analysis using specialized extractors and filters.

Refactored coordinator function that delegates to specialized extraction and filtering components following the Single Responsibility Principle. Each filtering concern is handled by a dedicated filter with its own logic.

Parameters:

apk_path – Path to the APK file
context – Analysis context

Returns:

StringAnalysisResult with comprehensive string analysis results

validate_config() → bool[source]: Validate module configuration (public interface)

get_analysis_capabilities() → Dict[str, bool][source]

Get current analysis capabilities based on configuration.

Returns:: Dictionary showing which analysis types are enabled

Extracts and analyzes strings from APK files to identify URLs, IP addresses, email addresses, domains, and encoded content.

Pattern Detection:

IP Addresses: IPv4 and IPv6 address patterns
URLs: HTTP/HTTPS URLs with domain validation
Email Addresses: RFC-compliant email pattern matching
Domains: Domain name extraction and validation
Base64 Strings: Encoded content detection with entropy analysis

Configuration:

modules:
  string_analysis:
    patterns:
      ip_addresses: true
      urls: true
      email_addresses: true
      domains: true
      base64_strings: true
    filters:
      min_string_length: 2
      exclude_patterns: []

Usage Example:

# Access string analysis results in other modules
if 'string_analysis' in context.module_results:
    string_data = context.module_results['string_analysis']
    urls = string_data.get('urls', [])
    ip_addresses = string_data.get('ip_addresses', [])

Result Structure:

{
    'urls': ['https://api.example.com', 'http://tracking.com'],
    'ip_addresses': ['192.168.1.1', '8.8.8.8'],
    'email_addresses': ['contact@example.com'],
    'domains': ['api.example.com', 'cdn.example.com'],
    'base64_strings': ['dGVzdCBzdHJpbmc='],
    'total_strings': 1247
}

Signature Detection Module

Integrates with threat intelligence APIs to check APK signatures against known malware databases.

Supported Services:

VirusTotal: Comprehensive malware scanning with 70+ engines
Koodous: Android-specific malware detection community
Triage: Automated malware analysis sandbox

Configuration:

modules:
  signature_detection:
    enabled: true
    providers:
      virustotal:
        enabled: true
        api_key: "YOUR_API_KEY"
        rate_limit: 4  # requests per minute
      koodous:
        enabled: true
        api_key: "YOUR_API_KEY"
      triage:
        enabled: true
        api_key: "YOUR_API_KEY"

Result Structure:

{
    'virustotal': {
        'detection_ratio': '5/70',
        'positives': 5,
        'total': 70,
        'scan_date': '2024-01-15 10:30:00',
        'malware_families': ['Android.Trojan.Banker']
    },
    'koodous': {
        'detected': True,
        'rating': 7,
        'analysis_url': 'https://koodous.com/analysis/...'
    }
}

Manifest Analysis Module

class dexray_insight.modules.manifest_analysis.ManifestAnalysisModule(config: Dict[str, Any])[source]

Bases: BaseAnalysisModule

Manifest analysis module for extracting AndroidManifest.xml information

__init__(config: Dict[str, Any])[source]

get_dependencies() → List[str][source]: No dependencies for manifest analysis

analyze(apk_path: str, context: AnalysisContext) → ManifestAnalysisResult[source]

Perform manifest analysis on the APK

Parameters:

apk_path – Path to the APK file
context – Analysis context

Returns:

ManifestAnalysisResult with analysis results

validate_config() → bool[source]: Validate module configuration

Analyzes AndroidManifest.xml for security configurations, component definitions, and intent filters.

Analysis Capabilities:

Intent filter analysis for security implications
Exported component detection
Custom permission definitions
Application component relationships
Security policy analysis (network security config, backup settings)

Security Checks:

Exported components without proper protection
Intent filters that may be exploitable
Debug mode enabled in production
Backup allowed settings
Network security configuration

Configuration:

modules:
  manifest_analysis:
    enabled: true
    extract_intent_filters: true
    analyze_exported_components: true

Result Structure:

{
    'exported_activities': [
        {
            'name': 'MainActivity',
            'exported': True,
            'intent_filters': ['android.intent.action.MAIN']
        }
    ],
    'exported_services': [],
    'exported_receivers': [],
    'security_issues': [
        'Activity MainActivity is exported without permission protection'
    ]
}

API Invocation Analysis Module

Analyzes method calls and reflection usage within the APK. This module has significant performance impact and is disabled by default.

Analysis Capabilities:

Method call graph analysis
Reflection usage detection
Dynamic class loading detection
Native method invocations
Crypto API usage patterns

Configuration:

modules:
  api_invocation:
    enabled: false  # Disabled by default
    reflection_analysis: true

Performance Considerations:

This module performs deep code analysis and can significantly increase analysis time. Enable only when detailed API analysis is required.

Tracker Analysis Module

class dexray_insight.modules.tracker_analysis.TrackerAnalysisModule(config: Dict[str, Any])[source]

Bases: BaseAnalysisModule

Advertising and analytics tracker detection module.

Phase 7 TDD Refactoring: Refactored to use specialized detectors and databases from dedicated submodules following SRP.

__init__(config: Dict[str, Any])[source]

get_dependencies() → List[str][source]: Dependencies: string analysis for pattern matching

analyze(apk_path: str, context: AnalysisContext) → TrackerAnalysisResult[source]

Perform tracker detection analysis using specialized detectors.

Refactored coordinator function that delegates to specialized detection components following the Single Responsibility Principle. Each detection concern is handled by a dedicated detector with its own logic and error management.

Parameters:

apk_path – Path to the APK file
context – Analysis context

Returns:

TrackerAnalysisResult with comprehensive detection results

validate_config() → bool[source]: Validate module configuration

Identifies third-party tracking libraries using the Exodus Privacy database.

Detection Capabilities:

Advertising trackers (Google AdMob, Facebook Audience Network)
Analytics trackers (Google Analytics, Firebase Analytics)
Crash reporting (Crashlytics, Bugsnag)
Social media SDKs (Facebook SDK, Twitter SDK)
Location tracking libraries

Configuration:

modules:
  tracker_analysis:
    enabled: true
    fetch_exodus_trackers: true
    exodus_api_url: "https://reports.exodus-privacy.eu.org/api/trackers"
    api_timeout: 10

Result Structure:

{
    'trackers_found': [
        {
            'name': 'Google AdMob',
            'category': 'Advertisement',
            'website': 'https://admob.google.com',
            'detection_method': 'exodus_signature'
        }
    ],
    'tracker_count': 3,
    'categories': ['Advertisement', 'Analytics']
}

Library Detection Module

class dexray_insight.modules.library_detection.LibraryDetectionModule(config: Dict[str, Any])[source]

Bases: BaseAnalysisModule

Third-party library detection module using multi-stage analysis.

Phase 6.5 TDD Refactoring: Refactored to use specialized engines and patterns/signatures from dedicated submodules following SRP.

__init__(config: Dict[str, Any])[source]

get_dependencies() → List[str][source]: Dependencies: string analysis for class names, manifest analysis for permissions/services

analyze(apk_path: str, context: AnalysisContext) → LibraryDetectionResult[source]

Perform comprehensive library detection analysis using specialized detection engines.

Refactored coordinator function that delegates to specialized detection engines following the Single Responsibility Principle. Each detection concern is handled by a dedicated engine with its own timing and error management.

Parameters:

apk_path – Path to the APK file
context – Analysis context

Returns:

LibraryDetectionResult with comprehensive detection results

Identifies third-party libraries using heuristic and similarity analysis techniques.

Detection Methods:

Stage 1 - Heuristic Detection: Pattern-based identification using package names, class names, and manifest elements
Stage 2 - Similarity Analysis: LibScan-inspired structural comparison

Configuration:

modules:
  library_detection:
    enable_heuristic: true
    confidence_threshold: 0.7
    enable_similarity: true
    similarity_threshold: 0.85
    custom_patterns: {}  # Custom library definitions

Library Categories:

UI/UX libraries (Material Design, Support Libraries)
Networking libraries (OkHttp, Retrofit, Volley)
Image processing (Glide, Picasso, Fresco)
Database libraries (Room, SQLite, Realm)
Utility libraries (Apache Commons, Guava)

Result Structure:

{
    'libraries_detected': [
        {
            'name': 'OkHttp',
            'category': 'networking',
            'version': '4.9.0',
            'confidence': 0.95,
            'detection_method': 'heuristic_package_analysis'
        }
    ],
    'total_libraries': 12,
    'categories_found': ['networking', 'ui', 'utility']
}

Behavior Analysis Module

class dexray_insight.modules.behaviour_analysis.BehaviourAnalysisModule(config: Dict[str, Any])[source]

Bases: BaseAnalysisModule

Refactored module for behavioral analysis with specialized components

__init__(config: Dict[str, Any])[source]

get_name() → str[source]

get_description() → str[source]

get_dependencies() → List[str][source]

Return list of module names this module depends on

Returns:: List of module names that must be executed before this module

get_priority() → int[source]: Get execution priority (lower numbers = higher priority)

analyze(apk_path: str, context: AnalysisContext) → BehaviourAnalysisResults[source]

Coordinate behavioral analysis using specialized components

Parameters:

apk_path – Path to APK file
context – Analysis context

Returns:

BehaviourAnalysisResults with behavioral findings

Analyzes privacy-sensitive behaviors and advanced techniques used by the application.

Behavioral Patterns Detected:

Device Information Access: Model, IMEI, Android version
Privacy-Sensitive Data: Clipboard, phone number, contacts
System Interaction: Dynamic receivers, running services
Advanced Techniques: Reflection usage, native code integration

Configuration:

modules:
  behaviour_analysis:
    enabled: true
    deep_mode: false  # Enable with --deep flag
    features:
      device_model_access: true
      imei_access: true
      clipboard_usage: true
      reflection_usage: true

Deep Mode Features:

When enabled with --deep flag, performs more comprehensive analysis:

Advanced reflection pattern detection
Complex obfuscation technique identification
Detailed privacy behavior analysis
Advanced evasion technique detection

Native Analysis Module

class dexray_insight.modules.native.native_loader.NativeAnalysisLoader(config: Dict[str, Any])[source]

Bases: BaseAnalysisModule

Main native binary analysis module that orchestrates native analysis.

This module: 1. Checks if temporal analysis is enabled and APK is unzipped 2. Discovers native binaries (.so files) in the unzipped APK 3. Filters binaries by configured architectures 4. Manages r2pipe connections to binaries 5. Executes registered native analysis modules 6. Collects and aggregates results 7. Integrates native strings with existing string analysis

__init__(config: Dict[str, Any])[source]

analyze(apk_path: str, context: AnalysisContext) → NativeAnalysisModuleResult[source]

Perform native binary analysis on the APK.

Parameters:

apk_path – Path to the APK file
context – Analysis context with shared data

Returns:

NativeAnalysisModuleResult with analysis results

get_dependencies() → List[str][source]: Get list of module dependencies

Orchestrates analysis of native binaries (.so files) using Radare2 integration.

Prerequisites:

Temporal analysis must be enabled (APK extracted)
Radare2 and r2pipe must be installed
Native binaries must be present in APK

Architecture Support:

modules:
  native_analysis:
    architectures:
      - "arm64-v8a"      # Primary target
      - "armeabi-v7a"    # Optional
      - "x86_64"         # Optional

Native String Extraction:

class dexray_insight.modules.native.string_extraction.NativeStringExtractionModule(config: Dict[str, Any], logger: Any | None = None)[source]

Bases: BaseNativeModule

Native module for extracting strings from native binaries.

This module uses radare2’s string extraction capabilities to find readable strings in native binaries and makes them available for further analysis.

__init__(config: Dict[str, Any], logger: Any | None = None)[source]

Initialize the native analysis module.

Parameters:

config – Configuration dictionary for this module
logger – Optional logger instance

analyze_binary(binary_info: NativeBinaryInfo, r2: Any) → NativeAnalysisResult[source]

Extract strings from a native binary using radare2.

Parameters:

binary_info – Information about the binary being analyzed
r2 – r2pipe connection to the binary

Returns:

NativeAnalysisResult with extracted strings

can_analyze(binary_info: NativeBinaryInfo) → bool[source]: Check if this module should analyze the given binary

get_module_name() → str[source]: Get the module name

Extracts strings from native binaries using Radare2’s string analysis capabilities.

String Sources:

Data section strings (high confidence)
All section strings (medium confidence)
Text parsing fallback (lower confidence)

Configuration:

modules:
  native_analysis:
    modules:
      string_extraction:
        enabled: true
        min_string_length: 4
        max_string_length: 1024
        encoding: "utf-8"
        fallback_encodings: ["latin1", "ascii"]

Result Structure:

{
    'analyzed_binaries': [
        {
            'file_path': 'lib/arm64-v8a/libexample.so',
            'architecture': 'arm64-v8a',
            'file_size': 245760
        }
    ],
    'total_strings_extracted': 127,
    'strings_by_source': {
        'lib/arm64-v8a/libexample.so': [
            {
                'content': 'https://api.example.com',
                'extraction_method': 'r2_iz_data_sections',
                'confidence': 0.9
            }
        ]
    }
}

Module Development

Creating Custom Modules

To create a custom analysis module:

Inherit from BaseAnalysisModule:

from dexray_insight.core.base_classes import BaseAnalysisModule, register_module

@register_module('my_custom_module')
class MyCustomModule(BaseAnalysisModule):
    pass

Implement Required Methods:

def analyze(self, apk_path: str, context: AnalysisContext) -> BaseResult:
    # Your analysis implementation
    pass

def get_dependencies(self) -> List[str]:
    return ['string_analysis']  # Dependencies on other modules

Create Result Class:

from dataclasses import dataclass
from dexray_insight.core.base_classes import BaseResult

@dataclass
class MyCustomResult(BaseResult):
    custom_data: Dict[str, Any] = None

Register Module:

The @register_module decorator automatically registers the module with the framework.

Module Integration Patterns

Accessing Previous Results:

def analyze(self, apk_path: str, context: AnalysisContext):
    # Access string analysis results
    if 'string_analysis' in context.module_results:
        strings = context.module_results['string_analysis']
        urls = strings.get('urls', [])

Sharing Data Between Modules:

# Store data for other modules
context.shared_data['my_analysis'] = {
    'patterns': detected_patterns,
    'confidence': analysis_confidence
}

Using Temporal Analysis:

# Access extracted APK files
if context.temporal_paths:
    unzipped_dir = context.temporal_paths.unzipped_dir
    native_files = list(unzipped_dir.rglob('*.so'))

Error Handling Best Practices:

def analyze(self, apk_path: str, context: AnalysisContext):
    start_time = time.time()

    try:
        # Analysis implementation
        result = self._perform_analysis(apk_path, context)

        return MyCustomResult(
            module_name=self.get_module_name(),
            status=AnalysisStatus.SUCCESS,
            execution_time=time.time() - start_time,
            custom_data=result
        )

    except Exception as e:
        self.logger.error(f"Analysis failed: {e}")
        return MyCustomResult(
            module_name=self.get_module_name(),
            status=AnalysisStatus.FAILURE,
            execution_time=time.time() - start_time,
            error_message=str(e)
        )

Performance Optimization

Module Priorities:

Set appropriate priority values to control execution order:

modules:
  my_module:
    priority: 50  # Lower numbers run first

Dependency Management:

Specify only essential dependencies to avoid unnecessary waiting:

def get_dependencies(self) -> List[str]:
    # Only include modules whose results you actually need
    return ['apk_overview']  # Don't include optional dependencies

Resource Usage:

Consider memory and CPU usage for large APKs:

def analyze(self, apk_path: str, context: AnalysisContext):
    # Check APK size and adjust analysis depth
    apk_size = Path(apk_path).stat().st_size
    if apk_size > 100 * 1024 * 1024:  # 100MB
        self.logger.info("Large APK detected, using fast analysis mode")
        return self._fast_analysis(apk_path, context)
    else:
        return self._comprehensive_analysis(apk_path, context)