ADR: Выбор целевых платформ сборки

• Status: Accepted by Andrei Ganiushkin andrey@ganyushkin.ru
• Date: 2026-08-02
• Authors: Andrei Ganiushkin andrey@ganyushkin.ru
• Related issues: -

Context

Netgap поставляется как набор исполняемых файлов. Требуется зафиксировать закрытый список целевых платформ (target triple), под которые собираются, подписываются и публикуются релизные артефакты.

Приложение реализует паттерн logical airgap и устанавливается на границе доверенного и недоверенного контуров. Это накладывает ограничения на характер поставки:

• целевая среда часто изолирована: нет доступа в интернет, нет внутренних репозиториев пакетов, установка дополнительных зависимостей требует отдельного согласования;
• на узлах периметра нежелательно устанавливать среды исполнения, интерпретаторы, менеджеры пакетов и разделяемые библиотеки: каждая дополнительная зависимость расширяет поверхность атаки и попадает в область аудита;
• поставка должна проверяться и подписываться (см. ADR 0005), поэтому набор платформ должен быть конечным, явным и воспроизводимым.

Ключевое требование к артефакту: минимум зависимостей в целевой среде. Исполняемый файл должен запускаться на «голой» машине без установки библиотек рядом с ним, при пустом окружении и без прав администратора (кроме привязки к портам ниже 1024).

Существенные факторы выбора:

• инфраструктура построена преимущественно на Linux;
• часть оборудования и стендов, включая лабораторные, работает на arm64;
• в реальных контурах присутствуют легаси-системы на Windows, а изолируемый сегмент и остальная сеть могут иметь разные ОС (гетерогенные сети);
• российские сертифицированные дистрибутивы Linux (Astra Linux, РЕД ОС, ALT Server) являются целевой средой и требуют отдельного подтверждения работоспособности;

Rust (см. ADR 0000) позволяет получить статически слинкованный бинарный файл без внешнего runtime, что делает выбор триплетов основным механизмом управления зависимостями поставки.

Decision

Зафиксировать закрытый список целевых платформ релиза:

Target triple	Среда	Модель линковки
x86_64-unknown-linux-musl	Linux x86_64	статическая (musl, static-pie)
aarch64-unknown-linux-musl	Linux arm64	статическая (musl, static-pie)
x86_64-pc-windows-gnu	Windows x86_64, GNU ABI (MinGW-w64)	статическая линковка runtime (-C target-feature=+crt-static)

Правила, вытекающие из решения:

1. Список является исчерпывающим. Добавление или удаление платформы — изменение релизного процесса, которое должно быть отражено в RELEASING.md, в Makefile (RELEASE_TARGET_PLATFORMS), в Cross.toml и в документах runtime requirements.
2. Для Linux используются исключительно *-musl-таргеты, а не *-gnu. Артефакт не должен зависеть от версии glibc дистрибутива: это снимает вопрос совместимости с любым дистрибутивом, включая сертифицированные российские ОС и старые ядра (минимум — Linux kernel 3.2).
3. Для Windows используется GNU ABI (MinGW-w64), а не MSVC. Toolchain MinGW-w64 распространяем, поэтому сборка Windows-артефакта выполняется в контейнере на машине с любой ОС и не требует Windows-машины с инструментарием Microsoft. Runtime линкуется статически, поэтому .exe импортирует только DLL, входящие в состав Windows (kernel32, ntdll, msvcrt, ws2_32, advapi32, bcrypt, crypt32), и не требует ни MinGW-w64 runtime, ни Visual C++ Redistributable. Минимальная поддерживаемая версия — Windows 10 1607 / Windows Server 2016 x64.
4. Все три платформы всегда собираются через cross в контейнерах, зафиксированных в Cross.toml (по тегу или digest), даже если машина сборки совпадает с целевой платформой. Нативная сборка релизного таргета запрещена: окружение сборки фиксируется в netgap-cicd-env.lock и проверяется make check-release-env-lock.
5. Базовый уровень CPU: x86-64-v1 (SSE2) для x86_64 и ARMv8-A для aarch64. Расширения (AES-NI, AVX2, SHA, NEON, ARM crypto) используются при их наличии, но не являются обязательными. Это исключает отказ запуска на старом оборудовании легаси-контуров.
6. Для каждой целевой платформы поддерживается документ runtime requirements (deliverable/runtime-requirements/<target>.yaml и его человекочитаемые версии), который попадает в подписанную поставку. Соответствие документа реальным зависимостям бинарных файлов проверяется автоматически.
7. Поддержка Astra Linux, РЕД ОС и ALT Server обеспечивается свойствами musl-таргета, но обязательно требует отдельного функционального тестирования на этих дистрибутивах перед заявлением о поддержке. Статическая линковка снимает вопрос зависимостей, но не снимает вопросы политик безопасности этих ОС: мандатное разграничение доступа и замкнутая программная среда Astra Linux (PARSEC, astra-modeswitch, контроль целостности и подписи исполняемых файлов), SELinux в РЕД ОС, политики noexec и ограничения на статические PIE-бинарные файлы. Результаты тестирования на этих ОС фиксируются отдельно.
8. Поддержка гетерогенных сетей является следствием решения: компоненты Netgap на разных сторонах логического разрыва могут работать на разных ОС и архитектурах. Допустимая конфигурация — изолируемый контур на Windows x86_64, внешний контур на Linux x86_64 или arm64, и наоборот. Совместимость обеспечивается протоколом взаимодействия компонентов, а не общей платформой, поэтому кросс-платформенные связки должны входить в набор e2e-сценариев.

Considered Alternatives

Alternative 1: x86_64-unknown-linux-musl, aarch64-unknown-linux-musl, x86_64-pc-windows-gnu

Три статически линкуемых таргета: Linux x86_64, Linux arm64 и Windows x86_64 с GNU ABI.

• Pros:
  • Нулевые зависимости в целевой среде: musl-бинарные файлы полностью статические, Windows-артефакт использует только системные DLL.
  • Покрывает основной сценарий эксплуатации: инфраструктура заказчиков и лабораторий на Linux.
  • Покрывает arm64-оборудование и стенды без отдельной ветки поставки.
  • Обеспечивает работу в гетерогенных сетях, включая изолируемый контур на Windows.
  • Не требует машин Windows или arm64 для сборки: все три платформы собираются в Linux-контейнерах.
  • Совместимость с любым дистрибутивом Linux без привязки к версии glibc, что критично для сертифицированных российских ОС.
  • Минимальный набор комбинаций для сборки, подписи, проверки и хранения артефактов — 3 платформы, каждая со своей подписью.
• Cons:
  • Отсутствует поддержка Windows arm64 и macOS.
  • musl в статической сборке даёт худшую производительность аллокатора по сравнению с glibc на некоторых профилях нагрузки.
  • GNU ABI на Windows менее типичен, чем MSVC, и хуже интегрируется с нативными средствами отладки Windows.
• Reason for selection: вариант даёт минимальные требования к целевой среде при полном покрытии реальных сценариев развёртывания и не требует парка машин сборки под каждую ОС.

Alternative 2: Linux-таргеты на glibc (*-unknown-linux-gnu)

Сборка Linux-артефактов под glibc вместо musl.

• Pros:
  • Лучшая производительность аллокатора и потоковой подсистемы на части нагрузок.
  • Стандартная для дистрибутивов модель линковки, привычная для эксплуатации.
  • Возможность динамически подключать системные библиотеки, включая обновляемые системой.
• Cons:
  • Артефакт зависит от версии glibc машины сборки: бинарный файл, собранный на новой системе, не запустится на более старой.
  • Для сертифицированных ОС потребуется сборка под каждую версию дистрибутива, что кратно увеличивает число артефактов, подписей и проверок.
  • В изолированном контуре появляется требование к набору установленных пакетов, что противоречит принципу минимальных зависимостей.
• Reason for rejection: зависимость от версии glibc целевой машины несовместима с требованием запуска на «голой» изолированной системе и приводит к неконтролируемому росту матрицы сборки.

Alternative 3: Windows-таргет на MSVC (x86_64-pc-windows-msvc)

Сборка Windows-артефакта нативным инструментарием Microsoft.

• Pros:
  • Нативный ABI Windows, лучшая совместимость с системными средствами отладки, профилирования и анализа аварийных дампов.
  • Более распространённый и лучше поддерживаемый вариант для коммерческой поставки под Windows.
  • Прямая совместимость с подписью Authenticode и корпоративными политиками проверки бинарных файлов.
• Cons:
  • Требуется машина сборки с Windows и установленным Microsoft Build Tools: toolchain не распространяем и не может быть помещён в контейнер релизной сборки.
  • Ломается единая модель сборки «все платформы в контейнерах на любой машине» и усложняется воспроизводимость окружения релиза.
  • Требуется отдельная лицензионная и инфраструктурная поддержка Windows-раннера в CI/CD.
• Reason for rejection: нарушает воспроизводимость и единообразие релизного процесса; получаемое преимущество не окупает отдельного парка Windows-машин сборки на текущем этапе. Решение может быть пересмотрено при появлении требования Authenticode-подписи.

Alternative 4: Расширенный список платформ (добавление Windows arm64, macOS, 32-битных целей)

Поставка также под aarch64-pc-windows-msvc, *-apple-darwin и 32-битные архитектуры.

• Pros:
  • Более широкое покрытие возможных сред эксплуатации.
  • Возможность запускать компоненты на рабочих станциях разработчиков и администраторов без эмуляции.
• Cons:
  • Каждая платформа умножает объём сборки, тестирования, ручной подписи всеми платформами, хранения артефактов и сопровождения документов runtime requirements.
  • Для этих платформ отсутствует подтверждённый спрос со стороны целевых сценариев развёртывания.
  • Растёт время релизного пайплайна и вероятность частичного отказа релиза из-за неосновной платформы.
• Reason for rejection: стоимость сопровождения платформы в релизном процессе высокая, а сценарии эксплуатации на текущем этапе не подтверждены. Платформа может быть добавлена позже по фактическому требованию.

Alternative 5: Поставка в виде контейнерных образов вместо нативных бинарных файлов

Единый артефакт — OCI-образ, запускаемый через container runtime.

• Pros:
  • Одна модель поставки для всех Linux-сред, изоляция процесса средствами runtime.
  • Привычная модель развёртывания для современной инфраструктуры.
• Cons:
  • Требует наличия container runtime в целевой среде, что является тяжёлой зависимостью и часто недопустимо на узлах периметра и в аттестованных контурах.
  • Не решает задачу поставки под Windows-контуры с легаси-системами.
  • Расширяет поверхность атаки и область аудита за счёт слоёв образа и самого runtime.
• Reason for rejection: противоречит требованию минимальных зависимостей в целевой среде. Контейнерная поставка возможна как дополнительный формат поверх тех же бинарных файлов, но не вместо них.

Consequences

Positive

• Поставка не требует установки библиотек, runtime и пакетов на целевой машине: достаточно скопировать исполняемый файл.
• Один Linux-артефакт на архитектуру работает на любом дистрибутиве, включая сертифицированные российские ОС, без пересборки под версию дистрибутива.
• Поддержка arm64 закрывает потребность лабораторий и оборудования на этой архитектуре.
• Windows-артефакт позволяет включать в контур легаси-системы и строить гетерогенные конфигурации, где стороны логического разрыва работают на разных ОС.
• Список из трёх платформ делает предсказуемыми объём релизного пайплайна, число подписей и состав опубликованных артефактов.
• Сборка всех платформ в контейнерах не требует парка машин под каждую ОС и обеспечивает воспроизводимость окружения релиза.
• Минимальный набор системных зависимостей упрощает аудит поставки и согласование установки в аттестованных контурах.

Negative

• Статическая линковка означает, что уязвимость в зависимости устраняется только перевыпуском релиза, а не обновлением системного пакета.
• musl может уступать glibc по производительности аллокатора на отдельных профилях нагрузки, что требует контроля нагрузочными тестами.
• GNU ABI на Windows ограничивает применение нативных средств отладки и не даёт Authenticode-подписи «из коробки».
• Не поддерживаются Windows arm64, macOS и 32-битные архитектуры.
• Каждая целевая платформа удваивает объём тестирования: unit, e2e, нагрузочные и кросс-платформенные сценарии выполняются отдельно.

Risks and Mitigations

• Risk: статический бинарный файл не запустится или будет заблокирован политиками безопасности Astra Linux, РЕД ОС или ALT Server (замкнутая программная среда, мандатное разграничение доступа, контроль целостности, noexec, SELinux).
  • Mitigation: до заявления о поддержке провести функциональное тестирование на каждой из этих ОС, включая запуск в режиме замкнутой программной среды и под мандатными метками; зафиксировать результаты и требования к настройке в документации поставки.
• Risk: производительность musl-сборки окажется хуже требуемой на реальных нагрузках.
  • Mitigation: включить целевые платформы в нагрузочные тесты релизного пайплайна и контролировать деградацию по перцентилям задержки; при подтверждённой проблеме рассмотреть замену аллокатора без смены триплета.
• Risk: уязвимость в статически слинкованной зависимости останется в поставке до следующего релиза.
  • Mitigation: регулярный cargo audit и cargo deny в пайплайне, выпуск patch-релиза по ветке support/* при критичных находках.
• Risk: в кросс-платформенной конфигурации (Windows на одной стороне, Linux на другой) проявятся различия в поведении сети, файловой системы, прав доступа или обработки сигналов.
  • Mitigation: включить в e2e-сценарии связки Linux↔Windows и Linux x86_64↔Linux arm64, а не только однородные конфигурации.
• Risk: в поставку случайно попадёт зависимость от внешней библиотеки или DLL из-за новой зависимости, компилирующей C/C++ код.
  • Mitigation: make check-runtime-requirements при сборке релизной поставки читает реальные зависимости из заголовков ELF и PE и прерывает сборку при незадекларированной библиотеке; для Windows статическая линковка runtime закреплена явно в .cargo/config.toml.
• Risk: появится требование поддержать платформу вне списка (например Windows arm64 или macOS).
  • Mitigation: список платформ пересматривается отдельным ADR; добавление платформы включает обновление Makefile, Cross.toml, документов runtime requirements, релизного процесса и схемы подписи.

References

• ADR 0000: Выбор основного языка разработки.
• ADR 0005: Подпись артефактов релиза контрибьютором по каждой платформе.
• ADR 0007: Стратегия слияния веток.
• RELEASING.ru.md, RELEASING.md, раздел «Целевые платформы».
• Cross.toml, .cargo/config.toml, Makefile (RELEASE_TARGET_PLATFORMS).
• deliverable/runtime-requirements/.
• Rust Platform Support.
• cross.