Политика, привязанная к единственному листу, который написал автор
Этот пример показывает одно внутреннее правило и факт, который делает его выразимым:
Слот для учётных данных можно заполнить. Его нельзя заполнить, записав секретный материал в собственный исходный код рабочего пространства.
Два релиза, различающиеся одной переменной: та же управляемая база данных, тот же обязательный слот для учётных данных, заполненный двумя разными 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, — и никогда за счёт того, что политика незаметно подставляет её.
Сборка обоих вариантов
aggrega build --release release-negative-authored.yaml --auto-pull # expected to failaggrega 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.regopolicy-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— реестр по умолчанию и подключение механизма управления.
Создание примера
Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.
Запишите пример в новую папку, названную по его имени:
aggrega scaffold --example policy-payload-leaf-sensitivityЗатем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:
cd policy-payload-leaf-sensitivityСборка
aggrega build --release release-negative-authored.yaml --auto-pull # refused; exits 1aggrega 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/`.