re-harmonyos

HarmonyOS application reverse engineering (HarmonyOS / hap / ArkTS)

When to use / when not to use

• Use: when you have a hap (application release package) / hsp (shared package) / har (static library archive) and need to inspect module configuration, resources, and ArkTS business logic
• Use: when you need to recover business logic from .abc bytecode (ArkCompiler output)—string location, disassembly, deobfuscation
• Use: when a HarmonyOS application contains native libraries (.so under libs/) and requires static/dynamic joint analysis
• Don't use: for ordinary Android APKs (use [[re-apk]]; the dex/smali system differs from this skill)
• Don't use: for pure Web/frontend applications (not a HarmonyOS container; for script/Web paths use [[re-script-deob]] or [[re-browser-ext]])
• Note:Dynamic execution defaults to sandbox ([[re-analyze/platform-tips]] highest principle)—static unpacking/disassembly is sandbox-free; running and observing on an emulator/real device must go into [[re-sandbox]]

Tool preparation

Refer to [[re-analyze/platform-tips]]—static analysis (unpacking, strings, disassembly) is sandbox-free; dynamic steps go into the sandbox per the highest principle.

hap unpacking (zip container, general approach)

• hap = zip container, same origin as APK (both belong to the zip/jar family)—any general-purpose zip unpacking tool can unpack it (unzip / 7-Zip / python3 zipfile module), not tied to a single implementation
• The process is the same origin as [[re-apk]]: first list the manifest (unzip -l) → then unpack → verify integrity (compare CRC/file count)
• Professional unpacking tools (integrating module.json parsing and resource extraction) can serve as alternatives; note to choose the version corresponding to the release version
• Verification: the directory structure after unpacking is complete (compare against the manifest from step 1)

python3 (string extraction and scripting)

• Linux: apt install python3 / dnf install python3 / pacman -S python; macOS: built-in; Windows: official installer
• zipfile is part of the standard library:python3 -m zipfile -l app.hap to list the manifest,python3 -m zipfile -e app.hap out/ to unpack
• Verification: python3 --version

String/resource extraction tools

• strings(bundled with binutils) and grep: to fish out URLs, keys, and prompt text from .abc and resources
• For resource files (layouts, images, rawfile), first use file to determine the type before extraction

ArkCompiler disassembler (an alternative targeting abc, generalized description)

• The jadx-style approach of [[re-java]] is reused: Android uses jadx to decompile dex, and the HarmonyOS side corresponds to ArkCompiler disassembly tools—both the official toolchain (shipped with the SDK) and open-source implementations are acceptable; just pick an implementation that can output instruction-level assembly (instruction mnemonics + operand/constant references), and multiple implementations can be cross-validated
• Version matching: identify the compiler version first, then choose the tool (see pitfall 2)

Operation steps

Execute in order; archive each step's artifacts (unpacked directory, disassembly output + sha256) (see [[re-triage]]).

1. Package structure identification and unpacking：

   file app.hap
   unzip -l app.hap | head -30
   unzip -o app.hap -d out/
   

   • hap ≈ APK variant:module.json(module configuration, equivalent to manifest: entry/permissions/component declarations),resources/(resources, equivalent to res/),ets/(where ArkTS compilation artifacts reside, .abc bytecode),libs/（native .so）、assets/(raw resources such as rawfile)
   • hsp / har are both zip containers with similar structures (hsp contains .abc, har is a static library archive), and the unpacking process is the same
   • The zip container unpacking process shares the same origin as APK ([[re-apk]]): list manifest → unpack → verify; if a nested container is found, unpack recursively (see pitfall 4)

2. Bytecode identification (.abc)：

   find out/ -name "*.abc" | head
   xxd out/ets/modules.abc | head -10    # 看文件头
   

   • .abc is an ArkCompiler (Ark Compiler) bytecode file, the main body of business logic; the file header contains a fixed magic number and version field, followed by segment structures (string segment/literal segment/instruction segment, etc., with the specific layout evolving with compiler versions)
   • Older versions have different layouts (module file naming/location differs)—go by the unpacked manifest;file when identification fails, use xxd/python3 to read the header, first identify the compiler version, then decide on the tool (see pitfall 2)

3. Business logic recovery (strings + disassembly)：

   strings -n 8 out/ets/*.abc | grep -iE 'https?://|key|secret|token|sign' | head
   grep -rnE 'https?://|key|secret' out/resources/ | head    # 资源内字符串也是线索
   

   • String localization: strings in .abc are stored as constants, and strings/grep can fish out URLs, keys, and prompts—trace back reference points from sensitive strings and recover logic along the call chain (the approach is the same as string localization in [[re-java]])
   • ArkCompiler disassembly: after outputting instruction-level assembly, first find the entry point and sensitive string reference points, then look at constant loading and call relationships to recover the flow
   • JS/TS business resource extraction: hap may contain plaintext JS/TS fragments (assets/, rawfile, uncompiled resources)—after extraction, process them using the [[re-script-deob]] method (beautify, deobfuscate, decode)
   • When obfuscated function names become short names, fall back on strings and behavior (see pitfall 3)

4. Similarities and differences with Android：

   • No dex/smali layer: business logic is in .abc (ArkCompiler bytecode), not dex—approaches such as smali patching and baksmali do not directly apply; the counterpart is ArkCompiler disassembly
   • Resources and manifest structures are similar: module.json ≈ AndroidManifest (entry/permissions/components), resources/ ≈ res/—the resource analysis approach of [[re-apk]] (resource dumping, string resource localization) is partially reused, with tools swapped for their HarmonyOS counterparts
   • Toolchain reuse and differences: zip unpacking, string extraction,file identification, and native so analysis ([[re-format-elf]] + [[re-ghidra]]) are all reused; dex-related tools (jadx/apktool) do not apply and are replaced by the ArkCompiler disassembler; the dynamic hook approach ([[re-frida]]) is still usable on HarmonyOS emulators/real devices, with the mounting method adjusted according to environment differences

5. Dynamic side (sandbox)：

   • Observe at runtime on an emulator/real device, with orchestration via [[re-mobile]]: install hap (official deployment tool) → launch and observe → packet capture/logs → hook the runtime to obtain plaintext, mutually corroborating with static disassembly
   • Always execute within [[re-sandbox]] (emulator snapshot / controlled device + network isolation), following the default sandbox principle of [[re-analyze/platform-tips]]

Cross-domain combination

• [[re-apk]]: the zip container unpacking process shares the same origin, and the manifest/resource analysis approach is reused
• [[re-hybrid-app]]: when hap embeds a WebView/hybrid framework (JS bundle), handle it by framework type
• [[re-java]]: the jadx-style decompiler approach is reused (on the abc side, the counterpart is the ArkCompiler disassembly tool)
• [[re-mobile]]: dynamic-side orchestration (emulator/real device + hook + packet capture); this skill belongs to that gateway domain
• [[re-script-deob]]: deobfuscate the extracted plaintext JS/TS business resources
• Base: native so → [[re-binary-core]] ([[re-format-elf]] / [[re-ghidra]]); preliminary survey → [[re-triage]]; dynamic sandbox → [[re-sandbox]]; sandbox principles → [[re-analyze/platform-tips]]

Common pitfalls and traps

• Android tools opening hap directly miss the ets directory: Symptom—jadx/apktool reports errors when opening hap, or only resources and configuration are visible while business code is not; Cause—dex-based tools do not recognize .abc, and the ets/ directory is skipped; Countermeasure—follow step 1 to first perform a complete zip unpacking and manifest verification, use the ArkCompiler disassembler for business code, and do not rely on dex tools
• abc disassembler is version-sensitive: Symptom—disassembly reports errors, output is misaligned, or instructions do not match; Cause—ArkCompiler continues to evolve, and bytecode layout/instruction sets differ across compilation versions, so tools must be matched by version; Countermeasure—first identify the compilation version (file header version field + module.json/build information), then choose the corresponding version of the tool, and if necessary cross-validate with multiple implementations
• Use strings as a fallback for short names after obfuscation: Symptom—functions/variables in the disassembly are all short names, and the logic cannot be read through; Cause—build-time obfuscation/compression erases semantics; Countermeasure—fall back to the string table and resources: grep URLs/prompts/key strings → locate reference points → recover semantics along the call chain, combined with dynamic behavior comparison
• hap dual-container unpacking is incomplete: Symptom—resources/modules are missing after unpacking, or runtime resources are disordered; Cause—some build versions nest another resource container inside the zip (inner zip/resource index), and single-layer unpacking only obtains the outer layer; Countermeasure—after unpacking, check for nested containers and recursively unpack down to module/resource files, and verify completeness by comparing CRC/file counts
• Business logic is in native so: Symptom—core algorithms/encryption cannot be found in .abc; Cause—sensitive logic is pushed down into .so under libs/ (JNI/NDK style); Countermeasure—handle so with [[re-format-elf]] + [[re-ghidra]] ([[re-binary-core]]), and combine with call sites on the .abc side to reconstruct the overall flow