docs(release): add readiness v0.2 hardening

2026-06-03 22:32:16 +03:00
parent 8db9f180ab
commit ad9a3c24cb
10 changed files with 618 additions and 0 deletions
@@ -0,0 +1,92 @@
+# Акт приемки пилота DetMir
+
+Документ-шаблон для коммерческого пилота DetMir/AWatch-rus. Перед передачей
+заказчику заполнить реквизиты сторон, даты, состав стенда и результаты
+проверок. Публичная версия не должна содержать live IP, домены, ФИО
+сотрудников, case IDs, evidence paths или screenshots с реальными данными.
+
+## 1. Стороны
+
+| Поле | Значение |
+|---|---|
+| Заказчик | `<CUSTOMER_LEGAL_NAME>` |
+| Исполнитель/правообладатель | `<RIGHT_HOLDER_LEGAL_NAME>` |
+| Проект | DetMir, программный комплекс AWatch-rus |
+| Период пилота | `<PILOT_START_DATE>` - `<PILOT_END_DATE>` |
+| Контур | `<PILOT_CONTOUR_NAME>` |
+
+## 2. Цель пилота
+
+Проверить применимость DetMir для:
+
+- мониторинга активности рабочих мест;
+- управленческой аналитики Workforce;
+- технического аудита ИТ-контура;
+- фиксации DLP-lite/ИБ-событий;
+- просмотра evidence и отчетов в портале;
+- контроля готовности системы через signed readiness bundle.
+
+## 3. Состав поставки
+
+| Компонент | Проверка |
+|---|---|
+| DetMir portal | вход, роли оператора/руководителя/владельца |
+| ActivityWatch telemetry | актуальность bucket/event данных |
+| Workforce analytics | индекс активности, веса приложений, drill-down |
+| DLP-lite incidents | USB/print/clipboard/file/email/browser signals, если включены |
+| Evidence workflow | preview/download/view audit |
+| Grafana dashboards | наличие данных и отсутствие query errors |
+| Readiness bundle | checksum/signature/fingerprint |
+| Prometheus alerts | readiness/signature alerts настроены |
+
+## 4. Критерии приемки
+
+Пилот считается успешным, если:
+
+- портал доступен ответственным пользователям заказчика;
+- telemetry freshness находится в согласованных пределах;
+- readiness status = `OK` или все `WARN` имеют согласованный план устранения;
+- signed readiness bundle проходит проверку;
+- не менее одного управленческого отчета сформировано и принято заказчиком;
+- не менее одного test incident/evidence workflow пройден end-to-end;
+- заказчик подтвердил, что состав данных и уведомлений соответствует правилам
+  внутреннего контроля и локальным нормативным документам.
+
+## 5. Результаты проверок
+
+| Проверка | Результат | Комментарий |
+|---|---|---|
+| Portal login | `<OK/WARN/FAIL>` | `<COMMENT>` |
+| Readiness bundle | `<OK/WARN/FAIL>` | `<COMMENT>` |
+| Workforce report | `<OK/WARN/FAIL>` | `<COMMENT>` |
+| DLP-lite incident | `<OK/WARN/FAIL>` | `<COMMENT>` |
+| Evidence preview/download | `<OK/WARN/FAIL>` | `<COMMENT>` |
+| Grafana dashboards | `<OK/WARN/FAIL>` | `<COMMENT>` |
+| Alerting | `<OK/WARN/FAIL>` | `<COMMENT>` |
+
+## 6. Ограничения пилота
+
+- DetMir не заявляется как сертифицированная СЗИ, SIEM, EDR/XDR или
+  enterprise DLP.
+- pfSense/network quarantine интеграции являются опциональным интеграционным
+  слоем и не входят в обязательный состав пилота.
+- Telegram runtime может использоваться как интеграционный канал уведомлений,
+  но не является ядром продукта.
+- Результаты Workforce analytics являются управленческими proxy-метриками и
+  должны трактоваться с учетом ролей, весов приложений и локальных регламентов.
+
+## 7. Решение
+
+| Решение | Отметка |
+|---|---|
+| Пилот принят без замечаний | `<YES/NO>` |
+| Пилот принят с замечаниями | `<YES/NO>` |
+| Требуется доработка | `<YES/NO>` |
+| Рекомендуется коммерческое внедрение | `<YES/NO>` |
+
+## 8. Подписи
+
+| Сторона | ФИО/должность | Подпись | Дата |
+|---|---|---|---|
+| Заказчик | `<CUSTOMER_SIGNER>` |  |  |
+| Исполнитель | `<CONTRACTOR_SIGNER>` |  |  |
@@ -0,0 +1,80 @@
+# Network perimeter и pfSense
+
+Документ описывает роль pfSense в архитектуре DetMir/AWatch-rus для
+коммерческих внедрений и экспертной оценки. pfSense рассматривается как
+опциональный интеграционный слой сетевого периметра, а не как обязательная
+часть продукта.
+
+## 1. Позиция продукта
+
+DetMir/AWatch-rus поставляет:
+
+- сбор и нормализацию endpoint/server telemetry;
+- Workforce analytics;
+- технический аудит;
+- DLP-lite/ИБ evidence workflow;
+- readiness checks и portal reporting.
+
+Сетевой шлюз, firewall, NAT, VPN и quarantine enforcement могут быть
+интегрированы с DetMir, но не входят в минимальный состав продукта.
+
+## 2. Роль pfSense
+
+pfSense может использоваться как:
+
+- источник сетевого контекста;
+- внешний policy enforcement point;
+- шлюз для ограничений VLAN/alias/rules;
+- источник логов для корреляции с endpoint activity.
+
+DetMir не требует pfSense для базовой работы портала, readiness, workforce,
+DLP-lite evidence и отчетов.
+
+## 3. Интеграционные границы
+
+| Слой | Статус |
+|---|---|
+| Endpoint telemetry | обязательный слой DetMir |
+| Server-side checks/readiness | обязательный слой DetMir |
+| Portal/Grafana/Prometheus | обязательный слой DetMir |
+| pfSense logs/context | опциональная интеграция |
+| pfSense policy enforcement | опциональная интеграция с отдельным решением |
+| Автоматический quarantine | не включать без отдельного согласования |
+
+## 4. Безопасный режим внедрения
+
+По умолчанию:
+
+- DetMir только читает сетевой контекст, если интеграция включена;
+- любые изменения firewall/NAT/VPN/quarantine запрещены без отдельного change
+  request;
+- pfSense credentials хранятся вне Git и вне public release assets;
+- public docs используют placeholders и TEST-NET адреса.
+
+## 5. Что не заявлять
+
+Для реестра российского ПО и публичной экспертизы не позиционировать DetMir как:
+
+- firewall;
+- NAC;
+- VPN gateway;
+- сертифицированное средство сетевой защиты;
+- обязательный модуль управления pfSense.
+
+Корректная формулировка:
+
+> DetMir поддерживает интеграцию с сетевым периметром заказчика, включая
+> pfSense-compatible gateways, как внешний источник контекста и опциональную
+> точку применения политик.
+
+## 6. Будущий roadmap
+
+Возможные этапы развития:
+
+1. Read-only import сетевых событий.
+2. Корреляция endpoint activity и VPN/network context.
+3. Manual approval workflow для сетевых ограничений.
+4. Controlled enforcement через allowlist политик.
+5. Audit trail каждого сетевого действия.
+
+До отдельного решения владельца продукта pfSense runtime остается no-touch.
@@ -30,6 +30,28 @@ Additional readiness artifacts:
 - `docs/screenshots/release-v0.1/portal-reports-risk.png`
 - `docs/screenshots/release-v0.1/portal-owner-summary.png`

+## Release-readiness v0.2 overlay
+
+Additional release/commercial-readiness artifacts:
+
+- `scripts/generate_release_sbom_v0_2.sh`
+- `scripts/verify_release_assets.sh`
+- `.github/workflows/release-assets.yml`
+- `docs/RELEASE_READINESS_V0.2_RU.md`
+- `docs/CUSTOMER_PILOT_ACCEPTANCE_RU.md`
+- `docs/NETWORK_PERIMETER_PFSENSE_RU.md`
+
+Generated GitHub Release assets:
+
+- `sbom/cyclonedx-rust-v0.2.json`
+- `sbom/spdx-rust-v0.2.json`
+- `sbom/cargo-metadata-v0.2.json`
+- `sbom/cargo-tree-v0.2.txt`
+- `sbom/python-inputs-v0.2.txt`
+- `RELEASE_ASSETS_MANIFEST-v0.2.json`
+- `SHA256SUMS-v0.2.txt`
+- `SHA256SUMS-v0.2.txt.sig`
+
 ## Artifacts

 ```text
@@ -16,6 +16,16 @@ Release type: public expert-review/source package.
 - architecture схема `docs/diagrams/release-readiness-v0.1.md`;
 - обезличенные screenshots портала в `docs/screenshots/release-v0.1/`.

+## Release-readiness v0.2 addendum
+
+Добавлен слой коммерческого/release hardening:
+
+- machine SBOM generation для CycloneDX и SPDX;
+- CI self-test checksum/signature verifier;
+- шаблон customer pilot acceptance act;
+- документ network perimeter/pfSense как optional integration layer;
+- требование подписанного Git tag и detached signature для release assets.
+
 ## Что входит

 - Обезличенный public source package DetMir/AWatch-rus.
@@ -0,0 +1,117 @@
+# Release readiness v0.2
+
+`release-readiness-v0.2` усиливает v0.1 в части коммерческого релиза и
+подготовки к реестру российского ПО.
+
+Дата фиксации: `2026-06-03`.
+
+## 1. Что добавлено
+
+| Блок | Файл |
+|---|---|
+| Machine SBOM generation | `scripts/generate_release_sbom_v0_2.sh` |
+| Release asset verification | `scripts/verify_release_assets.sh` |
+| CI checksum/signature self-test | `.github/workflows/release-assets.yml` |
+| Pilot acceptance act | `docs/CUSTOMER_PILOT_ACCEPTANCE_RU.md` |
+| pfSense perimeter positioning | `docs/NETWORK_PERIMETER_PFSENSE_RU.md` |
+
+## 2. Machine SBOM as GitHub Release asset
+
+Сгенерировать assets:
+
+```bash
+bash scripts/generate_release_sbom_v0_2.sh dist/release-v0.2
+```
+
+Ожидаемые файлы:
+
+```text
+dist/release-v0.2/sbom/cyclonedx-rust-v0.2.json
+dist/release-v0.2/sbom/spdx-rust-v0.2.json
+dist/release-v0.2/sbom/cargo-metadata-v0.2.json
+dist/release-v0.2/sbom/cargo-tree-v0.2.txt
+dist/release-v0.2/sbom/python-inputs-v0.2.txt
+dist/release-v0.2/RELEASE_ASSETS_MANIFEST-v0.2.json
+dist/release-v0.2/SHA256SUMS-v0.2.txt
+```
+
+Эти файлы публикуются как GitHub Release assets. Они не хранятся в tracked
+source, потому что `dist/` является generated output.
+
+## 3. Подпись release assets
+
+Release manager подписывает checksum file detached signature:
+
+```bash
+openssl dgst -sha256 -sign <RELEASE_PRIVATE_KEY.pem> \
+  -out dist/release-v0.2/SHA256SUMS-v0.2.txt.sig \
+  dist/release-v0.2/SHA256SUMS-v0.2.txt
+```
+
+Проверка:
+
+```bash
+RELEASE_VERIFY_PUBLIC_KEY=<RELEASE_PUBLIC_KEY.pem> \
+  bash scripts/verify_release_assets.sh dist/release-v0.2
+```
+
+## 4. Подписанный Git tag
+
+Требование для финального релиза:
+
+```bash
+git tag -s release-readiness-v0.2 -m "release-readiness-v0.2"
+git tag -v release-readiness-v0.2
+git push origin release-readiness-v0.2
+```
+
+Tag должен быть подписан пользовательским ключом правообладателя/maintainer, а
+не сторонним системным ключом пакетов ОС.
+
+## 5. CI gate
+
+Workflow:
+
+```text
+.github/workflows/release-assets.yml
+```
+
+Проверяет:
+
+- генерацию CycloneDX/SPDX JSON;
+- валидность JSON;
+- self-test checksum/signature verifier;
+- отрицательные сценарии checksum mismatch и missing signature.
+
+## 6. Pilot acceptance
+
+Шаблон:
+
+```text
+docs/CUSTOMER_PILOT_ACCEPTANCE_RU.md
+```
+
+Использовать для коммерческого пилота после установки и первичной настройки.
+Публичная версия должна оставаться обезличенной.
+
+## 7. pfSense perimeter
+
+Документ:
+
+```text
+docs/NETWORK_PERIMETER_PFSENSE_RU.md
+```
+
+Ключевая позиция: pfSense является опциональным интеграционным слоем, а не
+обязательной частью продукта DetMir/AWatch-rus.
+
+## 8. Acceptance checklist
+
+- SBOM assets сгенерированы.
+- `SHA256SUMS-v0.2.txt` создан.
+- `SHA256SUMS-v0.2.txt.sig` создан release private key.
+- `scripts/verify_release_assets.sh` проходит с public key.
+- Git tag подписан ключом maintainer.
+- GitHub release содержит SBOM JSON/TXT, manifest, checksum и signature.
+- `CUSTOMER_PILOT_ACCEPTANCE_RU.md` заполнен для пилотного заказчика.
+- pfSense не описан как обязательный компонент продукта.
@@ -147,6 +147,22 @@ git ls-files '*.py'

 Сформировать машинные перечни зависимостей.

+Для release-readiness v0.2 используется единый генератор:
+
+```bash
+bash scripts/generate_release_sbom_v0_2.sh dist/release-v0.2
+```
+
+Он формирует:
+
+- `cyclonedx-rust-v0.2.json`;
+- `spdx-rust-v0.2.json`;
+- `cargo-metadata-v0.2.json`;
+- `cargo-tree-v0.2.txt`;
+- `python-inputs-v0.2.txt`;
+- `RELEASE_ASSETS_MANIFEST-v0.2.json`;
+- `SHA256SUMS-v0.2.txt`.
+
 Rust:

 ```bash
@@ -202,6 +218,19 @@ sha256sum dist/* install-kit-awindows-*.zip install-kit-awindows-*.tar.gz \
  > SHA256SUMS
 ```

+Проверка release assets v0.2:
+
+```bash
+RELEASE_VERIFY_PUBLIC_KEY=<RELEASE_PUBLIC_KEY.pem> \
+  bash scripts/verify_release_assets.sh dist/release-v0.2
+```
+
+CI self-test:
+
+```bash
+bash scripts/verify_release_assets.sh --self-test
+```
+
 ## 9. Документы для реестра российского ПО

 Проверить наличие и актуальность: