Corrigir erros de certificado TLS e SSL de SWG em CLI e IA no Mac

Resolva erros CERTIFICATE_VERIFY_FAILED e unable to get local issuer certificate no git, npm, Python, Claude Code e Cursor atrás de uma SWG no macOS.

SWG bar · Atualizado

Quando um Mac corporativo está atrás de um Secure Web Gateway (SWG) que realiza inspeção HTTPS/SSL (break-and-inspect), o Safari e o Chrome costumam abrir sites sem nenhum alerta, enquanto ferramentas do Terminal e agentes de programação com IA falham com erros de handshake TLS como SSL: CERTIFICATE_VERIFY_FAILED, UNABLE_TO_GET_ISSUER_CERT_LOCALLY ou SSL certificate problem: unable to get local issuer certificate.

Essa diferença ocorre porque os navegadores consultam o Acesso às Chaves do macOS (Keychain) — onde o MDM pode instalar a CA raiz de inspeção da sua organização —, ao passo que muitos ambientes de linha de comando (git, curl, Node.js/npm, Python/pip) e ferramentas de IA (Claude Code, Cursor, servidores MCP) validam certificados usando seus próprios repositórios embutidos de CAs públicas.

1. Confirme qual nome de host está sofrendo inspeção HTTPS

Antes de alterar variáveis de ambiente ou configurações de rede, verifique se a cadeia de certificados do endpoint que está falhando realmente está sendo substituída no seu Mac:

  1. Instale e abra o SWG bar no macOS 14 ou posterior (Apple silicon).
  2. Execute o comando com falha uma vez e verifique SWG bar → Domínios — ou sonde o endpoint exato diretamente pelo Terminal usando a CLI incluída no aplicativo:
/Applications/SWGBar.app/Contents/MacOS/swgbar probe registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar domains detail registry.npmjs.org
  1. Examine a classificação e a CA raiz. Lembre-se de que interfaces web, servidores de autenticação, registros de pacotes e endpoints de API de LLMs frequentemente usam nomes de host distintos — um subdomínio pode passar sem alterações enquanto outro é descriptografado.

Se você utiliza um assistente compatível com MCP, também pode conectar o servidor MCP integrado do SWG bar para que seu cliente de IA consulte diretamente os domínios observados e as cadeias de certificados.

2. Escolha a solução adequada para o seu ambiente

Depois de confirmar que uma CA raiz de inspeção está assinando o certificado do nome de host de destino, escolha uma das três abordagens de acordo com a política da sua rede e a sua autorização:

Abordagem Como funciona Melhor quando
Configurar a confiança na CA para a ferramenta Aponte o runtime (por exemplo, NODE_EXTRA_CA_CERTS, SSL_CERT_FILE ou REQUESTS_CA_BUNDLE) para um arquivo PEM exportado que inclua a CA raiz corporativa. A política corporativa exige roteamento inspecionado pela SWG e você confia nessa CA para a ferramenta específica.
Solicitar uma exceção administrativa de inspeção TLS A equipe de TI exclui o nome de host da API ou do registro de pacotes da descriptografia HTTPS no gateway, mantendo o roteamento pelo gateway. Ferramentas com fixação de certificado (certificate pinning) ou endpoints de desenvolvimento usados pela equipe quebram sob break-and-inspect.
Ativar o contorno de SWG por domínio no SWG bar Direciona o nome de host selecionado no macOS sem a descriptografia HTTPS do gateway via barra de menus, CLI ou MCP. Você administra ou tem autorização para testar uma rota sem inspeção para domínios específicos no seu Mac.

Leia Bypass de SWG vs. exceção de inspeção TLS para uma comparação arquitetural detalhada entre exceções no gateway e mudanças de rota.

3. Contorne um domínio inspecionado no macOS quando autorizado

Se o contorno por domínio for adequado para a sua rede, você pode ativá-lo para o nome de host exato da API ou do registro pela barra de menus (SWG bar → Domínios → Contornar SWG → Ativar contorno para este domínio) ou pelo Terminal:

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

Depois que o status indicar Contorno ativo, reinicie o comando da CLI, o daemon em segundo plano ou o host de extensões da IDE para encerrar as conexões existentes e reconectar usando a nova regra. Consulte Como contornar uma SWG no Mac para ver a aprovação inicial da extensão de rede no macOS, o comportamento ao reiniciar e como desativar o contorno ao terminar.

Considere os limites da plataforma e da rede

  • Escopo por nome de host: Contornar example.com não inclui automaticamente api.example.com nem auth.example.com. Verifique cada nome de host acessado pela ferramenta.
  • Requisitos de rede: O SWG bar 2.4.12 requer macOS 14+ em Apple silicon e um caminho IPv4 disponível por uma interface de rede física. Se um firewall bloquear conexões diretas de saída ou se a ferramenta impuser seu próprio proxy explícito, desative a regra de contorno e utilize uma exceção TLS do administrador ou a configuração de pacote de CAs.
  • Verifique com evidências recentes: Execute uma nova verificação usando o guia de inspeção HTTPS e SSL após qualquer alteração, em vez de depender de resultados em cache.