Mac의 CLI 및 AI 도구에서 발생하는 SWG TLS/SSL 인증서 오류 해결

macOS의 SWG 환경에서 git, npm, Python, Claude Code, Cursor에 발생하는 CERTIFICATE_VERIFY_FAILED 및 로컬 발급자 인증서 오류를 진단하고 해결하세요.

SWG bar · 업데이트

회사 Mac이 **HTTPS/SSL 검사(Break-and-Inspect)**를 수행하는 보안 웹 게이트웨이(SWG) 뒤에 있으면 Safari와 Chrome에서는 경고 없이 웹사이트가 열리지만, 터미널 도구와 AI 코딩 에이전트에서는 SSL: CERTIFICATE_VERIFY_FAILED, UNABLE_TO_GET_ISSUER_CERT_LOCALLY, SSL certificate problem: unable to get local issuer certificate 같은 TLS 핸드셰이크 오류가 발생하는 경우가 많습니다.

이러한 불일치가 생기는 이유는 브라우저는 MDM이 조직의 검사 루트 CA를 설치해 둔 **macOS 키체인(Keychain)**을 참조하는 반면, 많은 명령줄 런타임(git, curl, Node.js/npm, Python/pip)과 AI 도구(Claude Code, Cursor, MCP 서버)는 자체적으로 번들링된 공개 CA 저장소를 기준으로 인증서를 검증하기 때문입니다.

1. 어떤 호스트 이름이 HTTPS 검사를 받고 있는지 확인하기

환경 변수나 네트워크 설정을 바꾸기 전에, 실패하는 엔드포인트의 인증서 체인이 Mac에서 실제로 교체되고 있는지 먼저 확인하세요.

  1. macOS 14 이상(Apple Silicon)에 SWG bar를 설치하고 엽니다.
  2. 실패하는 명령을 한 번 실행한 뒤 SWG bar → 도메인을 확인하거나, 내장된 CLI를 사용해 터미널에서 해당 엔드포인트를 직접 프로브합니다.
/Applications/SWGBar.app/Contents/MacOS/swgbar probe registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar domains detail registry.npmjs.org
  1. 분류 상태와 루트 CA를 확인합니다. 웹 프론트엔드, 인증 서버, 패키지 레지스트리, LLM API 엔드포인트는 서로 다른 호스트 이름을 사용하는 경우가 많아서, 한 하위 도메인은 그대로 통과하더라도 다른 하위 도메인은 복호화되고 있을 수 있습니다.

MCP 호환 어시스턴트를 사용 중이라면 SWG bar의 내장 MCP 서버를 연결해 AI 클라이언트가 관측된 도메인과 인증서 체인을 직접 조회하도록 할 수도 있습니다.

2. 환경에 맞는 해결 방법 선택하기

검사 루트 CA가 대상 호스트 이름의 인증서에 서명하고 있음을 확인했다면, 네트워크 정책과 권한에 따라 다음 세 가지 접근 방식 중 하나를 선택하세요.

접근 방식 작동 원리 적합한 상황
도구에 CA 신뢰 구성하기 런타임 환경 변수(예: NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, REQUESTS_CA_BUNDLE)가 사내 루트 CA를 포함한 내보낸 PEM 번들을 가리키도록 설정합니다. 사내 정책상 검사되는 SWG 라우팅이 필수이며 해당 도구에 대해 그 CA를 신뢰할 수 있을 때.
관리자 TLS 검사 예외 요청하기 IT 부서가 게이트웨이에서 해당 API 또는 레지스트리 호스트 이름을 HTTPS 복호화에서 제외하되 게이트웨이 라우팅은 유지합니다. 인증서 피닝이 적용된 도구나 팀 공용 개발 엔드포인트가 Break-and-Inspect 환경에서 작동하지 않을 때.
SWG bar에서 도메인별 SWG 우회 켜기 메뉴 막대, CLI 또는 MCP를 통해 macOS에서 선택한 호스트 이름을 게이트웨이 HTTPS 복호화 없이 라우팅합니다. 네트워크를 직접 관리하거나 Mac에서 특정 도메인에 대해 비검사 경로를 테스트하도록 승인받았을 때.

게이트웨이 예외와 경로 변경의 아키텍처 차이에 대한 자세한 비교는 SWG 우회와 TLS 검사 예외 비교를 읽어보세요.

3. 승인된 환경에서 macOS의 검사 대상 도메인 우회하기

도메인별 우회가 네트워크 정책에 부합한다면 메뉴 막대(SWG bar → 도메인 → SWG 우회 → 켜기) 또는 터미널에서 정확한 API나 레지스트리 호스트 이름에 대해 우회를 활성화할 수 있습니다.

/Applications/SWGBar.app/Contents/MacOS/swgbar bypass enable registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar bypass status

상태가 우회 중(CLI에서는 bypassing)으로 표시되면 기존 연결이 닫히고 새 규칙으로 다시 연결되도록 CLI 명령, 백그라운드 데몬 또는 IDE 확장 호스트를 다시 시작하세요. 최초 사용 시 macOS 네트워크 확장 허용, 재시작 후 동작, 작업 완료 후 우회를 끄는 방법은 Mac에서 SWG를 우회하는 방법을 참고하세요.

플랫폼 및 네트워크 경계 유의하기

  • 호스트 이름 단위의 적용 범위: example.com을 우회해도 api.example.com이나 auth.example.com이 자동으로 포함되지는 않습니다. 도구가 접속하는 각 호스트 이름을 개별적으로 확인하세요.
  • 네트워크 요구 사항: SWG bar 2.4.12는 Apple Silicon 기반 macOS 14 이상과 물리적 네트워크 인터페이스를 통한 사용 가능한 IPv4 경로가 필요합니다. 방화벽이 직접 아웃바운드 연결을 차단하거나 도구가 자체 명시적 프록시를 강제하는 경우 우회 규칙을 비활성화하고 관리자 TLS 예외 또는 CA 번들 구성을 대신 사용하세요.
  • 최신 근거로 검증하기: 설정을 변경한 뒤에는 캐시된 결과에 의존하지 말고 HTTPS 및 SSL 검사 가이드를 사용해 새로 확인하세요.