Dalvik Bytecode Emulator

A Python-based Dalvik VM emulator designed for static analysis and string decryption in Android applications. Execute targeted methods within APK files without requiring a full Android runtime.

Features at a Glance

Category	Capabilities
Bytecode Execution	127+ Dalvik opcodes including arithmetic, control flow, arrays, fields, and method invocation
Multi-DEX Support	Automatically loads and indexes all `classes*.dex` files from APKs
Static Analysis	Backward data-flow tracing and forward lookup for argument resolution
Android API Mocking	Context, PackageManager, Signature, Reflection, and system services
Java Standard Library	String, StringBuilder, Integer, Math, Arrays, List/Iterator hooks
Flexible Usage	CLI tool or import as a Python library

Overview

This emulator focuses on targeted method execution - given an APK and a target method signature, it:

Identifies all call sites to that method
Resolves the arguments at each call site (statically or via partial execution)
Executes the target method with those arguments
Returns the results

This is particularly useful for decrypting obfuscated strings in Android malware/apps.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         emulate.py                              │
│  - Entry point, argument parsing, orchestration                 │
└───────────────────────────────┬─────────────────────────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        ▼                       ▼                       ▼
┌───────────────┐    ┌─────────────────────┐    ┌──────────────┐
│  DexParser    │    │ DependencyAnalyzer  │    │ ClassLoader  │
│  - Multi-DEX  │    │ - Find call sites   │    │ - Method     │
│  - Strings    │    │ - Resolve args      │    │   resolution │
│  - Methods    │    │ - Forward lookup    │    │ - <clinit>   │
└───────────────┘    └─────────────────────┘    └──────────────┘
                                │
                                ▼
                     ┌─────────────────────┐
                     │      DalvikVM       │
                     │  - Registers        │
                     │  - PC management    │
                     │  - Opcode dispatch  │
                     └──────────┬──────────┘
                                │
        ┌──────────┬────────────┼────────────┬──────────┐
        ▼          ▼            ▼            ▼          ▼
   ┌────────┐ ┌────────┐  ┌──────────┐ ┌────────┐ ┌─────────┐
   │ const  │ │ array  │  │ control  │ │ field  │ │ invoke  │
   │  .py   │ │  .py   │  │   .py    │ │  .py   │ │   .py   │
   └────────┘ └────────┘  └──────────┘ └────────┘ └─────────┘
                     Opcode Handlers

Quick Start

Installation

pip install -r requirements.txt

Basic CLI Usage

# Emulate a specific method
python emulate.py app.apk "Lcom/example/Decryptor;->decrypt"

# With verbose output
python emulate.py app.apk "Lcom/example/Decryptor;->decrypt" -v

# With debug mode (detailed execution tracing)
python emulate.py app.apk "Lcom/example/Decryptor;->decrypt" --debug

# Limit results
python emulate.py app.apk "Lcom/example/Decryptor;->decrypt" --limit 10

Method Signature Format

LClassName;->methodName(ParameterTypes)ReturnType

Examples:
- LForwardLookupTests;->testFilledArray5
- Lutil/Crypto;->decrypt(Ljava/lang/String;)Ljava/lang/String;
- LMyClass;->compute(II)I

Capabilities in Detail

1. Implemented Opcodes (127+ total)

Move Operations (0x01-0x0d)

Opcode	Name	Description
0x01	move	Move value between registers
0x02	move/from16	Move from 16-bit register
0x03	move/16	Move with 16-bit addresses
0x04-0x06	move-wide/*	Move 64-bit value
0x07-0x09	move-object/*	Move object reference
0x0a	move-result	Move method return value
0x0b	move-result-wide	Move 64-bit return value
0x0c	move-result-object	Move object return value
0x0d	move-exception	Move exception object

Return Operations (0x0e-0x11)

Opcode	Name	Description
0x0e	return-void	Return from void method
0x0f	return	Return 32-bit value
0x10	return-wide	Return 64-bit value
0x11	return-object	Return object reference

Const Operations (0x12-0x1c)

Opcode	Name	Description
0x12	const/4	4-bit signed constant
0x13	const/16	16-bit signed constant
0x14	const	32-bit constant
0x15	const/high16	High 16 bits of 32-bit
0x16-0x19	const-wide/*	64-bit constants
0x1a-0x1b	const-string	Load string from pool
0x1c	const-class	Load class reference

Object Operations (0x1d-0x27)

Opcode	Name	Description
0x1d	monitor-enter	Enter synchronized block (no-op)
0x1e	monitor-exit	Exit synchronized block (no-op)
0x1f	check-cast	Type cast check
0x20	instance-of	Type test
0x21	array-length	Get array length
0x22	new-instance	Create new object
0x23	new-array	Create new array
0x24	filled-new-array	Create array with values
0x25	filled-new-array/range	Create array (range)
0x26	fill-array-data	Fill array from payload
0x27	throw	Throw exception

Control Flow (0x28-0x3d)

Opcode	Name	Description
0x28-0x2a	goto/*	Unconditional branch
0x2b	packed-switch	Dense switch statement
0x2c	sparse-switch	Sparse switch statement
0x2d-0x31	cmp*	Compare operations (float, double, long)
0x32-0x37	if-*	Two-register conditionals (eq, ne, lt, ge, gt, le)
0x38-0x3d	if-*z	Zero-compare conditionals

Array Operations (0x44-0x51)

Opcode	Name	Description
0x44-0x4a	aget*	Array element read (int, wide, object, boolean, byte, char, short)
0x4b-0x51	aput*	Array element write (all types)

Field Operations (0x52-0x6d)

Opcode	Name	Description
0x52-0x58	iget*	Instance field read
0x59-0x5f	iput*	Instance field write
0x60-0x66	sget*	Static field read
0x67-0x6d	sput*	Static field write

Invoke Operations (0x6e-0x78)

Opcode	Name	Description
0x6e	invoke-virtual	Virtual method call
0x6f	invoke-super	Super method call
0x70	invoke-direct	Direct method call
0x71	invoke-static	Static method call
0x72	invoke-interface	Interface method call
0x74-0x78	invoke-*/range	Range variants for >5 arguments

Arithmetic Operations (0x7b-0xe2)

Unary ops: neg-int, not-int, neg-long, not-long, neg-float, neg-double
Type conversions: int-to-, long-to-, float-to-, double-to-, int-to-byte/char/short
Integer arithmetic: add, sub, mul, div, rem, and, or, xor, shl, shr, ushr
Long arithmetic: Same operations for 64-bit integers
Float/Double arithmetic: add, sub, mul, div, rem
2-address forms: All above with destination = source1
Literal forms: Operations with 8-bit and 16-bit literal operands

2. Android API Mocking

The emulator provides comprehensive mocks for Android framework APIs:

Context & Package Management

API	Mock Behavior
`Context.getPackageName()`	Returns configured package name
`Context.getPackageManager()`	Returns mock PackageManager
`PackageManager.getPackageInfo()`	Returns mock PackageInfo with signatures
`PackageManager.getInstalledPackages()`	Returns list with mock package
`Signature.toByteArray()`	Returns configured certificate bytes
`Signature.toCharsString()`	Returns hex string of certificate
`Signature.hashCode()`	Returns consistent hash

Reflection Support

API	Mock Behavior
`Class.forName()`	Returns mock Class object
`Class.getMethod()`	Returns mock Method object
`Class.getField()`	Returns mock Field object
`Method.invoke()`	Attempts to execute or returns null
`Field.get()`	Returns field value or null
`Throwable.getCause()`	Returns null

Static Fields

Field	Value
`Build.VERSION.SDK_INT`	Configurable (default: 33)
`Boolean.TRUE/FALSE`	Wrapped Boolean objects
`Integer.TYPE`, `Long.TYPE`, etc.	Primitive type descriptors

3. Java Standard Library Hooks

Built-in implementations for common Java methods:

String Operations

Method	Implementation
`String.length()`	Returns actual length
`String.charAt(i)`	Returns character at index
`String.toCharArray()`	Returns char array
`String.getBytes()`	Returns UTF-16 LE encoded bytes
`String.intern()`	Returns same string
`String.valueOf(*)`	Converts any type to String

StringBuilder

Method	Implementation
`StringBuilder.<init>()`	Initializes empty buffer
`StringBuilder.append(*)`	Appends any type
`StringBuilder.toString()`	Returns built string

Numeric Operations

Method	Implementation
`Integer.parseInt()`	Parses string to int
`Integer.valueOf()`	Wraps int in Integer
`Long.parseLong()`	Parses string to long
`Boolean.valueOf()`	Wraps boolean in Boolean
`.intValue()`, `.booleanValue()`	Unwraps boxed types

Math Operations

Method	Implementation
`Math.abs()`	Absolute value
`Math.max()`	Maximum of two values
`Math.min()`	Minimum of two values

Arrays & Collections

Method	Implementation
`Arrays.copyOf()`	Copy array with new size
`System.arraycopy()`	Copy array region
`List.size()`	Returns list size
`List.get(i)`	Returns element at index
`List.iterator()`	Returns iterator
`Iterator.hasNext()` / `next()`	Iteration support
`Object.clone()`	Clones arrays

Utility

Method	Implementation
`TextUtils.isEmpty()`	Checks for null/empty CharSequence
`PrintStream.println()`	Prints to stdout (can be silenced)

4. Static Analysis Features

Backward Data-Flow Analysis

Traces from invoke instructions backward to find where argument registers get their values
Handles move chains, const values, static field reads, and method results
Reports unresolved arguments for partial execution fallback

Forward Lookup Analysis

When backward analysis finds allocation instructions, forward lookup scans for initialization:

Pattern	Forward Lookup
`new-instance`	Finds `invoke-direct <init>` constructor call
`new-array`	Finds `fill-array-data` population
Object setup	Captures `iput` field assignments

Dependency Analysis

Analyzes method bytecode to find static fields accessed
Identifies classes needing <clinit> initialization
Tracks methods called for recursive analysis

5. Multi-DEX Support

Automatically detects and loads all classes*.dex files from APKs
Builds unified index across all DEX files
Resolves cross-DEX method calls transparently
Handles Unicode/MUTF-8 encoded method names correctly

6. Class Initialization

Runs <clinit> static initializers when needed
Loads static field values from class definitions
Tracks initialized classes to avoid re-initialization
Supports cross-class static field resolution

Configuration

Customize mock behavior via dalvik_vm/mocks/config.py:

from dalvik_vm.mocks import mock_config

# Set package identity
mock_config.package_name = "com.target.app"

# Set SDK version
mock_config.sdk_int = 33  # Android 13

# Set signing certificate (for anti-tampering checks)
with open("original_cert.der", "rb") as f:
    mock_config.signature_bytes = f.read()

File Structure

dalvik-emulator/
├── emulate.py              # Main entry point & orchestration
├── cli.py                  # CLI wrapper
├── dalvik_vm/
│   ├── vm.py               # DalvikVM class
│   ├── types.py            # RegisterValue, DalvikObject, DalvikArray
│   ├── memory.py           # StaticFieldStore singleton
│   ├── class_loader.py     # Method resolution and execution
│   ├── dependency_analyzer.py  # Call site finding, arg resolution
│   ├── static_analysis.py  # Backward register tracing
│   ├── forward_lookup.py   # Forward initialization patterns
│   ├── dex_parser.py       # Multi-DEX file parsing
│   ├── android_mocks.py    # Re-exports from mocks/
│   ├── mocks/
│   │   ├── config.py       # Mock configuration
│   │   ├── factories.py    # Mock object creation
│   │   ├── dispatch.py     # Hook registry
│   │   ├── context_hooks.py    # Context/PackageManager hooks
│   │   ├── reflection_hooks.py # Reflection support
│   │   └── utility_hooks.py    # Utility hooks
│   └── opcodes/
│       ├── __init__.py     # Dispatch table (127+ opcodes)
│       ├── const.py        # Constant loading
│       ├── move.py         # Register moves
│       ├── control.py      # Branches, switches
│       ├── array.py        # Array operations
│       ├── field.py        # Instance/static field access
│       ├── invoke.py       # Method invocation & hooks
│       ├── arithmetic.py   # Math operations
│       ├── return_.py      # Return instructions
│       └── objects.py      # Object creation, type checks
├── tests/                  # Test suite
│   ├── test_opcodes.py     # Opcode unit tests
│   ├── test_android_mocks.py   # Mock tests
│   └── test_hooks.py       # Hook tests

Testing

Run test cases:

# Run unit tests
python -m pytest tests/

# Test filled-new-array
python emulate.py forwardtest.apk "LForwardLookupTests;->testFilledArray5"

# Test switch statement
python emulate.py forwardtest.apk "LForwardLookupTests;->testSwitchInit"

# Test static fields
python emulate.py forwardtest.apk "LForwardLookupTests;->testStaticArrayInit"

Extensibility

See DEVGUIDE.md for detailed instructions on:

Adding new Android API mocks
Overriding or adding opcode handlers
Customizing static analysis patterns
Extending forward lookup detection

Limitations

No full Android framework - Only mocked APIs are supported
No exception handling - Exceptions are not fully implemented
No threading - Single-threaded execution only
No native methods - JNI calls not supported
No dynamic class loading - DexClassLoader not supported
No reflection execution - Reflection is mocked, not executed

Requirements

Python 3.8+
See requirements.txt for full list

License

GPL v3 License

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
dalvik_vm		dalvik_vm
testing_apks		testing_apks
tests		tests
.DS_Store		.DS_Store
.gitignore		.gitignore
DEVGUIDE.md		DEVGUIDE.md
LICENSE		LICENSE
README.md		README.md
cli.py		cli.py
emulate.py		emulate.py
requirements.txt		requirements.txt

License

fatalSec/DaliVM

Folders and files

Latest commit

History

Repository files navigation

Dalvik Bytecode Emulator

Features at a Glance

Overview

Architecture

Quick Start

Installation

Basic CLI Usage

Method Signature Format

Capabilities in Detail

1. Implemented Opcodes (127+ total)

Move Operations (0x01-0x0d)

Return Operations (0x0e-0x11)

Const Operations (0x12-0x1c)

Object Operations (0x1d-0x27)

Control Flow (0x28-0x3d)

Array Operations (0x44-0x51)

Field Operations (0x52-0x6d)

Invoke Operations (0x6e-0x78)

Arithmetic Operations (0x7b-0xe2)

2. Android API Mocking

Context & Package Management

Reflection Support

Static Fields

3. Java Standard Library Hooks

String Operations

StringBuilder

Numeric Operations

Math Operations

Arrays & Collections

Utility

4. Static Analysis Features

Backward Data-Flow Analysis

Forward Lookup Analysis

Dependency Analysis

5. Multi-DEX Support

6. Class Initialization

Configuration

File Structure

Testing

Extensibility

Limitations

Requirements

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages