Proxyman Network Extension: 프록시 설정 없이 Mac 트래픽 캡처

5분 분량

이제 Proxyman이 Network Extension을 지원합니다 🎉

시스템 프록시를 무시하는 앱을 포함해, Mac의 앱과 스크립트에서 발생하는 HTTP/HTTPS 트래픽을 캡처하세요. 앱마다 프록시를 설정할 필요가 없습니다.

이 글에서 다루는 내용은 다음과 같습니다:

• 일반 프록시 모드의 문제점.
• Network Extension이 누락된 트래픽을 캡처하는 데 도움이 되는 방법.
• 켜는 방법과 기존 디버깅 도구를 사용하는 방법.
• Automatic Setup으로 Node.js, Ruby, Python의 SSL 오류를 해결하는 방법.

1. 일반 프록시 모드의 문제점

일반 프록시 모드는 macOS에 HTTP/HTTPS 프록시를 설정하여 작동합니다. 이 설정을 따르는 앱은 요청을 Proxyman을 거쳐 보냅니다.

하지만 일부 앱과 라이브러리는 시스템 프록시를 사용하지 않습니다:

• 요청 누락: 브라우저의 트래픽은 보이지만, 스크립트나 백엔드 서버에서 보낸 요청은 빠져 있을 수 있습니다.
• 별도의 프록시 설정: 라이브러리에 따라 Node.js, Ruby, Python, 명령줄 도구는 각각 고유한 프록시 설정이 필요할 수 있습니다.
• 코드 변경: 일부 라이브러리는 코드에서 프록시 주소를 직접 전달해야 합니다.
• 반복되는 설정: 다른 프로젝트나 HTTP 라이브러리로 바꾸면 프록시를 다시 설정해야 할 수 있습니다.

요청은 여전히 서버에 도달하지만 Proxyman은 거치지 않습니다. 라이브러리마다 직접 설정하는 데는 시간이 걸리고 실수로 이어질 수도 있습니다.

2. 해결책: Network Extension ✅

Network Extension은 시스템 수준에서 HTTP/HTTPS 연결을 캡처하여 Proxyman으로 라우팅합니다. 앱이 macOS 프록시 설정을 무시하더라도 요청을 캡처할 수 있습니다.

• 앱마다 프록시 주소를 입력할 필요가 없습니다.
• Proxyman으로 요청을 라우팅하기 위해 앱 코드를 바꿀 필요가 없습니다.
• 위 스크린샷에서처럼 --proxy 플래그 없이 cURL을 실행하세요.
• Proxyman이 요청을 캡처하는 동안에도 앱과 스크립트를 평소처럼 사용하세요.

이를 **투명 프록시(transparent proxy)**라고 합니다. 연결 라우팅은 macOS가 처리하므로 앱이 프록시 자체를 관리할 필요가 없습니다.

Apple의 공식 Network Extension API 기반

• Apple의 공식 투명 프록시 Network Extension API를 사용합니다.
• Proxyman이 직접 만들고 유지 관리하는 네이티브 macOS 시스템 확장으로 실행됩니다.
• TablePlus Inc Developer ID 인증서로 서명되었고 Apple의 공증을 받았습니다.
• macOS의 표준 확장 설정을 통해 설치하고 승인합니다.

목표는 Apple의 네이티브 네트워킹 API를 사용해 빠르고 효율적으로 캡처하면서, 디버깅을 시작하기 전 설정은 최소화하는 것입니다.

3. 무엇을 할 수 있나요?

캡처된 요청에도 이미 사용 중인 Proxyman 도구를 그대로 쓸 수 있습니다:

• 🔎 요청과 응답 검사: URL, 쿼리 파라미터, 헤더, 쿠키, 본문을 읽으세요. 서버가 반환한 응답 상태와 데이터를 확인하세요.
• 🧹 트래픽 필터링: 디버깅하려는 앱이나 도메인에 집중하고, 관련 없는 요청은 목록에서 숨기세요.
• 📁 Map Local: 저장된 응답을 반환해 백엔드를 바꾸지 않고 다양한 데이터를 테스트하세요.
• ✍️ Breakpoint: 요청이나 응답을 일시 중지하고 수정한 뒤, 앱이 그 변경을 어떻게 처리하는지 확인하세요.
• ⚙️ Scripting: 테스트 중에 자신만의 규칙을 적용해 요청과 응답을 수정하세요.

다음과 같은 경우에 유용합니다:

• 로컬 백엔드 서버가 보내는 API 호출을 검사할 때.
• Ruby나 Python 스크립트가 서비스에 무엇을 보내는지 확인할 때.
• 프록시 설정이 없는 Mac 앱의 트래픽을 캡처할 때.
• 여러 앱의 요청을 앱마다 따로 설정하지 않고 디버깅할 때.

4. Network Extension 켜는 방법

1. 최신 macOS용 Proxyman을 다운로드하여 엽니다.
2. Settings → Network Extension을 엽니다.
3. Enable Network Extension을 켜고, 표시되면 Install and Enable을 클릭합니다.

4. macOS 안내에 따라 System Settings → General → Login Items & Extensions → Network Extensions에서 Proxyman을 활성화합니다.
5. macOS가 네트워크 구성을 추가할지 묻면 Allow를 클릭합니다.
6. Proxyman을 열어 둔 채로 앱이나 스크립트에서 새 요청을 보내세요.

HTTPS를 검사하려면:

• Mac에 Proxyman 인증서를 설치하고 신뢰하세요.
• 검사하려는 앱이나 도메인에 대해 SSL Proxying을 활성화하세요.
• 새 요청을 보낸 다음, Proxyman에서 해당 요청을 선택해 내용을 확인하세요.

알아두어야 할 사항이 몇 가지 있습니다:

• 확장을 켜기 전에 이미 실행 중이던 앱은 다시 시작하세요. 그래야 새 연결을 열 수 있습니다.
• 이 확장을 통한 캡처를 중단하려면 Settings에서 Enable Network Extension을 끄세요.
• 이 기능은 Mac의 앱 트래픽을 캡처합니다. iPhone이나 Android 기기는 별도의 기기 설정 가이드를 따르세요.

설치 스크린샷 전체는 Network Extension 문서를 참고하세요.

5. 문제 해결: Node.js, Ruby, Python의 SSL 오류

문제

HTTPS 검사를 켠 뒤 스크립트에서 SSL 또는 인증서 오류가 보고됩니다.

• 이런 런타임은 자체 인증서 설정을 사용할 수 있습니다.
• macOS에서 Proxyman의 자체 서명 인증서를 신뢰하는 것만으로는 사용 중인 라이브러리에 충분하지 않을 수 있습니다.
• Network Extension은 트래픽을 Proxyman으로 라우팅하지만, 모든 런타임에서 인증서 신뢰를 자동으로 설정하지는 않습니다.

해결책: Automatic Setup 스크립트 사용 ✅

Proxyman의 Automatic Setup은 지원되는 라이브러리의 프록시와 인증서 설정을 준비합니다.

1. Proxyman → Setup → Automatic Setup을 엽니다.
2. Open New Terminal을 클릭합니다.
3. 필요하면 권한 요청을 승인합니다.
4. 새로 연 터미널에서 스크립트를 실행하거나 백엔드 서버를 다시 시작하세요.
5. 앱이나 도메인에 대해 SSL Proxying을 켜 둔 채로 요청을 다시 시도하세요.

참고:

• 이 설정은 Proxyman이 연 터미널 세션에만 적용됩니다.
• 다른 터미널에서 실행 중인 스크립트나 서버는 이 설정을 적용받지 않습니다. 중지한 뒤 새 터미널에서 실행하세요.
• Automatic Setup은 일반 셸 설정 파일을 변경하지 않습니다.
• Automatic Setup으로 트래픽을 캡처하는 경우, Network Extension을 끄고 설정된 터미널에서 계속 코드를 실행할 수 있습니다.

오류가 계속되면 Automatic Setup 문제 해결 가이드를 확인하세요.

관련 블로그

• Ruby 스크립트에서 HTTP/HTTPS 요청 캡처하기
• Node.js의 Axios에서 HTTP/HTTPS 요청 캡처하기
• Python Requests와 HTTPX에서 HTTPS 트래픽 캡처하기
• Proxyman v26.0.0에서 드디어 HTTP/2 지원