ArkGuard 난독화 활성화 및 설정 가이드

소스코드 난독화 활성화

ArkGuard 난독화 기능은 시스템에 내장되어 있으며, DevEco Studio에서 다음 절차에 따라 활성화할 수 있습니다.

난독화 스위치 켜기

모듈의 build-profile.json5 설정 파일 내 arkOptions.obfuscation.ruleOptions 항목에서 enable 필드를 통해 난독화 사용 여부를 지정합니다.

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

난독화 규칙 구성

스위치만 켜면 기본 난독화(지역 변수 및 매개변수 대상)만 적용됩니다. 추가 기능을 사용하려면 files 필드가 가리키는 설정 파일에서 세부 옵션을 지정해야 합니다. DevEco Studio 버전별로 기본값에 차이가 있을 수 있습니다.

DevEco Studio 5.0.3.600 이상 버전의 기본 설정 파일 예시입니다. 속성명, 최상위 식별자, 파일명, 임포트/익스포트 이름 난독화를 모두 활성화합니다:

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

설정 파일에서는 # 기호로 주석을 작성할 수 있습니다. 줄 시작 부분의 # 뒤 내용은 모두 무시됩니다:

# 기본 옵션
-enable-property-obfuscation
-enable-toplevel-obfuscation
-enable-filename-obfuscation
# -enable-export-obfuscation  # 일시 비활성화
-keep-property-name # 동적 속성명 보존용

참고: DevEco Studio 5.0.3.600 미만 버전에서는 신규 프로젝트가 기본적으로 난독화가 켜진 상태로 생성되며, API 10 이상 Stage 모델에 자동 적용되었습니다. 5.0.3.600 이상에서는 기본적으로 꺼져 있으며, 수동으로 enable: true로 설정해야 합니다. 이 경우 obfuscation-rules.txt에 위 네 가지 권장 옵션이 기본 포함되어 있습니다.

release 모드 빌드 지정

소스코드 난독화는 release 빌드에서만 수행되며 debug 빌드에서는 적용되지 않습니다. 스위치를 켜면 release 빌드 시에만 난독화가 진행됩니다.

주의: release와 debug의 차이는 난독화뿐만 아니라 다양합니다. 난독화로 인한 문제인지 확인하려면 스위치만 조정하여 테스트하세요.

세 가지 난독화 설정 파일

파일명유형수정 가능본 모듈 영향다른 모듈 영향
obfuscation-rules.txt사용자 정의예예아니오
consumer-rules.txt사용자 정의예아니오예
obfuscation.txt빌드 산출물자동 생성해당 없음예

obfuscation-rules.txt

HAP, HAR, HSP 모듈의 build-profile.json5에 arkOptions.obfuscation.ruleOptions.files 필드로 지정됩니다. 해당 모듈을 컴파일할 때 적용되는 규칙입니다. 신규 프로젝트 생성 시 기본으로 생성됩니다.

consumer-rules.txt

HAR 모듈 전용으로, arkOptions.obfuscation.consumerFiles 필드에 지정합니다. 해당 패키지가 다른 모듈에 의존될 때 그 모듈의 빌드 과정에서 적용되는 규칙입니다.

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

이 파일의 규칙이 상위 모듈에 영향을 줄 수 있으므로, 보존(-keep) 관련 설정만 구성하는 것을 권장합니다.

obfuscation.txt

개발자가 직 수정하지 않는 파일로, HAR 빌드 시 consumer-rules.txt와 의존 모듈의 규칙을 병합하여 자동 생성됩니다. 배포되는 HAR 패키지에 포함되며, 해당 패키지를 의존하는 모듈이 빌드될 때 규칙이 병합되어 적용됩니다.

참고: oh-package.json5에서 모듈 수준으로 의존할 때만 적용되며, 프로젝트 수준 의존 시에는 무시됩니다.

단계별 난독화 옵션 적용

1단계: 최상위 식별자 난독화

-enable-toplevel-obfuscation을 활성화합니다. globalThis로 전역 변수에 접근하는 코드가 있다면 접근 실패가 발생할 수 있으므로, -keep-global-name으로 해당 변수명을 보존하세요.

2단계: 속성명 난독화

1단계 적용 후 -enable-property-obfuscation을 활성화합니다. 다음 상황에 주의가 필요합니다:

  • 정적 정의/동적 접근 또는 동적 정의/정적 접근: -keep-property-name으로 속성명 보존
// 정적 정의, 동적 접근
const dataStore = {
  userToken: "abc123"
};
const keyFragment = "user" + "Token";
console.log(dataStore[keyFragment]); // 대괄호 문법으로 동적 접근

// 동적 정의, 정적 접근
const dynamicKey = computedPropertyName();
const config = {
  [dynamicKey]: "value"
};
console.log(config.presetKey); // 점 문법으로 정적 접근
  • 네이티브 라이브러리, JSON, 데이터베이스 필드 접근: -keep-property-name으로 필드명 보존
// SO 라이브러리 API
import { nativeMethod } from 'libsample.so';
// -keep-property-name nativeMethod 필요

// JSON 파일 필드
// -keep-property-name fieldFromJson 필요

// 데이터베이스 컬럼
// -keep-property-name dbColumnName 필요
  • HAR 배포 시: consumer-rules.txt에서 재난독화되어서는 안 되는 속성을 -keep-property-name으로 지정

3단계: 익스포트 난독화

2단계 적용 후 -enable-export-obfuscation을 활성화합니다. 다음 상황에 주의가 필요합니다:

  • HSP 모듈: 외부에 제공하는 인터페이스는 -keep-global-name으로, 클래스/인터페이스의 속성은 -keep-property-name으로 보존
  • HAR 모듈 배포: obfuscation-rules.txt에서 외부 인터페이스와 노출 속성을 각각 보존
  • SO 라이브러리 임포트: import { apiName } from 'lib.so' 형태는 -keep-global-name apiName 필요

4단계: 파일명 난독화

3단계 적용 후 -enable-filename-obfuscation을 활성화합니다. 다음 상황에 주의가 필요합니다:

  • 동적 임포트: const modulePath = './utils/helper'; import(modulePath) 형태는 -keep-file-name helper 필요
  • 라우터 맵 설정: routerMap의 pageSourceFile 경로는 -keep-file-name으로 보존
  • ohmUrl 기반 페이지 이동: router.pushUrl({url: '@bundle:com.example.app/Module/Page'}) 형태는 경로 보존 필요

오류 발생 시 build/default/[...]/release/obfuscation/nameCache.json에서 난독화된 이름과 원본 이름의 매핑을 확인할 수 있습니다. hstack 플러그인을 활용하면 오류 스택을 자동 복원할 수 있습니다.

난독화 결과 확인

빌드 완료 후 다음 경로에서 산출물을 확인할 수 있습니다:

  • 난독화된 소스: build/default/[...]/release/{모듈명}
  • 이름 매핑 및 시스템 API 화이트리스트: build/default/[...]/release/obfuscation
    • nameCache.json: 원본명 ↔ 난독화명 매핑 테이블
    • systemApiCache.json: SDK 인터페이스/속성명 (이와 중복되는 이름은 난독화 제외)

오류 스택 복원

난독화된 앱에서 발생한 crash의 스택 추적은 가독성이 떨어집니다. DevEco Studio Command Line Tools의 hstack 플러그인을 사용하여 원본 소스 기준 스택으로 복원하세요.

복원에 필요한 파일:

  • sourceMaps.map: 빌드 과정에서 생성된 소스맵
  • nameCache.json: 난독화 이름 매핑 정보

위 파일들은 반드시 로컬에 백업해두어야 합니다.

제약사항:

  • hvigor 빌드 프로세스에 사용자 정의 난독화 플러그인 삽입은 지원되지 않습니다.
  • 난독화된 HAR를 의존하는 모듈이 난독화를 켜면, 해당 HAR는 재난독화됩니다.

태그: ArkGuard DevEco Studio HAP HAR HSP

5월 25일 10:19에 게시됨

인기 태그

©2026 괴물 클럽