Risolvere gli errori dei certificati TLS e SSL di SWG negli strumenti CLI e IA su Mac
Risolvi gli errori CERTIFICATE_VERIFY_FAILED e di certificato dell’emittente locale in git, npm, Python, Claude Code e Cursor dietro un SWG su macOS.
SWG bar · Aggiornato
Quando un Mac aziendale si trova dietro un Secure Web Gateway (SWG) che esegue ispezione HTTPS/SSL (break-and-inspect), Safari e Chrome spesso caricano i siti web senza avvisi mentre gli strumenti da Terminale e gli agenti di programmazione IA si bloccano con errori di handshake TLS come SSL: CERTIFICATE_VERIFY_FAILED, UNABLE_TO_GET_ISSUER_CERT_LOCALLY o SSL certificate problem: unable to get local issuer certificate.
Questa discrepanza si verifica perché i browser consultano il Portachiavi di macOS — dove l’MDM può installare la CA radice di ispezione dell’organizzazione — mentre molti ambienti a riga di comando (git, curl, Node.js/npm, Python/pip) e strumenti IA (Claude Code, Cursor, server MCP) convalidano i certificati rispetto ai propri archivi di CA pubbliche integrati.
1. Conferma quale nome host è sottoposto a ispezione HTTPS
Prima di modificare variabili d’ambiente o impostazioni di rete, verifica se la catena di certificati dell’endpoint che restituisce errore viene effettivamente sostituita sul tuo Mac:
- Installa e apri SWG bar su macOS 14 o successivo (chip Apple).
- Esegui una volta il comando che fallisce, poi controlla SWG bar → Domini — oppure verifica direttamente l’endpoint esatto da Terminale con la CLI integrata:
/Applications/SWGBar.app/Contents/MacOS/swgbar probe registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar domains detail registry.npmjs.org
- Esamina la classificazione e la CA radice. Ricorda che interfacce web, server di autenticazione, registri di pacchetti ed endpoint API degli LLM utilizzano spesso nomi host diversi: un sottodominio può passare inalterato mentre un altro viene decifrato.
Se utilizzi un assistente compatibile con MCP, puoi anche collegare il server MCP integrato di SWG bar affinché il tuo client IA interroghi direttamente i domini e le catene di certificati osservati.
2. Scegli la soluzione adatta al tuo ambiente
Dopo aver confermato che una CA radice di ispezione firma il certificato del nome host di destinazione, scegli uno dei tre approcci seguenti in base ai criteri di rete e alle tue autorizzazioni:
| Approccio | Come funziona | Ideale quando |
|---|---|---|
| Configurare l’attendibilità CA per lo strumento | Indirizza il runtime (ad esempio tramite NODE_EXTRA_CA_CERTS, SSL_CERT_FILE o REQUESTS_CA_BUNDLE) a un bundle PEM esportato che includa la CA radice aziendale. |
I criteri aziendali impongono l’instradamento ispezionato tramite SWG e consideri attendibile quella CA per lo specifico strumento. |
| Richiedere un’eccezione all’ispezione TLS all’amministratore | L’IT esclude il nome host dell’API o del registro dalla decifratura HTTPS sul gateway mantenendo l’instradamento tramite gateway. | Strumenti con certificate pinning o endpoint di sviluppo condivisi dal team si bloccano con il break-and-inspect. |
| Attivare il bypass SWG per dominio in SWG bar | Instrada il nome host selezionato su macOS senza decifratura HTTPS del gateway tramite barra dei menu, CLI o MCP. | Amministri la rete o sei autorizzato a testare un percorso non ispezionato per specifici domini sul tuo Mac. |
Leggi Bypass SWG vs eccezione all’ispezione TLS per un confronto architetturale dettagliato tra eccezioni sul gateway e modifiche del percorso di rete.
3. Aggira un dominio ispezionato su macOS quando autorizzato
Se il bypass per dominio è appropriato per la tua rete, puoi attivarlo per il nome host esatto dell’API o del registro dalla barra dei menu (SWG bar → Domini → Aggira SWG → Attiva il bypass per questo dominio) oppure da Terminale:
/Applications/SWGBar.app/Contents/MacOS/swgbar bypass enable registry.npmjs.org
/Applications/SWGBar.app/Contents/MacOS/swgbar bypass status
Una volta che lo stato mostra Bypass attivo, riavvia il comando CLI, il demone in background o l’host delle estensioni dell’IDE affinché le connessioni esistenti si chiudano e si riconnettano seguendo la nuova regola. Segui Come aggirare una SWG su Mac per l’autorizzazione iniziale dell’estensione di rete di macOS, il comportamento al riavvio e la disattivazione del bypass al termine.
Tieni presenti i limiti della piattaforma e della rete
- Ambito per singolo nome host: Aggirare
example.comnon include automaticamenteapi.example.comoauth.example.com. Verifica ogni nome host contattato dal tuo strumento. - Requisiti di rete: SWG bar 2.4.12 richiede macOS 14+ su chip Apple e un percorso IPv4 disponibile tramite un’interfaccia di rete fisica. Se un firewall blocca le connessioni dirette in uscita o lo strumento impone un proprio proxy esplicito, disattiva la regola di bypass e usa invece un’eccezione TLS dell’amministratore o la configurazione di un bundle CA.
- Verifica con nuove evidenze: Esegui un nuovo controllo seguendo la guida all’ispezione HTTPS e SSL dopo ogni modifica anziché affidarti a risultati memorizzati nella cache.