Configurando Ferramentas CLI e Frameworks de Desenvolvimento para funcionar com a inspeção TLS da Cato

Visão Geral

Este artigo mostra como fazer com que ferramentas de linha de comando e frameworks de desenvolvedor confiem no certificado de inspeção TLS da Cato Networks, para que o HTTPS funcione sem erros enquanto o tráfego é inspecionado. Ele aborda como instalar o certificado Cato para todo o sistema e como apontar ferramentas específicas para o certificado quando não utilizam o repositório de confiança do SO.

Em todos os exemplos abaixo, substitua /path/to/CatoNetworksTrustedRootCA.pem pelo caminho real para o seu ambiente.

Instalar o Certificado para Todo o Sistema (Recomendado)

Instalar o Cato Root CA no sistema operacional do host permite que a maioria dos aplicativos confiem automaticamente no tráfego inspecionado. Você pode instalar o Cato Root CA conforme descrito em Como Instalar o Certificado Cato.

Se algo não funcionar como esperado, você pode adicionar manualmente o Cato Root CA ao repositório de confiança do SO. Para mais informações sobre a instalação do certificado Cato, veja o artigo relevante:

Pacote de Certificado Combinado (Para Ferramentas que Sobrescrevem o Pacote de Confiança)

Algumas ferramentas sobrescrevem o pacote de confiança CA em vez de estendê-lo, o que significa que elas realmente apagam todos os certificados que estavam lá antes. Para garantir que essas ferramentas confiem em ambos sites públicos e tráfego inspecionado pela Cato, crie um pacote combinado que inclua os certificados raiz confiáveis do SO, além do Cato Root CA.

Recomendação: Instale o Cato Root CA no repositório do sistema. Use um pacote combinado apenas para ferramentas que exigem um único arquivo CA.

Dica de Manutenção: Reconstrua o pacote combinado periodicamente (por exemplo, mensalmente ou após atualizações de confiança do SO).

Windows (PowerShell)

# Execute no PowerShell elevado
$dest="$env:ProgramData\CatoNetworks\TLS\cato_combined_ca.pem"; $destDir=Split-Path $dest; New-Item -ItemType Directory -Force -Path $destDir | Out-Null; Get-ChildItem Cert:\CurrentUser\Root, Cert:\LocalMachine\Root, Cert:\CurrentUser\CA, Cert:\LocalMachine\CA | Sort-Object Thumbprint -Unique | ForEach-Object { "-----BEGIN CERTIFICATE-----"; [System.Convert]::ToBase64String($_.RawData,'InsertLineBreaks'); "-----END CERTIFICATE-----"; "" } | Out-File -Encoding ascii $dest; Write-Host "Pacote combinado escrito para: $dest"

Caminho de saída: C:\ProgramData\CatoNetworks\TLS\cato_combined_ca.pem

macOS

sudo mkdir -p "/Library/Application Support/CatoNetworks/TLS"

security find-certificate -a -p \
  /System/Library/Keychains/SystemRootCertificates.keychain \
  /Library/Keychains/System.keychain \
  > /tmp/cato_combined_ca.pem && \
  sudo install -m 0644 /tmp/cato_combined_ca.pem \
  "/Library/Application Support/CatoNetworks/TLS/cato_combined_ca.pem"

Caminho de saída: /Library/Application Support/CatoNetworks/TLS/cato_combined_ca.pem

Linux

Concatene o pacote do SO com o Cato CA para produzir um único arquivo.

Debian/Ubuntu:

sudo bash -c 'cat /etc/ssl/certs/ca-certificates.crt > /etc/ssl/certs/cato_combined_ca.pem'

Caminho de saída: /etc/ssl/certs/cato_combined_ca.pem

RHEL/CentOS/Alma/Rocky:

sudo bash -c 'cat /etc/pki/tls/certs/ca-bundle.crt > /etc/pki/tls/certs/cato_combined_ca.pem'

Caminho de saída: /etc/pki/tls/certs/cato_combined_ca.pem

Configurações Específicas de Ferramentas

Algumas ferramentas ignoram o repositório de confiança do SO ou são executadas em ambientes onde ele não está disponível. Nesses casos, configure explicitamente para usar o Cato CA ou o pacote combinado.

Sintaxe Geral de Configuração de Variáveis

Linux/macOS:

export VARIABLE_NAME=/path/to/file

ou para uma solução permanente:

echo 'export VARIABLE_NAME=/path/to/file' >> ~/.zshrc ou ~/.bashrc 
source ~/.zshrc  ou  ~/.bashrc

Windows CMD

set VARIABLE_NAME=C:\path\to\file

ou para uma solução permanente:

Execute setx VARIABLE_NAME "C:\path\to\file" e depois reabra a janela CMD.

Windows PowerShell

$env:VARIABLE_NAME="C:\path\to\file"

Para uma solução permanente para o usuário atual:

Execute setx VARIABLE_NAME "C:\path\to\file" e depois reabra a janela CMD.
Para uma solução permanente para todos os usuários no dispositivo:

Execute [System.Environment]::SetEnvironmentVariable("VARIABLE_NAME", "C:\path\to\file", "Machine")

Python (Requests, AWS CLI, Azure CLI, Gcloud CLI)

Ferramentas Python costumam usar certifi, que inclui seu próprio pacote CA (separado do repositório de confiança do SO).

Correção Geral Recomendada para Python

macOS ou Linux – defina a variável REQUESTS_CA_BUNDLE para o pacote combinado (instruções acima Pacote de Certificado Combinado (Para Ferramentas que Sobrescrevem o Pacote de Confiança)).
Windows – execute pip install pip-system-certs para fazer o Python usar diretamente o repositório de confiança do Windows.

Correção Python Específica de Ferramenta

Somente para macOS/Linux, você pode adicionar o Cato Root CA ao pacote certifi da ferramenta ou apontar sua variável CA para o pacote combinado.

Azure CLI (macOS/Linux)

Adicione o Cato Root CA ao pacote certifi enviado com o CLI. Para encontrar a localização do pacote do Cerifi, execute o seguinte comando:

$(az --version 2>&1 | awk -F"'" '/Python location/ {print $2}') -m certifi

AWS CLI / Boto (MacOS/Linux)

Defina a variável:

AWS_CA_BUNDLE=/path/to/cato_combined_ca.pem

Ou adicione esta linha ao arquivo de configuração (~/.aws/config)

ca_bundle = /path/to/cato_combined_ca.pem

Gcloud CLI

Adicione o Cato Root CA ao pacote certifi enviado com o SDK:

~/google-cloud-sdk/platform/bundledpython*/lib/python*/site-packages/certifi/cacert.pem

Nota: Os caminhos podem variar dependendo da forma como você instalou a ferramenta. Se não encontrar certifi/cacert.pem nesses locais, pesquise dentro do diretório da ferramenta.

OpenSSL (Curl, Composer, Ruby/Fastlane)

Muitas ferramentas (como Curl, Composer e Ruby/Fastlane) dependem do OpenSSL para TLS. Por padrão, o OpenSSL lê o pacote CA do sistema no Linux, mas no macOS (Homebrew OpenSSL) e Windows, usa seus próprios arquivos CA em vez do repositório de confiança do SO.

Correção Geral Recomendada para OpenSSL

Defina a SSL_CERT_FILE variável para o pacote combinado.

Correção Específica de Ferramenta para OpenSSL

Se necessário, configure cada ferramenta baseada em OpenSSL para apontar para o pacote combinado ou adicione o Cato Root CA ao diretório de certificados do OpenSSL e execute c_rehash.

Curl

Para o curl embutido no macOS (SecureTransport), Windows (Schannel) e na maioria das compilações Linux (OpenSSL/LibreSSL), não é necessária configuração adicional. Essas compilações já utilizam o repositório de confiança do SO.

Para confirmar qual biblioteca TLS o curl está utilizando, execute: curl --version

Para compilações OpenSSL/LibreSSL que não utilizam o repositório do SO, defina explicitamente a variável CURL_CA_BUNDLE para apontar para o arquivo do pacote combinado (usando a sintaxe explicada acima).

Composer (PHP)

Configure o Composer para usar o pacote combinado: composer config -g cafile /path/to/cato_combined_ca.pem

Ruby, Bundler e Fastlane

Configure Ruby/Fastlane para confiar no pacote combinado: bundle config --global ssl_ca_cert /path/to/cato_combined_ca.pem

Node.js e npm

Node.js e npm lidam com repositórios de certificados de maneira diferente dependendo do SO.

Windows - Node.js frequentemente usa o repositório do sistema, então instalar o Cato Root CA para todo o sistema geralmente é suficiente.
Linux/macOS - Node.js geralmente usa seu próprio pacote de CAs, que não inclui o Cato Root CA.

Node.js

Se você encontrar erros TLS, configure o Node.js para confiar no Cato Root CA:

Defina a variável NODE_EXTRA_CA_CERTS para apontar para o arquivo Cato Root CA (não o pacote combinado):

export NODE_EXTRA_CA_CERTS=/path/to/CatoNetworksTrustedRootCA.pem

Esta variável informa ao Node.js para confiar na CA adicional além das internas.

npm

npm requer o pacote combinado em vez de um único arquivo CA. Configurar o npm da seguinte forma:

npm config set cafile "/path/to/cato_combined_ca.pem"

Isso garante que o npm confie tanto no Cato Root CA quanto nas CAs raiz públicas.

Java (Maven, Gradle, JDBC, etc...)

Java usa seu próprio arquivo de armazenamento de confiança chamado cacerts. Para habilitar a inspeção TLS, importe o Cato Root CA para esse armazenamento.

A senha padrão para cacerts é changeit.

Linux/macOS

sudo keytool -importcert -noprompt \
  -alias cato-root-ca \
  -file /path/to/CatoNetworksTrustedRootCA.pem \
  -keystore $JAVA_HOME/lib/security/cacerts \
  -storepass changeit

Windows (PowerShell)

keytool -importcert -noprompt `
  -alias cato-root-ca `
  -file "C:\path\to\CatoNetworksTrustedRootCA.pem" `
  -keystore "C:\Program Files\Java\jdk-17\lib\security\cacerts" `
  -storepass changeit

Todos os ferramentas baseadas em Java (como Maven, Gradle, drivers JDBC, Salesforce Apex Data Loader) confiarão no Cato CA uma vez que seja adicionado ao armazenamento cacerts.

Docker

O Docker consiste em duas partes: o motor/daemon no host e qualquer imagem/container.

O motor Docker usa o armazenamento de confiança do sistema operacional host, então instalar o Cato Root CA em todo o sistema é suficiente.
Para imagens, você deve importar o Cato Root CA para o container.

Imagens Baseadas em Debian/Ubuntu:

COPY CatoNetworksTrustedRootCA.pem /usr/local/share/ca-certificates/cato-root-ca.crt
RUN update-ca-certificates

Imagens Baseadas em RHEL/CentOS:

COPY CatoNetworksTrustedRootCA.pem /etc/pki/ca-trust/source/anchors/
RUN update-ca-trust

Isso garante que os aplicativos dentro do contêiner possam confiar no tráfego TLS inspecionado pelo Cato.

Go

Go tem sua própria implementação de TLS, mas por padrão, depende do armazenamento de confiança do sistema operacional. Instalar o Cato Root CA em todo o sistema geralmente é suficiente.

Em alguns casos (por exemplo, em pipelines CI/CD ou containers), pode ser necessário substituir a configuração de confiança explicitamente definindo a variável SSL_CERT_FILE para apontar para o arquivo de pacote combinado.

Android Studio

O Android Studio usa seu próprio armazenamento de confiança cacerts dentro do JDK embalado. Para habilitar a inspeção TLS, importe o Cato Root CA para esse armazenamento. A senha padrão é changeit.