配置CLI工具和开发框架以与Cato TLS 检查配合工作

概况

本文展示如何使命令行工具和开发框架信任Cato Networks TLS检查证书，以便在检查流量时HTTPS能够正常工作而不报错。它涵盖了如何在系统范围内安装Cato证书以及当工具不使用操作系统可信存储时如何指向特定工具的证书。

在以下所有示例中，将/path/to/CatoNetworksTrustedRootCA.pem替换为您环境的实际路径。

系统范围安装证书（推荐）

在主机操作系统中安装Cato根证书可让大多数应用自动信任经过检查的流量。您可以按照如何安装Cato证书中描述的方法安装Cato根证书。

如果某些功能未如预期般运行，您可以手动将Cato根证书添加到操作系统信任存储。有关安装Cato证书的更多信息，请参阅相关文章：

组合证书包（用于覆盖信任包的工具）

某些工具会覆盖CA信任包而不是扩展它，这意味着它们实际上删除了之前存在的所有证书。为了确保这些工具同时信任公共网站和Cato检查流量，请创建包含操作系统受信任的根证书加上Cato根证书的组合包。

建议： 将Cato根证书安装在系统存储中。仅对需要单个CA文件的工具使用组合包。

维护提示： 定期重建组合包（例如，每月或操作系统信任更新之后）。

Windows (PowerShell)

# 在提升权限的PowerShell中运行
$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"

输出路径：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"

输出路径：/Library/Application Support/CatoNetworks/TLS/cato_combined_ca.pem

Linux

连接操作系统包和Cato CA以生成单个文件。

Debian/Ubuntu：

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

输出路径：/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'

输出路径：/etc/pki/tls/certs/cato_combined_ca.pem

工具特定的配置

有些工具会忽略操作系统的信任存储或在无法访问的环境中运行。在这些情况下，明确配置它们使用Cato CA或组合包。

通用变量设置语法

Linux/macOS：

export VARIABLE_NAME=/path/to/file

或长期解决方案：

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

Windows CMD

set VARIABLE_NAME=C:\path\to\file

或长期解决方案：

运行 setx VARIABLE_NAME "C:\path\to\file" 然后重新打开CMD窗口。

Windows PowerShell

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

为当前用户提供长期解决方案：
运行 setx VARIABLE_NAME "C:\path\to\file" 然后重新打开CMD窗口。
为设备上的所有用户提供长期解决方案：
运行 [System.Environment]::SetEnvironmentVariable("VARIABLE_NAME", "C:\path\to\file", "Machine")

Python（Requests、AWS CLI、Azure CLI、Gcloud CLI）

Python工具通常使用certifi，它自带其CA包（与操作系统信任存储分开）。

工具特定的Python修复

仅适用于macOS/Linux，您可以将Cato根证书添加到工具的certifi包中，或将其CA变量指向组合包。

Azure CLI（macOS/Linux）

将Cato根证书附加到CLI提供的certifi包中。要查找Cerifi的包位置，请运行以下命令：

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

AWS CLI / Boto（MacOS/Linux）

设置变量：

AWS_CA_BUNDLE=/path/to/cato_combined_ca.pem

或将此行添加到配置文件 (~/.aws/config)

ca_bundle = /path/to/cato_combined_ca.pem

Gcloud CLI

将Cato根证书附加到与SDK提供的certifi包中：

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

注意：路径可能会根据您如何安装工具而有所不同。如果在这些位置中未看到certifi/cacert.pem，请在工具目录中搜索。

OpenSSL（Curl、Composer、Ruby/Fastlane）

许多工具（如Curl、Composer和Ruby/Fastlane）依赖于OpenSSL进行TLS。默认情况下，OpenSSL在Linux上读取系统CA包，但在macOS（Homebrew OpenSSL）和Windows上，它使用自己的CA文件而不是操作系统信任存储。

工具特定的OpenSSL修复

如有需要，配置每个基于 OpenSSL 的工具指向组合包，或将 Cato 根证书附加到 OpenSSL 证书目录并运行 c_rehash。

Curl

对于macOS（SecureTransport）、Windows（Schannel）以及大多数Linux版本（OpenSSL/LibreSSL）中的内置curl，通常不需要额外配置。这些版本已经使用操作系统信任存储。

要确认curl正在使用的TLS库，运行：curl --version

对于不使用操作系统存储的 OpenSSL/LibreSSL 版本，请明确设置变量 CURL_CA_BUNDLE 指向组合包文件（使用上面说明的语法）。

Composer（PHP）

配置Composer使用组合包：composer config -g cafile /path/to/cato_combined_ca.pem

Ruby，Bundler，和Fastlane

配置Ruby/Fastlane信任组合包：bundle config --global ssl_ca_cert /path/to/cato_combined_ca.pem

Node.js和npm

Node.js和npm根据操作系统不同会处理证书存储有所不同。

Windows —— Node.js通常使用系统存储，因此安装Cato根证书到系统范围通常足够。
Linux/macOS - Node.js 通常使用其自己的 CA 包，不包含 Cato 根 CA。

Node.js

如果遇到 TLS 错误，请配置 Node.js 信任 Cato 根 CA：

设置 NODE_EXTRA_CA_CERTS 变量指向 Cato 根 CA 文件（而非组合包）：
export NODE_EXTRA_CA_CERTS=/path/to/CatoNetworksTrustedRootCA.pem

这个变量告诉 Node.js 除内置的 CA 外，还需信任额外的 CA。

npm

npm 需要使用组合包而非单个 CA 文件。按如下方式配置 npm：

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

这确保了 npm 信任 Cato 根 CA 和公用根 CA。

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

Java 使用名为 cacerts 的自有信任库文件。要启用 TLS 检查，将 Cato 根 CA 导入此库。

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

所有基于 Java 的工具（如 Maven、Gradle、JDBC 驱动程序、Salesforce Apex Data Loader）在将其添加到 cacerts 库后将信任 Cato CA。

Docker

Docker 由两部分组成：主机上的引擎/守护程序和所有镜像/容器。

Docker 引擎使用主机操作系统信任库，因此系统范围内安装 Cato 根 CA 即可。
对于镜像，您必须将 Cato 根 CA 导入容器。

Debian/Ubuntu-Based 镜像：

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

RHEL/CentOS-Based 镜像：

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

这确保了容器内的应用程序可以信任 Cato 检查的 TLS 流量。

Go

Go 自有 TLS 实现，但默认依赖于操作系统信任库。通常系统范围内安装 Cato 根 CA 即可。

在某些情况下（例如在 CI/CD 管道或容器中），您可能需要通过将变量 SSL_CERT_FILE 设置为指向组合包文件来自行覆盖信任配置。

Android Studio

Android Studio 使用其捆绑 JDK 内的 cacerts 信任库。要启用 TLS 检查，需将 Cato 根 CA 导入该库。默认密码是 changeit。