Сеть: прокси и TLS¶
Корпоративная сеть обычно закрывает прямой выход в интернет и подписывает внутренние сервисы собственным CA. Synth умеет работать в обоих условиях: исходящий трафик можно направить через прокси, а доверие к сертификатам задать в одном месте — для всех подсистем сразу.
Зачем нужен egress-прокси¶
Через общий исходящий слой идут:
- запросы к провайдерам LLM;
- HTTP- и SSE-подключения к MCP-серверам;
- исходящие webhooks;
web_fetchиweb_search;- git-операции;
- проверка обновлений и загрузка внешних инструкций и скиллов.
Поддерживаются HTTP, HTTPS и SOCKS5. HTTPS-прокси может требовать собственный CA, Basic-аутентификацию или клиентский сертификат — эти параметры задаются у профиля отдельно от доверия к цели.
PostgreSQL
База — не HTTP-трафик, поэтому прокси к ней не применяется. Для PostgreSQL
настраивается TLS: режим storage.postgres.sslmode и сертификаты из
security.tls.
Профили и правила¶
Маршрут выбирается для каждого хоста назначения:
noProxy— исключения, всегда важнее правил;- правила
rules[]— в порядке объявления, побеждает первое совпадение; - режим:
all— профиль по умолчанию,selected— напрямую.
| Поле | Назначение |
|---|---|
enabled |
Явный выключатель; без него прокси включается наличием URL |
mode |
all — проксировать всё, кроме исключений; selected — только по правилам |
defaultProfile |
Профиль для режима all и правил без явного профиля |
profiles.<name> |
Именованный профиль: URL, Basic-аутентификация, TLS к прокси |
rules[] |
{hosts, action: proxy|direct, profile?}; порядок = приоритет |
noProxy |
Хосты и сети, которые всегда идут напрямую |
Правило с action: direct не может ссылаться на профиль. В режиме selected
всё, что не совпало с правилом, идёт напрямую. Шаблоны хостов: точное имя,
.suffix (сам домен и поддомены), *.suffix (только поддомены), host:port,
IP-литерал, CIDR и *.
Настройка¶
Прокси задаётся в config.yaml, переменными SYNTH_PROXY_* или в интерфейсе:
Настройки → «Сеть» → «Прокси». Приоритет источников:
Стандартные переменные HTTP_PROXY/HTTPS_PROXY/ALL_PROXY/NO_PROXY
учитываются только при fromEnv: true и если явный enabled: false их не
подавляет. Слияние — по полям, но profiles и rules runtime-настройка
заменяет целиком: частичного объединения списков нет.
proxy:
enabled: true
mode: all
defaultProfile: default
profiles:
default:
label: Corporate
url: "http://proxy.corp.example:3128"
auth:
type: basic
username: synth
tls:
caFile: "/etc/synth/tls/proxy-ca.pem"
rejectUnauthorized: true
llm:
label: LLM egress
url: "https://llm-proxy.corp.example:8443"
rules:
- hosts: ["api.openai.com", "*.openai.com"]
action: proxy
profile: llm
- hosts: ["*.corp.example", "10.0.0.0/8"]
action: direct
noProxy: ["localhost", ".svc"]
Применение — при следующем старте, как и TLS: транспорт создаётся один раз
при инициализации процесса. Интерфейс показывает статус saved/running и
плашку restartRequired; изменения вступают в силу после перезапуска инстанса.
Пароли¶
Пароль Basic-аутентификации не хранится ни в config.yaml, ни в
settings.json. Источники:
- профиль
default— переменнаяSYNTH_PROXY_PASSWORDили файл{dataDir}/secrets/proxy-password; - остальные профили —
SYNTH_PROXY_<NAME>_PASSWORDили файл{dataDir}/secrets/proxy/<name>.password.
Переменная окружения приоритетнее файла. Если пароль задан через окружение,
интерфейс не может его изменить и отвечает 409 CONFLICT. Пароль write-only:
он не возвращается в ответах, не пишется в аудит и не попадает в журналы.
CA и клиентские сертификаты профиля, загруженные из интерфейса, лежат в
{dataDir}/secrets/proxy/<name>/.
Ограничения¶
- Доменная аутентификация не реализуется. Kerberos, NTLM и Negotiate в
приложении не поддерживаются: между Synth и корпоративным прокси ставится
промежуточный egress-прокси или шлюз (например, Squid с
login=NEGOTIATEилиpxдля NTLM). Synth подключается к шлюзу по Basic, mTLS или без аутентификации. - SOCKS5 — best-effort. Имя хоста резолвит прокси; доверие к цели и mTLS через SOCKS5 не применяются. Для Kubernetes целевая схема — HTTP CONNECT.
- Git и stdio-MCP получают один прокси через окружение дочернего процесса.
Per-host маршрут для них не поддерживается; в режиме
selectedпрокси- переменные им не ставятся, чтобы не обойти правила молча. - Только Basic.
auth.type, отличный отbasic, — ошибка конфигурации. - Недоступный прокси не означает тихий direct. Прямой обход возможен только
при явном
fallbackDirect: true; ошибки аутентификации его не разрешают.
TLS и доверенные CA¶
security.tls — единый источник доверия для всех исходящих соединений: LLM,
MCP, webhooks, web_fetch, git и PostgreSQL. Подсистемы не создают собственных
HTTP-агентов и не полагаются на переменные окружения как на конфигурацию.
| Поле | Назначение |
|---|---|
caFile |
Путь к PEM-файлу CA; допускается бандл из нескольких сертификатов |
caPem |
PEM CA строкой, например из Secret; взаимоисключающ с caFile |
certFile / keyFile |
Клиентский сертификат и ключ для mTLS по умолчанию |
rejectUnauthorized |
Проверять сертификат сервера; по умолчанию true |
Пользовательский CA дополняет системное доверие, а не заменяет его:
публичные сайты продолжают проверяться. Для отдельных хостов можно задать свои
клиентские сертификаты — таблица mappings:
- точное имя хоста;
*.suffix— только поддомены;*— все хосты.
Побеждает первое совпадение сверху вниз; если совпадений нет, используется клиентский сертификат по умолчанию. Отдельного CA на хост нет: один CA-бандл на весь исходящий трафик.
security:
tls:
caFile: "/etc/synth/tls/corp-ca.pem"
# certFile: "/etc/synth/tls/client.crt"
# keyFile: "/etc/synth/tls/client.key"
rejectUnauthorized: true
TLS настраивается в config.yaml, переменными SYNTH_TLS_* или в интерфейсе:
Настройки → «Сеть» → «Доверенные CA (TLS)». Runtime-настройка хранится в
{dataDir}/security-tls.json с правами 0600, а PEM-материалы — в
{dataDir}/secrets/tls/. Файл читается до подключения к PostgreSQL, поэтому
является осознанным исключением из общего хранилища.
NODE_EXTRA_CA_CERTS — не конфигурация
Переменная остаётся совместимостью для дочерних процессов (MCP stdio, git)
и частью базового набора Node. Она не заменяет security.tls и не
должна использоваться как способ задать корпоративный CA. Задавайте CA через
caFile или caPem.
Изменения TLS применяются после перезапуска процесса: глобальный транспорт
строится при старте. Интерфейс показывает restartRequired.
PostgreSQL¶
Для базы действуют два независимых параметра:
storage.postgres.sslmode— режим соединения:disable,require,verify-full(алиасverify-ca).verify-fullтребует явного CA изsecurity.tlsи без него отказывается стартовать.security.tls— CA и клиентский сертификат. PostgreSQL использует тот же резолвер профилей по хосту, что и остальной egress; отдельной настройки сертификата для базы нет.
TLS-параметры в строке подключения (sslmode, sslrootcert, sslcert,
sslkey и подобные) запрещены: драйвер накладывает DSN поверх конфига и
может молча отключить проверку. Политика доверия задаётся только через
sslmode и security.tls.
Что дальше¶
- Конфигурация — полные секции
proxy,security.tlsиstorage.postgres. - Безопасность — аудит, роли и защита секретов.
- Kubernetes / Helm — CA из Secret и сетевые политики.