tessl/pypi-androguard

Comprehensive Python toolkit for Android application reverse engineering and security analysis.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Dynamic Analysis

Name: tessl/pypi-androguard
Author: tessl

Dynamic analysis capabilities for runtime analysis and modification of Android applications using Frida integration. The Pentest module provides comprehensive dynamic analysis functionality including tracing, hooking, and runtime manipulation.

Capabilities

Pentest Engine

The main dynamic analysis engine providing Frida integration and runtime analysis capabilities.

class Pentest:
    def __init__(self):
        """Initialize the dynamic analysis engine."""

def connect_default_usb(self) -> bool:
    """
    Connect to the default USB device for dynamic analysis.
    
    Returns:
        bool: True if connection successful, False otherwise
    """

def attach_package(self, package_name: str, list_file_scripts: list, pid=None) -> bool:
    """
    Attach to a running package for dynamic analysis.
    
    Parameters:
    - package_name: Android package name to attach to
    - list_file_scripts: List of Frida script files to inject
    - pid: Process ID (optional, will find automatically if None)
    
    Returns:
        bool: True if attachment successful
    """

def start_trace(self, filename: str, session: Session, list_modules: list, list_packages: list = None) -> None:
    """
    Start runtime tracing of specified modules and packages.
    
    Parameters:
    - filename: Output file for trace results
    - session: Androguard session object
    - list_modules: List of modules to trace
    - list_packages: List of packages to monitor (optional)
    """

def dump(self, package_name: str) -> dict:
    """
    Dump runtime information from a running package.
    
    Parameters:
    - package_name: Target package name
    
    Returns:
        dict: Dumped runtime information
    """

Message System

Event-driven message system for handling dynamic analysis events and communications.

class Message:
    """Base message class for dynamic analysis communication."""

class MessageEvent(Message):
    """Event-based message for dynamic analysis events."""

class MessageSystem(Message):
    """System-level message for dynamic analysis operations."""

Usage Examples

Basic Dynamic Analysis Setup

from androguard.pentest import Pentest
from androguard.session import Session

# Initialize dynamic analysis engine
pentest = Pentest()

# Connect to USB device
if pentest.connect_default_usb():
    print("Connected to device successfully")
    
    # Attach to target package with Frida scripts
    scripts = ["hooks.js", "trace.js"]
    if pentest.attach_package("com.example.app", scripts):
        print("Successfully attached to package")

Runtime Tracing

from androguard.pentest import Pentest
from androguard.session import Session

# Setup session and pentest engine
session = Session()
pentest = Pentest()

# Start tracing specific modules
modules_to_trace = ["libnative.so", "libssl.so"]
packages_to_monitor = ["com.example.app"]

pentest.start_trace(
    filename="trace_output.log",
    session=session,
    list_modules=modules_to_trace,
    list_packages=packages_to_monitor
)

Package Information Dumping

from androguard.pentest import Pentest

pentest = Pentest()

# Connect and dump package information
if pentest.connect_default_usb():
    package_info = pentest.dump("com.example.target")
    
    print("Package dump results:")
    for key, value in package_info.items():
        print(f"  {key}: {value}")

Frida Integration

The dynamic analysis module integrates with Frida for advanced runtime analysis capabilities including:

Method hooking: Intercept and modify method calls at runtime
Memory manipulation: Read and write application memory
API tracing: Monitor system and library API calls
Code injection: Execute custom JavaScript code in target process
SSL pinning bypass: Disable certificate pinning mechanisms
Anti-debugging bypass: Circumvent common anti-analysis techniques

Common Use Cases

Security Analysis

# Hook sensitive API calls
frida_script = """
Java.perform(function() {
    var CryptoClass = Java.use("javax.crypto.Cipher");
    CryptoClass.doFinal.implementation = function(input) {
        console.log("Crypto operation detected: " + input);
        return this.doFinal(input);
    };
});
"""

# Inject script into target
pentest.attach_package("com.banking.app", ["crypto_hooks.js"])

Behavioral Analysis

# Trace network communications
network_trace_modules = ["libssl.so", "libc.so"]
pentest.start_trace(
    "network_trace.log",
    session,
    network_trace_modules,
    ["com.suspicious.app"]
)

Reverse Engineering

# Dump runtime class information
package_dump = pentest.dump("com.target.app")

# Extract loaded classes and methods
if "classes" in package_dump:
    for class_name, methods in package_dump["classes"].items():
        print(f"Class: {class_name}")
        for method in methods:
            print(f"  Method: {method}")

Integration with Static Analysis

Dynamic analysis complements static analysis by providing runtime verification of static findings:

from androguard.misc import AnalyzeAPK
from androguard.pentest import Pentest

# Static analysis
a, d, dx = AnalyzeAPK("app.apk")

# Find suspicious methods statically
suspicious_methods = dx.find_methods(method_name="encrypt.*")

# Verify with dynamic analysis
pentest = Pentest()
pentest.connect_default_usb()

# Hook the methods found in static analysis
for method in suspicious_methods:
    hook_script = f"hook_{method.name}.js"
    pentest.attach_package(a.get_package(), [hook_script])

Install with Tessl CLI