Конфигурирование приложения

Важно: в Netgap вся конфигурация считается чувствительной. Она не разделяется на «секреты» и «общий конфиг», потому что даже несекретные на первый взгляд параметры могут раскрывать топологию сети, правила взаимодействия компонентов, адреса внутренних сервисов и особенности защитного контура. Такой подход снижает риск утечки инфраструктурной информации и повышает общий уровень безопасности эксплуатации.

Netgap принимает рабочую конфигурацию как один YAML-документ через стандартный ввод процесса (stdin). Это единый способ передать настройки при запуске.

CLI используется только для выбора команды: запустить компонент или вывести шаблон конфигурации. Рабочие параметры, сетевые правила и секреты не передаются через аргументы командной строки, переменные окружения или файлы конфигурации приложения.

Формат конфигурации

Конфигурация описывается в YAML. Документ содержит секции компонента и общие секции, например observability:

listen_address: 0.0.0.0
listen_port: 8080

observability:
  service_name: netgap-gateway
  event_targets:
    - level: info
      target_id: Tech
      target_destination: Console
      target_args: ""
      format: ColorizedANSI

Точный набор полей зависит от запускаемого компонента. Чтобы получить актуальный шаблон для конкретной версии, используйте команду print-default-config:

./netgap-gateway print-default-config
./netgap-executor print-default-config

Подробное описание секций конфигурации приведено в профильных статьях документации. Например, секция observability описана в разделе Наблюдаемость, а ее отдельные функции — в статьях про события, трассировку, метрики, проверку готовности и SIEM.

Передача конфигурации в приложение

Для запуска рабочей команды YAML должен поступить в stdin:

trusted-secret-provider netgap-gateway | exec env -i ./netgap-gateway run

В этом примере внешний доверенный механизм формирует YAML и передает его процессу Netgap по pipe. Команда env -i запускает приложение с очищенным окружением, чтобы переменные окружения не становились неявным каналом конфигурации.

Пример запуска gateway:

vault kv get -format=json secret/netgap/gateway \
  | jq -r '.data.data.config_yaml' \
  | exec env -i ./netgap-gateway run

Пример запуска executor:

vault kv get -format=json secret/netgap/executor \
  | jq -r '.data.data.config_yaml' \
  | exec env -i ./netgap-executor run

В production вместо vault может использоваться другой доверенный secret-provider, init-система, контейнерный runtime или оркестратор. Важно, чтобы на вход приложения поступал полный YAML-документ, а рабочая конфигурация не сохранялась в файлы приложения и не передавалась через CLI-флаги.

Ручной запуск для проверки

Для локальной проверки можно сгенерировать шаблон, отредактировать его в безопасном хранилище и передать результат в stdin:

secure-config-renderer --component gateway | exec env -i ./netgap-gateway run

Также для ручной проверки можно передать YAML напрямую из строки:

echo "<CONFIG_YAML>" | exec env -i ./netgap-executor run

Внимание: этот способ небезопасен для рабочей конфигурации. Значение CONFIG_YAML может попасть в историю shell, журналы терминала, средства аудита команд или другие механизмы наблюдения за пользовательской сессией.

Или прочитать подготовленный YAML-файл и передать его содержимое в stdin:

cat ./file/name.yaml | exec env -i ./netgap-executor run

Внимание: этот способ также небезопасен для рабочей конфигурации. YAML-файл оставляет персистентный след на файловой системе и может быть прочитан резервным копированием, индексаторами, средствами аудита или пользователями с доступом к хосту. Используйте такие варианты только для локальной проверки в контролируемом окружении.

Если оператор временно использует shell-команды для ручного запуска, нужно учитывать политику безопасности окружения: не сохранять секреты в истории команд, временных файлах и логах терминала.

Почему используется именно stdin

Подход выбран в ADR 0002: Выбор способа конфигурации приложения. Краткая причина: Netgap ориентирован на Zero-Trust окружения, где важно минимизировать персистентный след рабочей конфигурации и снизить риск утечки секретов через файловую систему, переменные окружения, историю команд и механизмы инспекции процессов ОС.

Практические следствия:

• приложение читает полный YAML из stdin при старте;
• при ошибке синтаксиса, отсутствии обязательных полей или логическом конфликте конфигурация отклоняется до запуска сетевых компонентов;
• файлы, .env, переменные окружения и CLI-флаги не являются источниками рабочей конфигурации;
• команда print-default-config помогает получить шаблон, но не запускает приложение.