이 저장소는 정답이 있는 교육용 취약 앱이 아니라, 실제 AOSP 빌드·서비스·HAL·커널·TEE·Secure Element 스택을 에뮬레이터에서 조사하는 연구 작업공간이다. 조사 대상, 실행 이미지, 도구 버전, 명령 원문, 증거 해시와 재현 절차를 한 케이스에 묶고 마지막에 보고서를 생성한다.
현재 host 준비 상태, 즉시 실행 순서와 남은 외부 검증은
docs/PROJECT-STATUS.md에서 먼저 확인한다.
에뮬레이터는 실제 OEM SoC와 완전히 같을 수 없다. 이 프로젝트는 차이를 숨기지 않고 아래 세 실행 계층을 함께 사용한다.
| 계층 | 실행 위치 | 적합한 연구 | 핵심 한계 |
|---|---|---|---|
| macOS AOSP AVD | Apple Silicon Mac의 Android Emulator | framework, system_server, Binder, 앱 샌드박스, native/media, goldfish/ranchu 커널 |
OEM vendor blob, 실제 RF, TrustZone, 실제 eSE가 없음 |
Cuttlefish userdebug |
KVM이 있는 Linux 호스트 | AIDL HAL, VINTF/VTS, system/vendor 경계, RootCanal, 가상 eSE/OMAPI | macOS에서 직접 실행 불가, 실제 SoC 주변장치와 다름 |
| OP-TEE QEMU v8 | Linux 컨테이너 또는 Linux 호스트의 QEMU | ARM TrustZone 경계, TEE core, TA/CA, SMC, secure storage | Qualcomm/Samsung 등 상용 TEE 구현과 동일하지 않음 |
macOS에서는 AVD를 즉시 사용하고, HAL/eSE의 충실도가 필요한 케이스는 infra/cuttlefish의 Linux KVM 실행기로 전환한다. AOSP는 Android 11 이후 macOS 빌드를 공식 지원하지 않으므로 AOSP 전체 빌드도 Linux에서 수행한다.
| 디렉터리 | 연구면 |
|---|---|
targets/android-system |
Framework, system_server, Binder 서비스, 권한·AppOps |
targets/android-hal |
Stable AIDL/HIDL, hwservicemanager, VINTF, VTS, SELinux |
targets/android-kernel |
GKI/goldfish 커널, 드라이버, ioctl, eBPF, binderfs |
targets/android-native-media |
native daemon, codec/parser, Stagefright, DRM, sanitizer/fuzzer |
targets/android-connectivity |
Bluetooth/RootCanal, NFC, Wi-Fi, telephony 경계 |
targets/android-app-sandbox |
PackageManager, component/URI 노출, WebView, sandbox 탈출 전제 |
targets/android-boot-chain |
AVB, boot image, init, dynamic partition, SELinux 정책 |
targets/arm-trustzone |
OP-TEE/QEMU의 Secure/Normal World, TA/CA, SMC |
targets/android-ese |
OMAPI → Secure Element Service → AIDL SE HAL → 가상 eSE/APDU |
# 1. 상태만 점검한다. 시스템을 변경하지 않는다.
./labctl doctor
# 2. 저장소 내부에 JDK, Android SDK/Emulator와 AOSP arm64 이미지를 설치한다.
# Android SDK 라이선스는 사용자가 직접 확인·승인해야 한다.
./scripts/bootstrap-macos.sh android
# 3. 셸 환경을 로드하고 격리된 AVD를 만든 뒤 시작한다.
source ./scripts/android-env.sh
./infra/android-avd/create.sh
./infra/android-avd/start.sh baseline
# 4. 실제 조사 케이스를 만들고 타깃별 증거를 수집한다.
./labctl new android-system SYS-001
./labctl collect android-system SYS-001
# 5. finding을 작성하고 조사 중임을 표시한 draft를 생성한다.
./labctl add-finding SYS-001
./labctl report SYS-001 --draft
# 6. TODO와 finding 검증을 모두 마친 뒤 케이스를 완료하고 final을 생성한다.
./labctl status SYS-001 complete
./labctl report SYS-001생성 데이터는 .lab/ 아래에만 저장되고 Git에 포함되지 않는다. 케이스 경로는 .lab/cases/<CASE_ID>이며 원시 증거, 명령, 종료 코드, SHA-256 manifest가 함께 보존된다.
HAL/eSE 통합 조사는 macOS AVD quickstart가 아니라 infra/cuttlefish의 Linux
KVM 계층을 먼저 준비한다.
저장소 계약과 보고 파이프라인 자체를 실제로 검사하려면:
make validate
make selftest직접 다운로드하는 도구는 version과 macOS architecture별 SHA-256을
config/toolchain.lock에 고정한다. bootstrap과 Frida 설치, evidence 수집은 같은
host toolchain lock을 공유하며, device를 변경하는 Frida 설치는 선택한
AVD/Cuttlefish runtime lock도 함께 보유한다.
- 해당
targets/<target>/README.md의 Step 0 — Emulator에서 맞는 실행 계층을 고른다. - 깨끗한 스냅샷과 빌드 fingerprint를 기록한다.
- 제공된 수집 스크립트로 공격면 baseline을 만든다.
- 정적 분석 → 동적 계측 → fuzzing → crash triage 순으로 진행한다.
- 같은 이미지에서 재현하고, 가능하면 패치 빌드와 비교한다.
- finding마다 최소 재현, 영향, 신뢰 경계, 로그/trace/tombstone 해시를 기록한다.
- 조사 중에는
./labctl report <CASE_ID> --draft를 사용한다. - 모든 TODO와 finding 검증을 마친 뒤
./labctl status <CASE_ID> complete,./labctl report <CASE_ID>순서로 최종 보고서를 만든다.
세부 공통 절차는 docs/RESEARCH-METHOD.md, 도구별 목적과 사용법은 docs/TOOLS.md, 환경별 사실과 한계는 docs/FIDELITY.md, 타깃 선정 근거는 docs/TARGET-SELECTION.md, 보고 체계는 docs/REPORTING.md를 따른다.
자신이 소유하거나 명시적으로 허가받은 이미지·소스·가상 장치만 대상으로 한다. 기본 스크립트는 실제 기기 자동 탐색이나 원격 대상 스캔을 하지 않으며, 지정된 emulator serial이 아니면 중단한다. 실제 계정·개인정보·결제 자격증명은 랩에 넣지 않는다.
공식 기준과 버전 기준일은 config/toolchain.lock 및 각 문서의 Sources에 고정한다.