Amber

Open-source Android reconstruction tool — lifts APKs into readable, buildable Gradle projects.

---

What Amber Does

Amber takes an Android APK and reconstructs it into a Gradle project you can open in Android Studio, inspect, and work toward rebuilding. The pipeline covers:

• DEX Parsing — reads Dalvik bytecode from APK/DEX artifacts
• IR & CFG Construction — builds internal intermediate representation and control-flow graphs
• SSA Conversion — transforms lifted code into Static Single Assignment form for structured analysis
• Type Inference — recovers type facts from bytecode evidence
• Java Source Emission — generates readable Java source files from the recovered IR
• Gradle Project Synthesis — produces a complete Android Gradle project with sources, manifest scaffolding, and build configuration
• Library Partitioning — separates likely third-party/library code from app code into distinct source roots
• Evidence & Diagnostics — produces metadata, trust labels, and diagnostic reports throughout the pipeline

Architecture

graph LR
    APK[APK / DEX Input] --> CLI[amber-cli]
    CLI --> Pipeline[amber-pipeline]
    Pipeline --> Core[amber-core]
    Core --> IR[IR / CFG / SSA]
    IR --> Emit[Java Emission]
    Emit --> Synth[Gradle Synthesis]
    Synth --> Project[Android Studio Project]

    style APK fill:#2A2A2A,color:#F5F5F0,stroke:#E85D3F
    style Project fill:#2A2A2A,color:#F5F5F0,stroke:#E85D3F

Loading

Module	Purpose
amber-core	DEX parsing, IR construction, SSA, type inference, Java emission, evidence ledger
amber-pipeline	End-to-end orchestration, Gradle project synthesis, library partitioning
amber-cli	Command-line interface wrapping the pipeline
amber-test-fixtures	Test APKs and resources for CI validation

Requirements

• JDK 21 (Temurin recommended)
• Android SDK with at minimum:
  • platforms;android-34
  • build-tools;34.0.0
  • platform-tools
• macOS or Linux — the generated project auto-detects the Android Studio JDK path on macOS; on other OSes, set JAVA_HOME manually

Quickstart

# Clone and build
git clone https://github.com/edengilbertus/amber.git
cd amber
./gradlew :amber-cli:installDist

# Reconstruct an APK
./amber-cli/build/install/amber-cli/bin/amber-cli reconstruct app.apk --output ./my-project

# Try building the output
cd my-project && ./gradlew assembleDebug

Project Structure

amber/
├── amber-core/          # Core IR, SSA, type inference, Java emission
├── amber-pipeline/      # Pipeline orchestration, Gradle synthesis
├── amber-cli/           # CLI entry point
├── amber-test-fixtures/ # Test APKs and resources
├── schemas/             # JSON schemas (dex-ssa-v1, evidence-ledger-v1)
├── docs/                # Master spec and design documents
│   ├── master-spec.md   # Normative pipeline specification
│   └── plans/           # Implementation plans and design docs
└── .github/workflows/   # CI (Gradle validation + Android synthesis smoke test)

Current Status

Amber is an active research and engineering tool. Here's where things stand:

Area	Status
DEX parsing & lifting	✅ Functional
IR / CFG / SSA construction	✅ Functional
Type inference	✅ Functional
Java source emission	✅ Functional (heuristic naming, iterating on edge cases)
Gradle project synthesis	🟡 Functional, compile path being hardened
Resource & manifest recovery	🟡 Stubbed when real artifacts unavailable
Kotlin metadata recovery	🟡 In progress
Compose detection	🟡 ABI detection implemented, wrappers in progress

Known Limitations

• The generated project may need manual fixes to compile on complex real-world APKs — the synthesis compile path is actively being hardened
• Resource and manifest recovery produce stubs when the original artifacts can't be fully decoded
• Package naming is heuristic — output is best used for inspection and incremental repair rather than guaranteed faithful recovery
• The Android smoke test in CI validates Java compilation (compileDebugJavaWithJavac), not a full assembleDebug

Contributing

See CONTRIBUTING.md for development setup, coding standards, and PR guidelines.

License

Copyright 2025-2026 Eden Gilbert Kiseka

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.