Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Политика, привязанная к единственному листу, который написал автор

Этот пример показывает одно внутреннее правило и факт, который делает его выразимым:

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

Два релиза, различающиеся одной переменной: та же управляемая база данных, тот же обязательный слот для учётных данных, заполненный двумя разными Features — одну разработчик подключает в Aggregate, другую оператор подключает в Release. Политика, написанная оператором, отклоняет одно подключение и разрешает другое. Запускать эту пару стоит потому, что оба подключения работают с секретным материалом, — поэтому правило нельзя сформулировать через вопрос «является ли это подключение чувствительным?», и контрольная политика ниже показывает, что происходит, если попытаться.

Всё, кроме двух файлов политик, берётся из каталога стандартной библиотеки, включая сущность Plugin для управления.

Слот и две сущности Features, которые могут его заполнить

core/datastore/mariadb объявляет один обязательный слот для учётных данных:

featuresSchema:
root_password:
required: true
sensitive: true
inject: []
description: Root database password. Recipe controls delivery (Black-Box).

sensitive: true здесь — утверждение о точке привязки, а не о каком-либо конкретном заполнении: всё, что привязывается к этому слоту, работает с секретным материалом. inject: [] закрывает доставку — куда попадают учётные данные, решает Recipe, и разработчик это не диктует.

К этому слоту привязываются две сущности Features из стандартной библиотеки, и они моделируют противоположные жизненные циклы учётных данных:

Featureкто владеет материаломчто задаёт подключение
core/secret-valueего предоставляет автордва листа values — см. ниже
core/generated-secretего создаёт и ротирует целевой движокничего; она не объявляет values

core/secret-value объявляет два своих листа асимметрично, и именно эта асимметрия — краеугольный камень всего примера:

values:
origin: { type: string, sensitive: true }
key: { type: string, required: true, default: "value" }

origin несёт материал и объявлен чувствительным. key — имя для доставки, и он намеренно оставлен неотмеченным: ключ называет, где находится материал, а не является им самим, и каждая сущность Recipe, реализующая эту Feature, выводит его в открытом виде.

core/generated-secret вообще не объявляет values, поэтому подключению нечего задавать. Это аналог, управляемый движком, а не ослабленная версия того же самого: у неё та же метка семейства учётных данных, она привязывается к тому же слоту, а её сущности Recipes ничего не выводят, поскольку учётные данные принадлежат движку, которым управляет собственная Recipe компонента.

Два релиза

aggregate-authored.yaml связывает слот способом, при котором учётные данные предоставляет автор: разработчик прикрепляет учётные данные в сущности Aggregate, и прикрепление задаёт оба листа:

features:
root_password:
type: core/secret-value
values:
key: MARIADB_ROOT_PASSWORD
origin: root-password-in-the-clear

Делегированный вариант связывает слот способом, при котором учётными данными управляет движок, и это связывание принадлежит оператору: владеет ли движок учётными данными, следует из сущности Recipe, которую выбирает сущность Manifest, поэтому release-delegated.yaml прикрепляет core/generated-secret в своей записи для db, а aggregate-delegated.yaml — это та же написанная автором сущность Aggregate без блока features::

components:
db:
features:
root_password:
type: core/generated-secret

Оба релиза используют общий manifest.yaml, который связывает все три типа для цели Terraform, поэтому различие между ними не в сущности Manifest:

components:
type:
core/datastore/mariadb:1.0.0: terraform/mariadb-rds:1.0.0
features:
type:
core/secret-value:1.0.0: terraform/variable-secret:1.0.0
core/generated-secret:1.0.0: terraform/generated-secret:1.0.0

Политика

policy.rego, подключённая к графу сборки:

package house.governance
import rego.v1
deny contains msg if {
some node_id, attachments in input.graph.spec.feature_values_mapping
some attachment_name, attachment in attachments
some leaf in attachment.sensitive_payload_leaves
msg := sprintf("%v: the %v credential carries declared-sensitive material in its payload at %v", [node_id, attachment_name, leaf])
}

sensitive_payload_leaves перечисляет листья, которые несёт полезная нагрузка этого подключения и путь которых подключённая сущность Feature объявляет чувствительным, каждый — в виде пути через точку с префиксом столпа. Читается та полезная нагрузка, которую подключение в итоге несёт, поэтому лист, стоящий на значении, которое схема сущности Feature объявляет как default, указывается наравне с листом, значение которого записал автор. Из этого следуют два вывода, и пример построен на обоих:

  • Лист появляется только там, где его покрывает объявление: объявление называет этот лист или объект, содержащий его, с посегментным сопоставлением по пути через точку. Из самого текста пути ничего не извлекается, и никакое значение не проверяется. Поэтому key, записанный рядом с origin в том же подключении, никогда не появляется: его сущность Feature ничего о нём не объявляет.
  • Подключение, полезная нагрузка которого ничего не несёт в объявленном листе, ничего не добавляет в список. Подключение делегированного релиза несёт ответ для подключения целиком и вовсе не содержит списка по листьям, поскольку ключ не передаётся, когда он был бы пустым.

Подключение находится в .aggrega-config.yaml в роли ir-verdict — это роль, которая получает граф сборки:

plugins:
governance:
- uri: governance/rego:0.9.0
role: ir-verdict
with:
sources:
- policy.rego

Роль вердикта возвращает только решение «принять или отклонить». Она может остановить эту сборку, но не может переписать Aggregate так, чтобы он соответствовал требованиям, поскольку путь, который отправляет вердикт, не может применить его как изменение. Сущность Release, которой нужна делегированная форма, получает её, подключая делегированную сущность Feature, — и никогда за счёт того, что политика незаметно подставляет её.

Сборка обоих вариантов

Terminal window
aggrega build --release release-negative-authored.yaml --auto-pull # expected to fail
aggrega build --release release-delegated.yaml --auto-pull

--auto-pull заполняет lock-файл во время сборки; однократный запуск aggrega pull --release release-<arm>.yaml заранее делает то же самое и позволяет выполнять последующие сборки без флага. Результат рендеринга и lock-файлы генерируются, а не поставляются: в этом примере зафиксированы только входные данные, а всё остальное генерируется заново.

Что возвращается

Авторский релиз отклоняется, и сборка завершается с кодом 1. E0005 — это диагностика, которую несёт отказ политики, — см. справочник по диагностике:

[… omitted: the pull's lines — the same refusal among them — and a lint notice about core/secret-value]
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: db: the root_password credential carries declared-sensitive material in its payload at values.origin
caused by: policy violation

Прочитайте путь к листу. Полезная нагрузка привязки содержит два значения; отказ называет values.origin и не упоминает values.key. Это единственное предложение — и есть результат работы полистовой пометки: одна привязка, два листа полезной нагрузки, одно объявление, один отказ.

Кроме того, отказ приходит до того, как что-либо будет отрисовано. Каталог dist/infra-authored/ вообще не создаётся, поэтому нет частичного дерева артефактов, которое нужно было бы очищать, и нет ничего на диске, что последующий шаг мог бы принять за результат.

Делегированный релиз собирается, завершается с кодом 0 и записывает два файла. dist/infra-delegated/terraform/aggrega.modules.tf — корневую конфигурацию границы:

# Root configuration for this boundary. Each component rendered here is one
# module block below, and the directory that block points at holds that
# component's own files. One configuration means one dependency graph, which is
# what lets a reference or a depends_on reach from one component to another.
module "db" {
source = "./modules/db"
}

и dist/infra-delegated/terraform/modules/db/main.tf, который начинается с блока комментариев #, идентифицирующего сборку, а затем содержит ограничение провайдера AWS, ресурс и выходное значение адреса, которое публикует Recipe:

terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 6.69"
}
}
}
resource "aws_db_instance" "db" {
identifier = "db"
engine = "mariadb"
engine_version = "11.4"
port = 3306
## ── Compute ──────────────────────────────────────────────
instance_class = "db.t3.small"
## ── Storage ──────────────────────────────────────────────
allocated_storage = 100
storage_type = "gp3"
## ── Database ─────────────────────────────────────────────
db_name = "appdb"
username = "admin"
## Black-Box: RDS manages the password via Secrets Manager.
manage_master_user_password = true
## ── HA ───────────────────────────────────────────────────
multi_az = false
## ── Backup ───────────────────────────────────────────────
backup_retention_period = 7
## ── Provider-specific overrides ──────────────────────────
}
output "address" {
value = aws_db_instance.db.address
}

manage_master_user_password = true — это делегированная форма, появившаяся в результате: учётные данные хранит движок, и сущность Release нигде не называет никаких секретных данных. Разрешённый релиз отрисовал настоящий артефакт, а не прошёл проверку, ничего не отрисовав.

Контрольный вариант: вопрос о вложении целиком

Замените подключённый источник в .aggrega-config.yaml:

sources:
- policy-attachment-wide.rego

policy-attachment-wide.rego — тот же обход, но опирающийся на attachment.sensitive — одно булево значение для всего вложения, — а не на список по отдельным листьям:

deny contains msg if {
some node_id, attachments in input.graph.spec.feature_values_mapping
some attachment_name, attachment in attachments
attachment.sensitive
msg := sprintf("%v: the %v credential handles sensitive material", [node_id, attachment_name])
}

Пересоберите оба релиза — и затем верните policy.rego на место, поскольку остальная часть этой страницы исходит из него. Теперь отклонены оба, с одной и той же фразой:

[… omitted: the pull's lines — the same refusal among them — and a lint notice about core/secret-value]
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: db: the root_password credential handles sensitive material
caused by: policy violation

Это не ошибочное срабатывание правила — правилу задают более грубый вопрос, и оно отвечает на него правильно. sensitive отражает то, что объявляют сущности: здесь оно истинно, потому что слот объявляет, что всё, что к нему привязывается, работает с секретным материалом, и слот утверждает это независимо от того, кто его заполняет. Делегированное вложение ничего не задаёт автором и всё равно является чувствительным, поэтому правило, опирающееся на этот ответ, вообще не может различить два релиза. Делегированный релиз — это сборка, которую правило по отдельным листьям разрешает, а правило для вложения целиком разрешить никак не может.

Третий факт о чувствительности, sensitive_inject, тоже не помогает: он называет ключи доставки, у которых ключ provides, на который они ссылаются, объявлен чувствительным. Здесь слот закрыт для доставки, а Feature, предоставляемая автором, не публикует раздел provides, поэтому в этом рабочем пространстве он ничего не называет. Из трёх фактов только список по отдельным листьям отвечает на вопрос «где полезная нагрузка этого вложения несёт данные», а именно об этом внутреннее правило.

Все три факта рядом, с формами полезной нагрузки и случаями, в которых каждый из них — правильный вопрос, описаны в разделе факты о вложениях, которые читает политика управления. О самом сокете — ролях, уровнях серьёзности вердиктов, канале ввода оператора — см. сокет политики, а о месте политик в продукте — Управление и соответствие требованиям.

Что эта цель показывает об авторской форме

Recipe управляемой базы данных безусловно задаёт собственную директиву движка для управляемого пароля и не читает никаких внедрённых учётных данных, поэтому на этой цели он останавливает сборку на самом авторском вложении, называя слот, вместо того чтобы принять материал, которому некуда попасть. Политика отклоняет его раньше, там, где он на самом деле находится: в файле, который рабочее пространство хранит под контролем версий. Это и есть забота управления, и она не связана с тем, что отрендерил бы какой-либо Recipe.

Именно поэтому две Features — равноправные варианты, а не альтернативы, одинаково уместные на любой цели. Привязывайте Feature с учётными данными от автора там, где вы действительно владеете учётными данными, а Feature, управляемую движком, — там, где ими владеет цель. Авторский релиз этого примера — то самое несоответствие, которое внутреннее правило может выявить автоматически.

Откуда берётся плагин

Каждая сущность, которую использует это рабочее пространство, берётся из опубликованного каталога стандартной библиотеки: сущность Component, обе сущности Features, сущность Recipe, обе сущности FeatureRecipes и сущность Plugin для управления — они читаются из реестра hub, который указывает .aggrega-config.yaml, или из рабочей копии каталога (где её взять), указанной через --catalog.

uri: governance/rego:0.9.0 называет эту сущность Plugin. Это идентификатор: координата <pluginType>/<name> плюс версия, и обе половины входят в эту форму. Версия — та, под которой плагин опубликован: hub публикует её как oci://hub.aggrega.ai/plugin/governance/rego:0.9.0. Версия участвует в разрешении: подключение, указывающее версию, которой нет ни в одном каталоге, ни в одном реестре и ни в самом бинарном файле aggrega, останавливает сборку. Бинарный файл содержит сущность движка только в версии своего собственного выпуска.

При сборке с --catalog, указывающим на рабочую копию каталога, примеру больше ничего не нужно: с бинарным файлом aggrega того выпуска, который называет подключение и который сам содержит сущность Plugin, каждая сущность разрешается без сети, а выполняется движок, скомпилированный в бинарный файл aggrega. Без него сущности читаются из hub.aggrega.ai.

Движок Rego скомпилирован в бинарный файл CLI, и его версия — это выпуск компилятора, который его поставляет. Компилятор другого выпуска читает из hub сущность Plugin, которую называет подключение, и запускает движок, скомпилированный в него самого: версия в подключении идентифицирует сущность и не выбирает движок.

Файлы

  • aggregate-authored.yaml — слот root_password, привязанный через core/secret-value в Aggregate, где автор сам задаёт ключ доставки и секретные данные.
  • aggregate-delegated.yaml — та же база данных без привязки: разработчик ничего не привязывает.
  • manifest.yaml — привязывает тип компонента и оба типа Feature к их Recipes для Terraform. Общий для обоих релизов.
  • release-negative-authored.yaml, release-delegated.yaml — по одному на каждую ветвь, у каждого своя граница directory:. Флага для места вывода нет, поэтому при двух релизах с общим каталогом второй перезаписал бы первый. release-delegated.yaml также привязывает слот в своей записи для db через core/generated-secret, ничего не задавая самостоятельно. Какая Feature заполняет слот и в каком документе — единственное различие между двумя ветвями.
  • policy.rego — внутреннее правило, привязанное к пометке на уровне отдельного листа.
  • policy-attachment-wide.rego — контрольный вариант, привязанный к ответу на уровне всей привязки. По умолчанию не подключён.
  • .aggrega-config.yaml — реестр по умолчанию и подключение механизма управления.

Создание примера

Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

Terminal window
aggrega scaffold --example policy-payload-leaf-sensitivity

Затем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:

Terminal window
cd policy-payload-leaf-sensitivity

Сборка

Terminal window
aggrega build --release release-negative-authored.yaml --auto-pull # refused; exits 1
aggrega build --release release-delegated.yaml --auto-pull # builds

С ИИ-ассистентом

ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.

Используйте только инструменты Aggrega и не создавайте папки самостоятельно. Если в папке Workspace ещё нет папки `policy-payload-leaf-sensitivity`, вызовите один раз инструмент `scaffold`, задав для `example` значение `policy-payload-leaf-sensitivity` и не задавая `dir`: он запишет пример в новую папку `policy-payload-leaf-sensitivity`. Затем вызовите инструмент `build`, задав для `workspace_root` значение `policy-payload-leaf-sensitivity`, для `release` — `release-negative-authored.yaml`, для `auto_pull` — true и для `write` — true: эта сборка должна быть отклонена, поэтому прочитайте мне отказ. Затем вызовите инструмент `build` так же, задав для `release` значение `release-delegated.yaml`. Сообщите мне, какие файлы записала эта вторая сборка; они находятся в `policy-payload-leaf-sensitivity/dist/`.