Mac の SWG 配下における Homebrew、Docker、Python、Node.js の CA 信頼設定

macOS で Homebrew、Docker Desktop、Node.js、Python、git、curl が SWG 署名の TLS 証明書を拒否する理由と、CA バンドル設定と SWG 回避の使い分けを解説します。

SWG bar · 更新日

HTTPS Break-and-Inspect を行う企業環境下の Mac では、開発者ランタイムごとに TLS 証明書の検証方法が異なります。Safari や Chrome が macOS キーチェーンを参照するのに対し、CLI ツールやコンテナーは独自の CA バンドルを使うことが多く、パッケージマネージャーや SDK 全体で突然ビルドエラーが発生する原因になります。

Mac の開発ツールが選択的に失敗する理由

ツール / ランタイム macOS 上のデフォルト信頼ストア 主な環境変数または設定
Node.js / npm / yarn / pnpm バイナリ組み込みの Mozilla CA バンドル NODE_EXTRA_CA_CERTS=/path/to/corp-ca.pem
Python / pip / uv / requests certifi バンドルまたは OpenSSL の CA パス SSL_CERT_FILE / REQUESTS_CA_BUNDLE
git ビルドに応じた OpenSSL または Secure Transport git config --global http.sslCAInfo /path/to/corp-ca.pem
curl / Homebrew(brew) macOS Secure Transport または OpenSSL CA バンドル HOMEBREW_CURLRC / CURL_CA_BUNDLE(curl --version で確認)
Docker Desktop / コンテナー Linux VM およびイメージ内の /etc/ssl/certs(macOS キーチェーンではない) 企業 CA を Docker VM / イメージの信頼ストアへ追加

1. どのレジストリや API ホスト名が傍受されているか特定する

シェルプロファイルやコンテナービルドを編集する前に、DNS やファイアウォールのブロックではなく、具体的にどの外部ホスト名が SSL 検査を受けているのかを確認します。

swgbar domains list --status confirmed
swgbar probe registry.npmjs.org
swgbar probe pypi.org
swgbar probe ghcr.io

パッケージマネージャーはダウンロードを複数のホストへリダイレクトすることがよくあります(例:formulae.brew.sh → ghcr.io、github.com → objects.githubusercontent.com)。詳しくは マルチドメインの Web アプリ、SSO、CDN、API 向けに SWG を回避するをご覧ください。

2. CA バンドル設定、TLS 検査除外、SWG 回避のどれを使うか判断する

  • 企業ルート CA の PEM を追加する:社内ポリシーによりすべての通信で SWG 復号が必須の場合は、SWG bar → 証明書で特定した正確なルート CA をエクスポートし、IT セキュリティ部門の案内に従って NODE_EXTRA_CA_CERTS、SSL_CERT_FILE、REQUESTS_CA_BUNDLE、または http.sslCAInfo を設定します。TLS 検証自体を無効化(NODE_TLS_REJECT_UNAUTHORIZED=0 や sslVerify=false)することは絶対に避けてください。
  • IT 部門に TLS 検査除外を申請する:共有レジストリ、Docker ベースイメージ、厳格な証明書ピンニングを行うツールなど、CI とローカル端末の両方でカスタム CA バンドルを維持するのが壊れやすいケースで推奨されます。
  • 許可されたネットワークでドメイン単位の SWG 回避を使う:Mac 上で特定のホストを回避する権限がある場合や自身がネットワークを管理している場合は、SWG bar で SWG を回避を有効にするか(または swgbar bypass enable <domain> を実行し)、CLI プロセスを再起動します。

システム既定値を変える前にワークフローを比較する

CERTIFICATE_VERIFY_FAILED エラーの段階的な対処方法は Mac の CLI・AI ツールにおける SWG TLS/SSL 証明書エラーを解決する方法をお読みください。ローカルのルーティングルールとゲートウェイのポリシー除外を比較する場合は、SWG 回避と TLS 検査の除外設定の違いをご参照ください。