DexTrace

DexTrace is a lightweight core for Android APK / DEX parsing and call-tracing.

It does not decide whether an APK is malicious.
Instead, DexTrace focuses on producing a clean, standardized, and reproducible representation of:

• APK metadata
• AndroidManifest structure
• DEX internal tables
• API call evidence and method-level cross-references (XREF)

These results are designed to be consumed by higher-level engines, such as
👉 Quark Engine or other static / hybrid analysis frameworks.

---

Goals

DexTrace is intended to provide:

• lightweight APK and DEX parsing without depending on a full Android analysis framework
• deterministic Dalvik bytecode disassembly and inspection
• structured API extraction from DEX bytecode
• manifest and APK metadata parsing
• a Python API and CLI for inspection, debugging, and integration
• reproducible outputs suitable for downstream rule engines

✨ Current Features

APK Support

• File hashes (MD5 / SHA1 / SHA256)
• File size and ZIP entries
• APK archive reading for downstream parsing workflows

AndroidManifest Parsing

• Supports binary AXML and plain XML
• Extracts:
  • package name
  • permissions
  • activities
  • services
  • receivers
  • providers
• Safe fallback for malformed or missing manifests

DEX Header Parsing

• Strict DEX magic validation (dex\n035, cdex)
• Full header field decoding
• Defensive handling of truncated / invalid DEX files

DEX Bytecode Parsing (Core)

• code_item parsing
• instruction iteration
• offset-aware bytecode handling
• method/code mapping support
• designed to scale toward richer control-flow or data-flow analysis later

---

🔍 API Call Tracing (Quark-aligned)

DexTrace implements progressive API tracing stages aligned with
Quark Engine’s 5-stage detection model.

Stage 2 – API Calls

• extracts all invoke-* instructions
• resolves:
  • caller class / method / prototype
  • callee class / method / prototype
  • opcode type and bytecode offset
• produces structured XREF output
• safe against malformed indices and corrupted tables

Stage 3 – API Sets (Per Method)

• groups APIs per caller method
• represents which APIs are used together
• order-independent
• designed for combination-based rule matching

Stage 4 – API Call Sequences

• preserves static call order within each method
• offset-aware ordering of invoke-* instructions
• method-local (no CFG explosion)
• designed for sequence-based rule matching

---

Repository Structure

src/dextrace/
  api.py                  # public Python API entry point
  cli/                    # CLI entry points
  core/                   # APK/DEX parsing and API extraction core
  dalvik/                 # Dalvik disassembly and opcode utilities
  manifest/               # binary AndroidManifest parsing
  errors.py               # shared project exceptions
  version.py              # package version

tests/
  fixtures/               # synthetic fixtures used by tests
  test_*.py               # pytest-based test suite

docs/
  modules-overview.md     # module-by-module handoff guide
  development-workflow.md # contributor workflow and validation notes
  current-status.md       # current state, known gaps, handoff notes

Key areas

src/dextrace/cli/

Command-line entry points.

• main.py: top-level CLI dispatcher
• cmd_meta.py: metadata-oriented inspection
• cmd_disasm.py: disassembly-oriented inspection
• cmd_dex.py: DEX/API-oriented inspection

src/dextrace/core/

Core APK / DEX parsing and API extraction logic.

Includes:

• APK reading
• APK metadata extraction
• manifest parsing bridge
• DEX structure parsing
• method/code mapping
• API extraction
• method/API resolution

src/dextrace/dalvik/

Dalvik bytecode internals.

Includes:

• opcode format metadata
• operand decoding
• instruction size handling
• payload decoding
• disassembly support
• smali-oriented helpers

src/dextrace/manifest/

Low-level binary AXML parsing used by manifest-related workflows.

---

📦 Installation

Development install (editable mode)

git clone https://github.com/ev-flow/DexTrace.git
cd DexTrace
pip install -e .

Optional Pipenv workflow

pipenv install --dev
pipenv shell

---

CLI Usage

DexTrace exposes a single CLI entry point:

dextrace --help

APK Metadata

Show hashes, manifest summary, and DEX presence:

dextrace meta sample.apk

DEX Header

Parse and display full DEX header fields:

dextrace dex --header sample.apk

DEX Summary

Show a concise overview of DEX structure:

dextrace dex --summary sample.apk

🔗 API Tracing Commands

Stage 2 – API Calls

dextrace dex --apis sample.apk

Stage 3 – API Sets

dextrace dex --api-sets sample.apk

Stage 4 – API Sequences

dextrace dex --api-seq sample.apk

JSON Output

All commands support structured JSON output:

dextrace dex --api-seq --json sample.apk

Example Output

Stage 2

{
  "dex": {
    "summary": {
      "magic": "dex\n035\u0000",
      "version": "035",
      "file_size": 717940,
      "string_ids_size": 6285,
      "method_ids_size": 5455,
      "class_defs_size": 534
    },
    "api_calls": [
      {
        "caller": {
          "class": "Landroid/support/v4/accessibilityservice/AccessibilityServiceInfoCompat;",
          "method": "<clinit>",
          "proto": "()V"
        },
        "invoke": {
          "opcode": "invoke-direct",
          "offset": 16
        },
        "callee": {
          "class": "Landroid/support/v4/accessibilityservice/AccessibilityServiceInfoCompat$AccessibilityServiceInfoJellyBeanMr2;",
          "method": "<init>",
          "proto": "()V"
        }
      }
    ],
    "api_calls_count": 1
  }
}

---

Running Tests

Run the full test suite:

pytest

Run a targeted test file:

pytest tests/test_dex_parser.py

Run tests by keyword:

pytest -k api_extractor

Suggested subsystem-oriented test runs

• CLI changes:

  pytest tests/test_cli_meta.py tests/test_smoke.py

• APK / metadata changes:

  pytest tests/test_apk_reader.py tests/test_apk_metadata.py

• manifest changes:

  pytest tests/test_manifest_parser.py

• DEX parser changes:

  pytest tests/test_dex_parser.py tests/test_dex_header.py

• API extraction changes:

  pytest tests/test_dex_api_extractor.py

• Dalvik / disassembly changes:

  pytest -k disassembler

---

Development Notes

DexTrace is organized by subsystem, so contributors should usually:

1. identify the affected subsystem first
2. make the smallest targeted change possible
3. run the closest subsystem tests first
4. broaden validation only if the change touches shared logic
5. update documentation when contributor-facing behavior changes

When DexTrace is used under Quark Engine, Quark-facing mismatches should be investigated conservatively and evidence-first. Preserve:

• APK identifier or sample path
• rule IDs
• exact commands used
• DexTrace output
• comparison-core output such as Androguard
• diff excerpts
• current hypothesis

Prefer wording such as:

• inconsistent API matching
• resolution difference
• invoke extraction gap

until the exact root cause is verified in code and tests.

---

Documentation

Additional contributor documentation:

• Contributing
• Modules Overview
• Development Workflow
• Current Status

---

Samples and Build Artifacts

The repository may include:

• extracted sample APK directories for validation or reproduction
• generated build artifacts under dist/

These are useful for testing and packaging, but they are not the core implementation surface.

---

Relationship with Quark Engine

DexTrace can be used as an analysis core under Quark Engine. In that setup:

• DexTrace is responsible for parsing APK / DEX input and extracting evidence
• Quark Engine is responsible for higher-level rule matching and scoring

When validating Quark-facing behavior, comparisons should keep the APK, rule set, and Quark version fixed while only changing the analysis core.

---

License

See LICENSE.