Mac에서 iPhone 디버깅하기

이 안내서는 Chute가 설치된 휴대전화에서 출발해, 그 휴대전화의 복호화된 요청을 요청·응답 본문과 함께 Mac 창에 띄우고 필터와 내보내기가 가능한 상태까지 갑니다. 각자 참조 페이지가 있는 것들 — CA, 호스트 목록, 기록, 제어 채널, Dashboard — 을 실제로 하는 순서대로 이어 붙이고, 각 단계에서 다음으로 넘어가기 전에 무엇이 보여야 하는지 말합니다.

필요한 것:

• 휴대전화의 Chute iOS(라이선스 포함). iPhone에서 HTTPS 복호화와 본문 캡처는 라이선스가 필요한 기능입니다. 라이선스가 없어도 아래 모든 것이 연결까지는 되지만, HTTPS 행은 불투명하고 데이터 탭은 선택할 수 없습니다. 라이선스와 활성화를 보세요.
• Mac의 Chute Dashboard — 무료, 라이선스 불필요.
• USB 케이블(권장: 네트워크에 아무것도 열 필요가 없고 셀룰러에서도 동작), 또는 휴대전화와 Mac이 같은 Wi-Fi에 있을 것.

Mac에 아무것도 설치하고 싶지 않다면, 웹 콘솔이 브라우저에서 같은 연결·본문·재작성을 보여 주며 휴대전화에는 external-http-controller만 있으면 됩니다. 아래 1–3단계는 그대로 적용되고, 4단계부터는 대신 웹 콘솔 열기를 따르세요.

1. CA 설치와 신뢰

휴대전화의 구성 편집기에서: MITM → CA 구성 → 새 CA 인증서 생성, 그다음 시스템에 CA 인증서 설치, 그리고 설정 → 일반 → 정보 → 인증서 신뢰 설정에서 신뢰합니다. 모두가 놓치는 단계를 포함한 전체 과정은 HTTPS 복호화 페이지에 있습니다.

확인할 것: 인증서 페이지에 신뢰할 수 있는 CA 인증서라고 표시됩니다. 신뢰할 수 없는이라고 나오면 인증서 신뢰 설정의 신뢰 스위치가 아직 꺼져 있는 것입니다 — 켜기 전까지 뒤의 어떤 것도 동작하지 않습니다.

2. 복호화할 호스트 지정

Chute는 나열한 호스트만 복호화합니다. 편집기의 MitM 섹션(CA 구성이 있는 곳)에서 보고 싶은 호스트를 추가합니다. *가 아니라 좁게 시작하세요 — 디버깅 중인 앱의 API 호스트처럼. 복호화하는 호스트마다 휴대전화의 CPU를 쓰고, 인증서를 고정한 앱은 복호화되면 망가집니다. *.apple.com은 처음부터 제외하는 것이 좋습니다.

[MITM]
enable = true
hostname = api.example.com, *.example.net, -*.apple.com

문법 — 포트, - 제외, /path 범위 — 은 HTTPS 복호화 페이지에 있습니다. 나중에 Dashboard의 MitM 규칙 패널에서 효과를 보며 호스트를 넣고 빼다가, 동작하는 것을 구성에 옮겨 적을 수도 있습니다.

3. 복호화와 기록 켜기

휴대전화의 제어판에서 스위치 두 개:

• MitM — 2단계의 호스트에 대한 복호화를 켭니다.
• 트래픽 캡처 — 요청과 응답 본문을 기록합니다(replica 설정). 없으면 Dashboard는 모든 연결을 규칙·정책과 함께 보여 주지만 데이터는 없습니다.

둘 다 나중에 Dashboard 도구 막대에서 켤 수 있으니 지금 잊어도 괜찮습니다. 구성에 적혀 있지 않으면([General]의 replica = true, [MITM]의 enable = true) 둘 다 재시작 후 유지되지 않으며, iPhone에서는 둘 다 라이선스가 필요한 기능이라 라이선스가 없으면 구성이 무엇이라고 하든 엔진이 거부합니다.

4. Dashboard 연결 허용

구성 편집기에서: 외부 컨트롤러.

1. 외부 컨트롤러 접근을 켭니다 — 각주에 Chute Dashboard/Chute CLI 연결 허용이라고 적혀 있습니다.
2. 포트(빈 포트 아무거나; 특별히 없으면 6170)와 직접 정한 비밀번호를 입력합니다.
3. Wi-Fi 접근 허용: USB라면 꺼짐으로 둡니다. Wi-Fi로 연결할 때만 켜세요 — 그 네트워크에서 비밀번호를 아는 모두에게 리스너가 열립니다.
4. 저장한 뒤 터널을 시작(또는 재시작)합니다.

확인할 것: 제어판에 외부 접근 포트: 6170(내 포트)이 표시됩니다. 이 줄이 없으면 터널이 저장된 구성으로 돌고 있지 않은 것입니다 — 재시작하세요.

5. Dashboard 연결

휴대전화를 케이블로 Mac에 꽂고, 휴대전화가 물으면 이 컴퓨터를 신뢰합니다. Chute Dashboard를 열고 새 대시보드 창에서 USB로 연결을 고른 뒤, 기기: 에서 휴대전화를 선택하고 4단계의 포트와 비밀번호를 넣고 연결합니다.

대신 Wi-Fi로 하려면: 원격 컴퓨터에 연결에서 호스트에 휴대전화 주소(설정 → Wi-Fi → ⓘ의 IP 주소), 같은 포트와 비밀번호를 넣습니다.

확인할 것: 새 Dashboard 창이 열리고, 휴대전화가 연결을 만들수록 활성 목록이 채워집니다. 비어 있으면 휴대전화를 몇 초 써 보세요. 여기서 잘못될 수 있는 것은 두 가지입니다: 비밀번호가 일치하지 않음, 그리고 휴대전화에 닿지 못하는 경우(주소가 틀림, Wi-Fi 접근 꺼짐, 터널이 안 돌고 있음)입니다 — 이때도 창은 열리며, Wi-Fi에서는 결국 연결이 종료되었습니다로 끝나고, USB에서는 휴대전화가 응답할 때까지 재시도하며 연결 중…에 머뭅니다. 자세한 내용은 Dashboard 페이지에 있습니다.

6. 도구 막대 스위치 확인

활성 목록 위에 3단계의 두 스위치가 Dashboard가 보는 대로 있습니다:

• 트래픽 캡처는 트래픽 캡처 사용 안 함이라고 보여야 합니다 — 기록이 켜져 있습니다. 트래픽 캡처 사용이라고 보이면 누르세요.
• MitM 사용(규칙 N개)은 MitM 사용 안 함(규칙 N개)이라고 보여야 합니다 — 복호화가 켜져 있고, N은 2단계의 호스트 수입니다. 버튼에 (규칙 N개) 개수가 없으면 호스트 목록이 휴대전화에 닿지 않은 것입니다: 2단계를 확인하고 터널을 재시작하세요.

7. 재현하고 요청 찾기

트래픽을 보고 싶은 앱에서 그 동작을 합니다. 그다음 목록 위의 필터 막대로 목록을 좁힙니다: 호스트/URL 필터…에 호스트를 입력하거나 — 도구 막대의 필터 필드도 같은 검색입니다 — MitM만을 켜서 복호화된 행만 남깁니다.

확인할 것: 내 호스트의 행에 플래그 열의 M이 있습니다. 메서드 열은 동사가 아니라 연결 유형 — HTTPS — 을 보여 줍니다: 요청 줄과 상태 줄은 요청 헤더와 응답 헤더의 첫 행입니다. 하나를 선택하면 요청 헤더 탭에 헤더·쿼리 매개변수·쿠키가 있고, 응답 데이터에 본문이 텍스트로 보이며, JSON을 고르면 트리로, 이미지를 고르면 그림으로 볼 수 있습니다.

내 호스트의 행에 M이 없다면 그 연결은 복호화되지 않은 것입니다. 가능성 높은 순서로: 호스트가 목록에 없음(또는 패턴이 맞지 않음 — api.example.com은 www.example.com을 포함하지 않음), MitM이 꺼짐, CA가 설치됐지만 신뢰되지 않음(앱 자체가 인증서 오류를 보일 것임), 앱이 인증서를 고정함(호스트를 제외하고 안을 볼 수 없음을 받아들임), 앱이 QUIC 위의 HTTP/3를 씀 — 복호화할 수 없으니 block-quic으로 TCP로 되돌립니다.

행에 M은 있는데 요청 데이터와 응답 데이터를 선택할 수 없다면 아무것도 캡처되지 않은 것입니다: 그 연결이 실행될 때 기록이 꺼져 있었거나(켜고 다시 재현), 휴대전화의 [Replica]가 호스트를 걸러 냈습니다. 2 MiB보다 큰 본문은 휴대전화가 넘겨주기를 거부하며, 그 탭에는 본문을 불러올 수 없습니다라고 표시됩니다.

8. 찾은 것 보관

행들을 선택하고 그중 한 행을 오른쪽 클릭: 선택 항목을 HAR로 내보내기…는 선택한 행 모두를 본문과 함께 브라우저 개발자 도구, Charles, Proxyman에서 열리는 파일로 쓰고, curl 명령 복사는 오른쪽 클릭한 행의 요청을 복사해 Mac 터미널에서 다시 보낼 수 있게 하며, 선택 항목을 CSV로 내보내기…로 스프레드시트용 파일을 얻습니다. 데이터 탭 안의 bin으로 내보내기는 본문 하나를 캡처된 그대로 저장합니다.

9. 무언가 바꿔 보기(선택)

MitM 보기의 패널은 실행 중인 엔진을 편집합니다. 빠른 실험 두 가지:

• 헤더 재작성 → 내 호스트에 규칙 추가: 요청, 추가, X-Debug = 1. 재현하면 새 행에 H와 R이 붙고, 상세 패널의 적용된 규칙에 내 규칙이 인용됩니다.
• 모의 응답 → 어떤 엔드포인트에 직접 만든 본문으로 응답하기. 응답 본문 유형은 팝업 메뉴이며(file, text, base64, tiny-gif), 그 옆의 상자에는 유형에 필요한 것을 넣습니다: file이면 경로(찾아보기…로 고를 수 있음), text면 본문 자체, base64면 그 base64, tiny-gif면 아무것도 넣지 않습니다. file 경로는 휴대전화가 읽는데 휴대전화에는 /Users/… 같은 것이 없으므로, 휴대전화라면 text나 base64를 골라 본문을 바로 이 패널의 규칙 안에 적으세요 — MitM 도구의 알림 참조. 모의 응답이 답한 행에는 K가 붙습니다.

여기서 추가한 규칙은 터널이 재시작되면 사라집니다. 동작하는 것은 구성에 적으세요 — 참조 페이지: URL 재작성, 헤더 재작성, 본문 재작성, 모의 응답.

끝났을 때

• 트래픽 캡처를 끄거나 replica = false로 두세요: 기록이 켜져 있는 동안 본문이 휴대전화에 계속 쌓입니다.
• Wi-Fi 접근 허용을 켰다면 다시 끄세요.
• 다시 할 거라면 CA는 설치된 채로 두고, 아니라면 설정 → 일반 → VPN 및 기기 관리에서 제거하세요.