android-reverse-engineering-skill/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A Claude Code Skill (plugin) for Android reverse engineering, API extraction, and privacy auditing. It provides four skills:

• android-reverse-engineering: 5-phase workflow — dependency verification, APK/XAPK/JAR/AAR decompilation (jadx and/or Fernflower), manifest/structure analysis, call flow tracing, and HTTP API endpoint extraction
• tracker-analysis: 4-phase workflow — detect analytics/tracker SDKs (Firebase, Adjust, AppsFlyer, Mixpanel, Amplitude, Segment, Braze, CleverTap, Flurry), analyze init/events/user ID/consent, report data exfiltration endpoints
• ad-analysis: 3-phase workflow — detect ad SDKs (AdMob, Unity, IronSource, AppLovin, Meta AN, Vungle, InMobi, Chartboost, Pangle, Mintegral), map ad formats and mediation setup, report privacy/consent
• sdk-neutralizer: 6-phase workflow — decode APK, identify tracker/ad SDK entry points, neutralize by replacing smali method bodies with stubs, disable manifest components, rebuild and sign APK for enterprise sideloading

Repository Structure

• .claude-plugin/marketplace.json — Marketplace catalog entry
• plugins/android-reverse-engineering/.claude-plugin/plugin.json — Plugin manifest
• plugins/android-reverse-engineering/commands/decompile.md — /decompile slash command
• plugins/android-reverse-engineering/commands/find-trackers.md — /find-trackers slash command
• plugins/android-reverse-engineering/commands/find-ads.md — /find-ads slash command
• plugins/android-reverse-engineering/commands/neutralize.md — /neutralize slash command
• plugins/android-reverse-engineering/skills/android-reverse-engineering/ — Core RE skill (5-phase workflow, references, scripts)
• plugins/android-reverse-engineering/skills/tracker-analysis/ — Tracker/analytics SDK detection skill (4-phase workflow, references, find-trackers.sh)
• plugins/android-reverse-engineering/skills/ad-analysis/ — Advertising SDK detection skill (3-phase workflow, references, find-ads.sh)
• plugins/android-reverse-engineering/skills/sdk-neutralizer/ — SDK neutralization skill (6-phase workflow, references, decode-apk.sh, neutralize.sh, merge-splits.sh, rebuild-apk.sh)

Key Scripts

Core scripts under plugins/android-reverse-engineering/skills/android-reverse-engineering/scripts/:

# Check installed dependencies
bash scripts/check-deps.sh

# Install a dependency (auto-detects OS/package manager)
bash scripts/install-dep.sh <dep>   # e.g., jadx, vineflower, dex2jar

# Install ALL neutralizer dependencies at once (java, apktool, apksigner, zip)
bash scripts/install-dep.sh neutralize-all

# Decompile an APK/JAR/AAR/XAPK
bash scripts/decompile.sh [--engine jadx|fernflower|both] [--deobf] [--no-res] [-o outdir] <file>

# Search decompiled source for API calls
bash scripts/find-api-calls.sh <source-dir> [--retrofit|--okhttp|--volley|--urls|--auth|--all]

Tracker analysis script under plugins/android-reverse-engineering/skills/tracker-analysis/scripts/:

# Search for tracker/analytics SDKs
bash find-trackers.sh <source-dir> [--firebase|--adjust|--appsflyer|--mixpanel|--amplitude|--segment|--braze|--clevertap|--flurry|--all]

Ad analysis script under plugins/android-reverse-engineering/skills/ad-analysis/scripts/:

# Search for advertising SDKs
bash find-ads.sh <source-dir> [--admob|--unity|--ironsource|--applovin|--facebook|--formats|--mediation|--consent|--entrypoints|--all]

SDK neutralizer scripts under plugins/android-reverse-engineering/skills/sdk-neutralizer/scripts/:

# Check neutralization dependencies (including apktool >= 2.9.0)
bash check-neutralize-deps.sh

# Decode APK or XAPK (for XAPK: decodes base APK, preserves splits in .xapk-origin/)
bash decode-apk.sh <file.apk|file.xapk> [-o <decoded-dir>]

# Neutralize SDK entry points in decoded APK (dry-run first)
bash neutralize.sh <decoded-dir> [--ads|--trackers|--all] [--dry-run] [--no-backup] [--no-manifest] [--targets-file <file>] [--replay] [--no-save-manifest]

# Merge XAPK splits into decoded base for single APK output (optional, for XAPK input)
bash merge-splits.sh <decoded-dir> [--abi <abi>] [--all-abis] [--skip-resources]

# Rebuild and sign neutralized APK (auto-reassembles XAPK if .xapk-origin/ exists, or single APK if merged)
bash rebuild-apk.sh <decoded-dir> [--auto-keystore|--debug-key|--keystore <file>] [-o <output>] [--no-sign] [--no-res] [--zipalign] [--single-apk]

Architecture

Plugin structure follows Claude Code skill conventions:

• skills/<name>/SKILL.md defines the skill's workflow and capabilities
• commands/<name>.md defines slash commands with YAML frontmatter
• scripts/ contains executable bash utilities invoked by the skill
• references/ contains in-depth technical documentation the skill consults

Script conventions:

• Exit codes: 0 = success, 1 = error, 2 = manual action needed
• check-deps.sh outputs machine-readable INSTALL_REQUIRED: and INSTALL_OPTIONAL: lines
• decompile.sh handles XAPK by extracting the archive and decompiling each APK separately
• ${CLAUDE_PLUGIN_ROOT} references the plugin root directory; FERNFLOWER_JAR_PATH for custom JAR location

Decompiler strategy:

• jadx: default for APKs (fast, handles resources natively)
• Fernflower/Vineflower: better Java output for complex code, requires dex2jar for APK input
• --engine both: runs both in parallel and compares output quality

No Build/Test/Lint

This is a documentation-and-scripts plugin with no compiled code, no test suite, and no linter configuration. Changes are validated by reading the markdown/bash and testing scripts manually against APK files.

Versioning

The plugin version is declared in two files that must be kept in sync:

• .claude-plugin/marketplace.json → plugins[0].version (marketplace catalog)
• plugins/android-reverse-engineering/.claude-plugin/plugin.json → version (plugin manifest)

Claude Code reads the version from plugin.json with priority — if that file has a stale version, /plugin will show the old number even if marketplace.json is updated. Always bump both files together.

Conventions

• Line endings are LF (enforced via .gitattributes for WSL/Windows compatibility)
• Scripts target Bash 4.0+ and support Linux (apt/dnf/pacman) and macOS (Homebrew)
• Scripts fall back to user-local installs (~/.local/) when sudo is unavailable