macOS Bootloader Patcher

macOS Virtualization Framework VM에서 서드파티 커널 확장을 실행하기 위한 iBoot 모듈 및 커널 캐시 패치 도구입니다.

기능

핵심 기능

이 도구는 다음과 같은 패치 작업을 자동화합니다:

• iBoot Stage 0 (AVPBooter.vmapple2.bin) - 호스트 시스템의 부트로더 패치
• iBoot Stage 1 (LLB.img4) - VM의 LLB (Low-Level Bootloader) 패치
• iBoot Stage 2 (iBoot.img4) - VM의 iBoot 패치
• Kernel Cache (kernelcache) - VM의 커널 캐시 패치

필수 도구

• img4tool - img4 파일 처리용
• openssl - ASN1 파싱용 (일반적으로 시스템에 포함)
• xxd - 16진수 덤프용 (일반적으로 시스템에 포함)

설치

# img4tool 설치 (예: Homebrew)
brew install img4tool

# 또는 소스에서 빌드
git clone https://github.com/tihmstar/img4tool.git
cd img4tool
./autogen.sh
./configure
make
sudo make install

패키지 설치

# 저장소 클론
git clone <repository-url>
cd MacOs-Bootloader-Patch-Tools

# 설치 (개발 모드)
pip install -e .

# 또는 직접 실행
python -m bootloader_patcher.cli --help

사용법

기본 명령어

1. iBoot Stage 0 패치

bootloader-patcher stage0 /System/Library/Frameworks/Virtualization.framework/Resources/AVPBooter.vmapple2.bin

2. iBoot Stage 1 (LLB) 패치

bootloader-patcher stage1 LLB.img4.org --work-dir ./work

3. iBoot Stage 2 패치

bootloader-patcher stage2 iBoot.img4.org --work-dir ./work

4. Kernel Cache 패치

# 함수 주소를 알고 있는 경우
bootloader-patcher kernelcache kernelcache.org --work-dir ./work --validate-addr 0xfffffe0008be57ec

# 함수 주소를 모르는 경우 (수동 패치 필요)
bootloader-patcher kernelcache kernelcache.org --work-dir ./work

--validate-addr 옵션 설명:

--validate-addr는 커널 캐시 내에서 _validate_acm_context() 함수의 메모리 주소를 지정합니다. 이 함수는 서드파티 커널 확장을 차단하는 검증 로직을 수행하며, 이 함수를 호출하는 위치를 NOP 명령어로 교체해야 합니다.

함수 주소 찾는 방법:

• IDA Pro: kernelcache.bin을 열고 __validate_acm_context 함수로 이동하여 주소 확인
• Hopper: Loader에서 com.apple.security.AppleVPBootPolicy 선택 후 함수 검색
• 상세 정보는 KERNEL_CACHE_EXPLANATION.md 참고

5. AuxiliaryStorage에서 LLB 추출

bootloader-patcher extract-aux ~/Library/Containers/com.utmapp.UTM/Data/Documents/VM.utm/Data/AuxiliaryStorage --output ./extracted

전체 프로세스 자동화

bootloader-patcher all \
    --avp-booter /path/to/AVPBooter.vmapple2.bin \
    --llb-img4 LLB.img4.org \
    --iboot-img4 iBoot.img4.org \
    --kernelcache kernelcache.org \
    --aux-storage AuxiliaryStorage \
    --work-dir ./work \
    --validate-addr 0xfffffe0008be57ec

패치 상세 설명

iBoot Stage 0

• 파일: AVPBooter.vmapple2.bin
• 위치: 호스트 시스템 (/System/Library/Frameworks/Virtualization.framework/Resources/)
• 패치 내용: image4_validate_property_callback() 함수의 반환 값을 0으로 변경
• 패치 바이트: E0 03 14 AA (MOV X0, X20) → 00 00 80 D2 (MOV X0, #0)

iBoot Stage 1 (LLB)

• 파일: LLB.img4
• 위치: VM의 AuxiliaryStorage 파일 내부
• 패치 내용: Stage 0과 동일한 패치 적용
• 처리: img4 형식 압축 해제 → 패치 → 재포장

iBoot Stage 2

• 파일: iBoot.img4
• 위치: VM 파일 시스템 내
• 패치 내용: validate_boot_object() 함수 호출 제거
• 처리: img4 압축 해제 → PAYP 구조 보존 → 패치 → 재포장

Kernel Cache

• 파일: kernelcache
• 위치: VM 파일 시스템 내
• 패치 내용: _validate_acm_context() 함수 호출을 NOP로 교체 (2곳)
• 처리: img4 압축 해제 → PAYP 구조 보존 → 패치 → 재포장

주의사항

1. 백업 필수: 모든 원본 파일은 자동으로 .org 확장자로 백업됩니다.

2. 수동 확인 필요: 일부 패치 작업은 바이너리 분석이 필요할 수 있습니다:

   • Kernel Cache의 _validate_acm_context() 함수 주소
   • 일부 버전에서 패턴이 다를 수 있음

3. 시스템 보호 해제: 호스트 시스템에서 다음 설정이 필요합니다:

   csrutil disable
   csrutil authenticated-root disable

4. VM 설정: 게스트 VM에서도 보안 설정을 낮춰야 합니다.

5. 재부팅 필요: Stage 0 패치 후 호스트 시스템 재부팅이 필요합니다.

문제 해결

패치 실패

• 파일 경로 확인
• 필요한 도구가 설치되어 있는지 확인 (img4tool, openssl, xxd)
• 파일 권한 확인

PAYP 구조 찾기 실패

• ASN1 파싱 출력 확인
• 수동으로 오프셋 찾기:

  openssl asn1parse -inform der -in file.im4p -i -dump | grep PAYP

Kernel Cache 패치 실패

• 함수 주소를 수동으로 찾기 (Hex Fiend, IDA Pro, Hopper 등)
• 주소를 --validate-addr 옵션으로 전달

참고 자료

• img4tool
• NyanSatan's Virtual-iBoot-Fun
• steven-michaud/ThirdPartyKexts.md