ArkGuard Obfuscation Tool Guide: Secure HarmonyOS Code with Step-by-Step Configuration

Introduction to Code Obfuscation

ArkGuard is a source code obfuscation tool that provides basic obfuscation capabilities. After software release, code can be easily obtained and analyzed; clear variable and function names allow attackers or competitors to understand logic, core algorithms, and key flows. Obfuscation techniques such as renaming transform meaningful identifiers into short, irregular characters, significantly increasing the difficulty and cost of manual code reading.

Enabling Obfuscation

1. Enable Obfuscation Switch

Configure in the module's build-profile.json:

"arkOptions": {
  "obfuscation": {
    "ruleOptions": {
      "enable": true,
      "files": ["./obfuscation-rules.txt"]
    }
  }
}

2. Configure Obfuscation Rules

Starting from DevEco Studio 5.0.3.600, new projects include four default rules in obfuscation-rules.txt:

-enable-property-obfuscation
-enable-toplevel-obfuscation
-enable-filename-obfuscation
-enable-export-obfuscation

Developers can customize these rules as needed.

Obfuscation Options

Default obfuscation (varies by version) — takes effect after enabling obfuscation

Disable obfuscation — -disable-obfuscation Enable property name obfuscation — -enable-property-obfuscation Enable string property name obfuscation — -enable-string-property-obfuscation Enable top-level scope name obfuscation — -enable-toplevel-obfuscation Enable import/export name obfuscation — -enable-export-obfuscation Enable filename obfuscation — -enable-filename-obfuscation Code compression — -compact Remove declaration file comments — -remove-comments Remove console.* statements — -remove-log Output name cache — -print-namecache Reuse name cache — -apply-namecache Output unobfuscated name list — -print-kept-names Reduce language default whitelist — -extra-options strip-language-default Reduce system API default whitelist — -extra-options strip-system-api-args Keep declaration file parameters — -keep-parameter-names Merge dependent module options — -enable-lib-obfuscation-options Mark whitelist via source comments —

-use-keep-in-source

3. Configure Retention (Keep) Options

After enabling obfuscation, methods, properties, or paths may be obfuscated, potentially causing runtime failures when accessing unobfuscated objects. Retention options prevent this:

Keep specific property names — -keep-property-name Keep top-level scope or import/export element names — -keep-global-name Keep file/folder names — -keep-file-name Keep comments — -keep-comments Keep all names in declaration files — -keep-dts Keep all names in source files —

-keep

4. Specify Release Compilation

Source code obfuscation only supports release builds, not debug builds. In DevEco Studio, select the build mode via the top-right icon. Debug builds contain extensive debug information (variable names, function names, line numbers) that become meaningless or cause errors after obfuscation.

ObfuscationHelper Tool

A tool that scans modules and scenarios to quickly identify required retention options and whitelist fields, generating Hm-recommend-keep-list.txt.

Step 1: Open ObfuscationHelper

Menu: Tools → ObfuscationHelper, or right-click a module in the project pane.

Step 2: Select Modules and Scenarios to Scan

Choose modules to scan. If a module previously generated a whitelist, history records appear; selecting them associates prior investigation records so already-reviewed whitelist fields are not re-checked.

Click "Generate Recommended Whitelist" to create the recommendation file under the corresponding module.

Step 3: Manual Whitelist Investigation

For DevEco Studio 6.0.0 Beta1 and above:

"Pending Investigation" shows items that could not be auto-resolved; developers must inspect business logic to identify whitelist fields.

If no whitelist needed, mark as "Investigated".

If whitelist needed, click "Add Whitelist", enter retention option and field, then save.

After investigation, click "Generate Investigation Whitelist" to produce Hm-manual-keep-list.txt / Hm-manual-consumer-keep-list.txt under the module, plus an Excel report obfuscation-helper-xxx.xlsx at the project root. If "Merge Whitelist Files" is checked, a merged Hm-merge-manual-keep-list.txt is also created.

For DevEco Studio versions below 6.0.0 Beta1: manual rule and whitelist entry is required, and history association is not supported.

Step 4: Add Whitelist Files to Obfuscation Configuration

Two methods:

In each module's build-profile.json5, add Hm-manual-keep-list.txt to the files field and Hm-manual-consumer-keep-list.txt to the consumerFiles field.

Place the merged Hm-merge-manual-keep-list.txt in the entry module's build-profile.json5 under files.

Common Issues

Scenario 1: Property Obfuscation Breaks System API Calls Using Record Objects

Analysis: System APIs are not obfuscated; when Record keys are obfuscated, the system API cannot retrieve the original key values.

Solution: Add the Record type's key values to the property whitelist.

Scenario 2: Excluding a Third-Party HAR Package from Obfuscation

Solution: In the module consuming the third-party HAR, configure -keep ./oh_modules/third-party-library-name.

For additional scenarios, refer to the official documentation: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/source-obfuscation-questions