Настройка CLI инструментов и фреймворков разработки для работы с инспекцией TLS от Cato

Обзор

Эта статья объясняет, как заставить командные инструменты и фреймворки разработчиков доверять сертификату инспекции TLS от Cato Networks, чтобы HTTPS работал без ошибок во время инспекции трафика. Описывается, как установить сертификат Cato на уровне всей системы и как указать конкретным инструментам на сертификат, когда они не используют хранилище доверия ОС.

Во всех примерах ниже замените /path/to/CatoNetworksTrustedRootCA.pem на актуальный путь для вашей среды.

Установите сертификат на уровне всей системы (рекомендуется)

Установка корневого сертификата Cato в ОС хоста позволяет большинству приложений автоматически доверять инспектированному трафику. Вы можете установить корневой сертификат Cato, как описано в How to Install the Cato Certificate.

Если что-то не работает так, как ожидалось, вы можете вручную добавить корневой сертификат 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 "Объединенный пакет записан в: $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

Конкатенировать пакет ОС с CA Cato, чтобы создать один файл.

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

Специфические конфигурации инструментов

Некоторые инструменты игнорируют хранилище доверия ОС или работают в средах, где оно недоступно. В этих случаях явно настройте их на использование CA Cato или объединенного пакета.

Общий синтаксис установки переменных

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 в пакет certifi, который поставляется с CLI. Чтобы найти место хранения пакета Certifi, выполните следующую команду:

$(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 в пакет certifi, который поставляется с SDK:

~/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 считывает системный пакет CA на Linux, но на macOS (Homebrew OpenSSL) и Windows, он использует собственные файлы CA вместо хранилища доверия ОС.

Специфическое исправление для OpenSSL

При необходимости настройте каждый инструмент, основанный на OpenSSL, чтобы указать на объединенный пакет, или добавьте корневой сертификат Cato в директорию сертификатов OpenSSL и выполните c_rehash.

Curl

Для встроенного curl на macOS (SecureTransport), Windows (Schannel) и большинстве сборок Linux (OpenSSL/LibreSSL) дополнительных настроек не требуется. Эти сборки уже используют хранилище доверия ОС.

Чтобы подтвердить, какую библиотеку TLS использует curl, выполните: 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.

Node.js

Если вы сталкиваетесь с ошибками TLS, настройте Node.js для доверия корневому сертификату Cato:

Установите переменную NODE_EXTRA_CA_CERTS для указания на файл корневого сертификата Cato (а не на объединенный пакет):

export NODE_EXTRA_CA_CERTS=/path/to/CatoNetworksTrustedRootCA.pem

Эта переменная сообщает Node.js доверять дополнительному CA поверх встроенных.

npm

npm требует объединенного пакета вместо одного файла CA. Настройте npm следующим образом:

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

Это обеспечивает доверие npm как корневому сертификату Cato, так и публичным корневым CA.

Java (Maven, Gradle, JDBC и т. д.)

Java использует собственный файл хранилища доверия, называемый cacerts. Чтобы включить инспекцию TLS, импортируйте корневой сертификат Cato в это хранилище.

Пароль по умолчанию для 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) будут доверять Cato CA после его добавления в хранилище cacerts.

Docker

Docker состоит из двух частей: движка/демона на хосте и любых образов/контейнеров.

Движок Docker использует хранилище доверия ОС хоста, поэтому установка корневого сертификата Cato на уровне системы достаточно.
Для образов необходимо импортировать корневой сертификат Cato в контейнер.

Изображения на основе Debian/Ubuntu:

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

Изображения на основе RHEL/CentOS:

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

Это обеспечивает доверие приложений внутри контейнера к трафику TLS, проверенному Cato.

Go

Go имеет собственную реализацию TLS, но по умолчанию полагается на хранилище доверия ОС. Установка Cato Root CA на уровне системы обычно достаточна.

В некоторых случаях (например, в конвейерах CI/CD или контейнерах) может потребоваться явно переопределить конфигурацию доверия, установив переменную SSL_CERT_FILE на путь к объединенному файлу пакета.

Android Studio

Android Studio использует собственное хранилище доверенных сертификатов cacerts внутри связанного JDK. Чтобы включить инспекцию TLS, импортируйте Cato Root CA в это хранилище. Пароль по умолчанию - changeit.