Configuración de herramientas CLI y marcos de desarrollo para trabajar con Inspección TLS de Cato

Visión General

Este artículo muestra cómo hacer que las herramientas de línea de comandos y los marcos de desarrolladores confíen en el certificado de Inspección TLS de Cato Networks, para que HTTPS funcione sin errores mientras el tráfico es inspeccionado. Cubre cómo instalar el certificado de Cato a nivel del sistema y cómo apuntar herramientas específicas al certificado cuando no utilizan el almacén de confianza del sistema operativo.

En todos los ejemplos a continuación, reemplace /path/to/CatoNetworksTrustedRootCA.pem con la ruta real para su entorno.

Instalar el certificado a nivel del sistema (Recomendado)

Instalar el Cato Root CA en el sistema operativo del host permite que la mayoría de las aplicaciones confíen automáticamente en el tráfico inspeccionado. Puede instalar el Cato Root CA como se describe en How to Install the Cato Certificate.

Si algo no funciona como se esperaba, puede agregar manualmente el Cato Root CA al almacén de confianza del sistema operativo. Para más información sobre cómo instalar el certificado de Cato, consulte el artículo relevante:

Paquete certificado combinado (Para herramientas que sobrescriben el paquete de confianza)

Algunas herramientas sobrescriben el paquete de confianza CA en lugar de extenderlo, lo que significa que en realidad eliminan todos los certificados que había antes. Para garantizar que estas herramientas confíen tanto en los sitios web públicos como en el tráfico inspeccionado por Cato, cree un paquete combinado que incluya los certificados raíz de confianza del sistema operativo más el Cato Root CA.

Recomendación: Instale el Cato Root CA en el almacén del sistema. Use un paquete combinado solo para herramientas que requieran un único archivo CA.

Consejo de mantenimiento: Reconstruya el paquete combinado periódicamente (por ejemplo, mensualmente o después de actualizaciones de confianza del sistema operativo).

Windows (PowerShell)

# Ejecutar en 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 "Combined bundle written to: $dest"

Ruta de salida: 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"

Ruta de salida: /Library/Application Support/CatoNetworks/TLS/cato_combined_ca.pem

Linux

Concatene el paquete del sistema operativo con el Cato CA para producir un único archivo.

Debian/Ubuntu:

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

Ruta de salida: /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'

Ruta de salida: /etc/pki/tls/certs/cato_combined_ca.pem

Configuraciones específicas de herramientas

Algunas herramientas ignoran el almacén de confianza del sistema operativo o se ejecutan en entornos donde no está disponible. En estos casos, configúrelos explícitamente para usar el Cato CA o el paquete combinado.

Sintaxis general para establecer variables

Linux/macOS:

export VARIABLE_NAME=/path/to/file

o para una solución permanente:

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

Windows CMD

set VARIABLE_NAME=C:\path\to\file

o para una solución permanente:

Ejecutar setx VARIABLE_NAME "C:\path\to\file" y luego reabrir la ventana CMD.

Windows PowerShell

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

Para una solución permanente para el usuario actual:

Ejecutar setx VARIABLE_NAME "C:\path\to\file" y luego reabrir la ventana CMD.
Para una solución permanente para todos los usuarios en el dispositivo:

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

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

Las herramientas de Python a menudo usan certifi, que incluye su propio paquete CA (separado del almacén de confianza del sistema operativo).

Corrección general recomendada para Python

macOS o Linux: establezca la variable REQUESTS_CA_BUNDLE en el paquete combinado (instrucciones arriba Paquete certificado combinado (Para herramientas que sobrescriben el paquete de confianza)).
Windows: ejecutar pip install pip-system-certs para que Python use directamente el almacén de confianza de Windows.

Corrección específica de herramientas para Python

Solo para macOS/Linux, puede agregar el Cato Root CA al paquete certifi de la herramienta, o apuntar su variable CA al paquete combinado.

Azure CLI (macOS/Linux)

Agregue el Cato Root CA al paquete certifi incluido con la CLI. Para encontrar la ubicación del paquete de Certifi, ejecute el siguiente comando:

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

AWS CLI / Boto (MacOS/Linux)

Establecer la variable:

AWS_CA_BUNDLE=/path/to/cato_combined_ca.pem

O agregue esta línea al archivo de configuración (~/.aws/config)

ca_bundle = /path/to/cato_combined_ca.pem

Gcloud CLI

Agregue el Cato Root CA al paquete de certifi incluido con el SDK:

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

Nota: Las rutas pueden variar dependiendo de cómo instaló la herramienta. Si no ve certifi/cacert.pem en estas ubicaciones, busque dentro del directorio de la herramienta.

OpenSSL (Curl, Composer, Ruby/Fastlane)

Muchas herramientas (como Curl, Composer y Ruby/Fastlane) dependen de OpenSSL para TLS. Por defecto, OpenSSL lee el paquete de CA del sistema en Linux, pero en macOS (Homebrew OpenSSL) y Windows, usa sus propios archivos CA en lugar del almacén de confianza del sistema operativo.

Corrección general recomendada para OpenSSL

Establezca la variable SSL_CERT_FILE en el paquete combinado.

Corrección específica para OpenSSL

Si es necesario, configure cada herramienta basada en OpenSSL para que apunte al paquete combinado, o agregue el Cato Root CA en el directorio de certificados de OpenSSL y ejecute c_rehash.

Curl

Para curl incorporado en macOS (SecureTransport), Windows (Schannel) y la mayoría de las compilaciones de Linux (OpenSSL/LibreSSL), no se requiere configuración adicional. Estas compilaciones ya utilizan el almacén de confianza del sistema operativo.

Para confirmar qué biblioteca TLS está utilizando curl, ejecute: curl --version

Para compilaciones de OpenSSL/LibreSSL que no usan el almacén del sistema operativo, configure explícitamente la variable CURL_CA_BUNDLE para que apunte al archivo del paquete combinado (usando la sintaxis explicada arriba).

Composer (PHP)

Configure Composer para usar el paquete combinado: composer config -g cafile /ruta/a/cato_combined_ca.pem

Ruby, Bundler y Fastlane

Configure Ruby/Fastlane para confiar en el paquete combinado: bundle config --global ssl_ca_cert /ruta/a/cato_combined_ca.pem

Node.js y npm

Node.js y npm manejan los almacenes de certificados de forma diferente dependiendo del sistema operativo.

Windows - Node.js a menudo usa el almacén del sistema, por lo que instalar el Cato Root CA a nivel del sistema suele ser suficiente.
Linux/macOS - Node.js generalmente utiliza su propio paquete de CA, que no incluye el Cato Root CA.

Node.js

Si encuentras errores TLS, configura Node.js para confiar en el Cato Root CA:

Establece la variable NODE_EXTRA_CA_CERTS para apuntar al archivo Cato Root CA (no al paquete combinado):

export NODE_EXTRA_CA_CERTS=/path/to/CatoNetworksTrustedRootCA.pem

Esta variable indica a Node.js que confíe en la CA adicional además de las incorporadas.

npm

npm requiere el paquete combinado en lugar de un solo archivo CA. Configura npm de la siguiente manera:

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

Esto asegura que npm confíe tanto en el Cato Root CA como en las CAs públicas raíz.

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

Java utiliza su propio archivo de almacén de confianza llamado cacerts. Para habilitar la inspección TLS, importa el Cato Root CA a este almacén.

La contraseña predeterminada para cacerts es 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

Todas las herramientas basadas en Java (como Maven, Gradle, controladores JDBC, Salesforce Apex Data Loader) confiarán en el Cato CA una vez que se haya agregado al almacén cacerts.

Docker

Docker consta de dos partes: el engine/daemon en el host y las imágenes/contenedores.

El engine de Docker utiliza el almacén de confianza del SO del host, por lo que instalar el Cato Root CA a nivel del sistema es suficiente.
Para las imágenes, debes importar el Cato Root CA en el contenedor.

Imágenes basadas en Debian/Ubuntu:

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

Imágenes basadas en RHEL/CentOS:

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

Esto asegura que las aplicaciones dentro del contenedor puedan confiar en el tráfico TLS inspeccionado por Cato.

Go

Go tiene su propia implementación de TLS, pero por defecto, depende del almacén de confianza del SO. Instalar el Cato Root CA a nivel del sistema suele ser suficiente.

En algunos casos (por ejemplo, en pipelines CI/CD o contenedores), puede que necesites anular la configuración de confianza explícitamente estableciendo la variable SSL_CERT_FILE para que apunte al archivo de paquete combinado.

Android Studio

Android Studio utiliza su propio almacén de confianza cacerts dentro del JDK incluido. Para habilitar la inspección TLS, importa el Cato Root CA a ese almacén. La contraseña predeterminada es changeit.