# Proxyman Proxy Helper Tool

> Proxyman Proxy Helper Tool을 설치하면 macOS 시스템 프록시를 더 빠르게 변경하고 복원할 수 있으며, 게스트 또는 관리자가 아닌 사용자도 트래픽을 캡처할 수 있습니다.

> **노트:** Proxyman은 프록시 설정을 무시하는 Mac 앱의 HTTP/HTTPS 트래픽을 캡처하는 [Network Extension](https://proxyman.com/docs/ko/advanced-features/network-extension)도 제공합니다. Proxy Helper Tool은 시스템 프록시를 관리하고, Network Extension은 앱별 프록시 설정 없이 지원되는 트래픽을 캡처합니다.
>
> Network Extension은 BETA이며 macOS 26 이상에서 Proxyman PRO가 필요합니다.

## Proxy Helper Tool이란 무엇인가요? {#what-is-the-proxy-helper-tool}

기본적으로 Proxyman은 [networksetup](https://www.unix.com/man-page/osx/8/networksetup/) 명령줄 도구로 HTTP/HTTPS 프록시 설정을 변경합니다. 하지만 **networksetup**은 속도가 느려서 앱의 시작이나 종료를 지연시킬 수 있습니다. 

Proxyman은 더 빠른 해결책으로 **Proxyman Proxy Helper Tool**을 제공합니다. 이는 **높은 성능**으로 네트워크 프록시 설정을 변경하는 macOS [Privileged Helper Tool](https://developer.apple.com/library/archive/documentation/Security/Conceptual/SecureCodingGuide/Articles/AccessControl.html#//apple\_ref/doc/uid/TP40002589-SW2)입니다.

> **노트:** Proxy Helper Tool을 사용할 때와 사용하지 않을 때 앱을 각각 실행해 보면 차이를 확인할 수 있습니다.

처음 실행하면 Proxyman이 Proxy Helper Tool 설치를 요청합니다. 설치를 건너뛰고 나중에 **Settings** → **Advanced**에서 설치할 수도 있습니다.

![Proxy Helper Tool 1.7.0이 설치되어 있고 Uninstall 버튼이 있는 Proxyman Settings의 Advanced 탭](https://proxyman.com/docs/assets/proxyman-settings-advanced-proxy-helper-tool.jpg)

_Settings의 Advanced에 있는 Proxy Helper Tool_

> **노트:** 설치한 후에는 Helper Tool을 `/Library/PrivilegedHelperTools/com.proxyman.NSProxy.HelperTool`에서 찾을 수 있습니다.
>
> Proxyman이 새 버전의 Proxy Helper Tool을 배포하면 다시 설치해야 합니다.

### macOS 13 Ventura 이상에서 권한 부여 {#grant-permission-on-macos-13-ventura-or-later}

macOS 13 Ventura 이상에서는 Helper Tool이 동작하려면 System Settings에서 먼저 허용해야 합니다.

권한을 부여하는 방법은 다음과 같습니다.

1. **System Settings** → **General** → **Login Items** 순서로 엽니다(macOS 15 이상에서는 **Login Items & Extensions**).
2. Proxyman을 찾아 스위치를 켜세요 ✅

권한이 없으면 Proxyman의 **Settings** → **Advanced**에 **Open Login Items…** 버튼이 표시되며, 이 버튼을 누르면 해당 설정 화면으로 이동합니다.

![Proxyman 스위치가 켜져 있는 macOS System Settings의 Login Items](https://proxyman.com/docs/assets/Screenshot%202022-11-20%20at%2021.10.43.png)

_Proxy Helper Tool에 권한 부여_

### 게스트 또는 관리자가 아닌 사용자 {#guest-or-non-admin-users}

게스트 또는 관리자가 아닌 사용자라면 Proxy Helper Tool을 설치하기 전까지 `networksetup` 명령이 실패하여 HTTP/HTTPS 프록시 설정을 변경할 수 없습니다. 

Proxy Helper Tool은 모든 유형의 사용자에 대해 프록시 설정을 변경할 수 있는 권한을 가지고 있습니다.

게스트 또는 관리자가 아닌 사용자라면 더 원활한 사용을 위해 Proxy Helper Tool 설치를 강력히 권장합니다.

### Proxy Helper Tool 제거 {#uninstall-the-proxy-helper-tool}

**Settings** → **Advanced** → **Uninstall**에서 Proxy Helper Tool을 제거하거나, `/Library/PrivilegedHelperTools/com.proxyman.NSProxy.HelperTool` 경로의 파일을 직접 삭제할 수 있습니다.

## 명령줄로 Proxy Helper Tool 설치 {#install-the-proxy-helper-tool-by-command-line}

macOS용 Proxyman 4.12.0 이상에서는 GUI 없이 Helper Tool을 설치할 수 있습니다. 다음 명령을 실행합니다.

```
sudo /Applications/Proxyman.app/Contents/MacOS/proxyman --install-privileged-components
```

## 변경 내역 {#changelog}

### 버전 1.6.0 (Proxyman 5.11.0 이상) {#version-160-proxyman-5110-or-later}

* 수정됨: 앱이 종료되면 Proxyman이 PAC URL을 복원하지 못하는 문제

### **버전 1.5.0** {#version-150}

* 보안 취약점을 수정했습니다. Proxyman v1.5.0 이하(2019년)가 Helper Tool(v1.4.0)에 연결해 사용자 동의 없이 시스템 프록시를 덮어쓸 수 있었습니다. 이번 수정으로 수신 연결을 검증하는 제약이 추가되었습니다. 호출하는 쪽은 Apple의 공증을 받았고, Proxyman LLC 인증서로 서명되었으며, Library Validation과 Force Hard 플래그가 켜져 있어야 합니다. (CVE-2023-45732)

📣 NCC Group의 **Scott Leitch**에게 감사드립니다.

### **버전 1.4.0** {#version-140}

* 새로운 macOS 13 Ventura 요구 사항을 준수하도록 Helper Tool 업데이트
* Login Items에 앱 아이콘과 앱 이름 표시

> **노트:** macOS Ventura 이상에서는 Proxyman이 포그라운드에서만 실행되는데도 helper tool, launch daemon, launch agent가 **Allow in the Background** 아래에 표시됩니다.
>
> 이 문제를 macOS에서 고쳐 달라고 Apple에 요청하는 [Twitter 논의](https://twitter.com/siracusa/status/1583914093437935616?s=46\&t=C1XB91IkDFkG697Ab8T9Dg)가 진행 중입니다.

1.4.0 버전을 설치한 후에도 macOS가 이전 정보를 캐시하고 있어 Login Items 항목이 업데이트되지 않을 수 있습니다. 

![Proxyman 대신 이전에 캐시된 이름과 빈 아이콘이 표시된 macOS Login Items 항목](https://proxyman.com/docs/assets/Screen%20Shot%202022-10-25%20at%2010.00.04.png)

_Login Items에 오래된 캐시 항목이 표시됨_

해결하는 방법은 다음과 같습니다.

1. Terminal 앱을 열고 `sfltool resetbtm`을 실행합니다.
2. Mac을 재시작합니다.
3. 완료입니다.

### **버전 1.3.0** {#version-130}

* 이전 프록시 설정을 기억해 두었다가 복원합니다.

### 버전 1.2.0 {#version-120}

* Proxyman이 비정상 종료되면 HTTP 프록시 설정을 안전하게 되돌립니다.

## 문제 해결 {#troubleshooting}

Helper Tool을 설치할 때 다음 오류가 표시되면:

The operation couldn’t be completed. (CFErrorDomainLaunchd error 9.)

다음 문서의 단계를 따르세요: [CFErrorDomainLaunchd error 9 해결 방법 (Tencent Cloud)](https://cloud.tencent.com/developer/article/1816504)

관련 GitHub 이슈: [ProxymanApp/Proxyman#1113](https://github.com/ProxymanApp/Proxyman/issues/1113)