Corrigir Erros de Certificado SSL no curl, Git, Python e Node.js

O erro SSL certificate problem: unable to get local issuer certificate (ou suas variantes) é uma das dores de cabeça mais comuns no desenvolvimento. Significa que a ferramenta não consegue verificar a cadeia de certificados do servidor — geralmente porque os certificados raiz de CA no seu sistema estão desatualizados ou ausentes.

Este guia cobre correções adequadas — não apenas workarounds com -k / --insecure que desabilitam a segurança.

A causa raiz

Suas ferramentas verificam certificados SSL contra um bundle de CA — um arquivo contendo certificados raiz confiáveis. Quando esse bundle está desatualizado, ausente, ou o servidor tem uma cadeia incompleta, a verificação falha.

Sua ferramenta → "Este certificado é assinado por uma CA que eu confio?"
Bundle de CA → "Eu não tenho o certificado raiz dessa CA"
→ ERRO: unable to get local issuer certificate

curl

Erro

curl: (60) SSL certificate problem: unable to get local issuer certificate

Correção 1: Atualizar certificados CA (correção correta)

# Debian/Ubuntu
sudo apt update && sudo apt install ca-certificates
sudo update-ca-certificates

# CentOS/RHEL
sudo yum update ca-certificates

# macOS (Homebrew curl)
brew install ca-certificates

Correção 2: Especificar caminho do bundle CA

curl --cacert /etc/ssl/certs/ca-certificates.crt https://example.com

Correção 3: Definir variável de ambiente

export CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

Não faça isso (a menos que esteja testando)

curl -k https://example.com  # Desabilita TODA a verificação de certificados

Git

Erro

fatal: unable to access 'https://...': SSL certificate problem: unable to get local issuer certificate

Correção 1: Atualizar certificados CA (mesmo que curl)

sudo apt update && sudo apt install ca-certificates

Correção 2: Apontar o Git para o bundle CA correto

git config --global http.sslCAInfo /etc/ssl/certs/ca-certificates.crt

Correção 3: No Windows (Git for Windows)

O Git for Windows inclui seus próprios certificados CA. Atualize o Git para a versão mais recente, ou:

git config --global http.sslBackend schannel

Isso diz ao Git para usar o armazenamento de certificados integrado do Windows em vez do seu próprio bundle.

Não faça isso em produção

git config --global http.sslVerify false  # Desabilita TODA a verificação SSL para o Git

Python (requests / pip)

Erro (requests)

requests.exceptions.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED]

Erro (pip)

pip install ... Could not fetch URL https://...: connection error: [SSL: CERTIFICATE_VERIFY_FAILED]

Correção 1: Atualizar certifi (bundle CA do Python)

pip install --upgrade certifi

A biblioteca requests do Python usa o pacote certifi para certificados CA, não o armazenamento do sistema.

Correção 2: Apontar para o bundle CA do sistema

import requests
response = requests.get('https://example.com', verify='/etc/ssl/certs/ca-certificates.crt')

Ou variável de ambiente:

export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt

Correção 3: macOS Python (problema comum)

O Python no macOS frequentemente tem um armazenamento de certificados vazio após a instalação. Execute:

# Encontre sua instalação Python
python3 -c "import ssl; print(ssl.get_default_verify_paths())"

# Instale os certificados (macOS Python do python.org)
/Applications/Python\ 3.x/Install\ Certificates.command

Correção para pip especificamente

pip install --upgrade pip
pip config set global.cert /etc/ssl/certs/ca-certificates.crt

Node.js

Erro

Error: unable to get local issuer certificate
  code: 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY'

Correção 1: Definir NODE_EXTRA_CA_CERTS

export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt

Isso adiciona CAs extras sem substituir o bundle integrado do Node.

Correção 2: Para certificados autoassinados em desenvolvimento

// Apenas para desenvolvimento — adiciona uma CA específica
const https = require('https');
const fs = require('fs');

const agent = new https.Agent({
  ca: fs.readFileSync('/path/to/custom-ca.pem'),
});

fetch('https://internal-service.local', { agent });

Não faça isso em produção

export NODE_TLS_REJECT_UNAUTHORIZED=0  # Desabilita TODA a verificação SSL

Proxy corporativo / ambientes empresariais

Muitas redes corporativas usam um proxy de inspeção TLS que reassina o tráfego com uma CA interna. Suas ferramentas não confiam nesta CA interna.

Correção: Obtenha o certificado da CA corporativa com seu departamento de TI e adicione-o:

# Abrangente para o sistema (Debian/Ubuntu)
sudo cp corporate-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

# Python
export REQUESTS_CA_BUNDLE=/path/to/corporate-ca-bundle.pem

# Node.js
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

# Git
git config --global http.sslCAInfo /path/to/corporate-ca-bundle.pem

Containers Docker

Imagens Docker frequentemente possuem bundles CA desatualizados. Correção:

# Baseadas em Debian
RUN apt-get update && apt-get install -y ca-certificates && update-ca-certificates

# Alpine
RUN apk add --no-cache ca-certificates

Diagnóstico rápido

# Testar se a conexão SSL funciona com openssl
openssl s_client -connect example.com:443 -servername example.com < /dev/null 2>/dev/null | grep "Verify return code"
# "0 (ok)" = cadeia está correta, o bundle CA da sua ferramenta é o problema
# "21 (unable to verify)" = cadeia do servidor está incompleta

# Verificar qual bundle CA seu sistema usa
python3 -c "import certifi; print(certifi.where())"
curl-config --ca 2>/dev/null || echo "Check /etc/ssl/certs/"

Perguntas frequentes

Por que funciona no meu navegador mas não no curl/Python?

Navegadores mantêm sua própria loja de CA (atualizada com o navegador). Ferramentas de linha de comando usam o bundle CA do sistema ou seu próprio (Python usa certifi, Git for Windows inclui o seu). Se o bundle do sistema estiver desatualizado, ferramentas CLI falham enquanto navegadores funcionam normalmente.

É seguro desabilitar a verificação SSL?

Para testes rápidos: sim, se você entender que não está verificando a identidade do servidor. Para código de produção ou CI/CD: nunca. Desabilitar a verificação te expõe a ataques man-in-the-middle. Sempre corrija a causa raiz (atualize o bundle CA ou corrija a cadeia do servidor).

O certificado do servidor está correto mas eu ainda recebo erros

Verifique se sua ferramenta está passando por um proxy que reassina o tráfego. Redes corporativas, algumas VPNs e softwares antivírus fazem isso. A CA do proxy não está no armazenamento de confiança da sua ferramenta.