Перейти до вмісту
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 з даними від автора там, де ви справді володієте обліковими даними, а керований рушієм — там, де ними володіє ціль. Авторський реліз цього прикладу — це саме та невідповідність, яку внутрішнє правило може виявити механічно.

Звідки береться плагін

Кожна сутність, яку використовує цей робочий простір, походить з опублікованого каталогу стандартної бібліотеки: сутність Component, дві Features, Recipe, дві FeatureRecipes і сутність Plugin для керування — їх зчитують із реєстру hub, який називає .aggrega-config.yaml, або з checkout-копії каталогу (де її отримати), вказаної через --catalog.

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

Якщо приклад зібрано з --catalog, що вказує на checkout-копію каталогу, йому більше нічого не потрібно: з бінарним файлом 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/`.