Một chính sách dựa trên đúng một lá mà tác giả đã viết
Ví dụ này dạy một quy định nội bộ và sự thật khiến nó có thể diễn đạt được:
Một khe thông tin xác thực có thể được điền. Nó không được điền bằng cách viết dữ liệu bí mật vào chính mã nguồn của workspace.
Hai bản phát hành, chỉ khác nhau một biến: cùng một cơ sở dữ liệu được quản lý, cùng một khe thông tin xác thực bắt buộc, được điền bởi hai Features khác nhau — một do nhà phát triển gắn trong Aggregate, một do người vận hành gắn trong Release. Một chính sách do người vận hành viết từ chối cái này và cho phép cái kia. Điều khiến cặp này đáng chạy là cả hai lần gắn đều xử lý dữ liệu bí mật — vì vậy quy định không thể được viết dựa trên câu hỏi “lần gắn này có nhạy cảm không?”, và chính sách đối chứng bên dưới cho thấy điều gì xảy ra khi bạn thử làm vậy.
Mọi thứ, trừ hai tệp chính sách, đều đến từ catalog thư viện chuẩn, kể cả thực thể Plugin quản trị.
Slot, và hai Features có thể lấp đầy nó
core/datastore/mariadb khai báo một slot thông tin xác thực bắt buộc:
featuresSchema: root_password: required: true sensitive: true inject: [] description: Root database password. Recipe controls delivery (Black-Box).sensitive: true ở đó là một khẳng định về điểm liên kết chứ không về một cách lấp đầy cụ thể nào: bất cứ thứ gì liên kết với slot này đều xử lý dữ liệu bí mật. inject: [] đóng việc phân phối — Recipe quyết định thông tin xác thực đi đến đâu, và nhà phát triển không áp đặt điều đó.
Hai Features của thư viện chuẩn liên kết với slot đó, và chúng mô hình hóa hai vòng đời thông tin xác thực trái ngược nhau:
| Feature | ai sở hữu dữ liệu bí mật | một attachment viết những gì |
|---|---|---|
core/secret-value | một tác giả cung cấp nó | hai leaf values — xem bên dưới |
core/generated-secret | engine đích cấp phát và xoay vòng nó | không gì cả; nó không khai báo values nào |
core/secret-value khai báo hai leaf của nó một cách bất đối xứng, và sự bất đối xứng đó chính là điểm then chốt của toàn bộ ví dụ này:
values: origin: { type: string, sensitive: true } key: { type: string, required: true, default: "value" }origin mang dữ liệu bí mật và được khai báo là nhạy cảm. key là một tên phân phối và được cố ý để không đánh dấu — một key đặt tên cho nơi dữ liệu bí mật nằm chứ không phải bản thân dữ liệu đó, và mọi Recipe triển khai Feature này đều kết xuất nó ở dạng rõ.
core/generated-secret hoàn toàn không khai báo values, nên không có gì để một attachment viết. Nó là đối tác do engine quản lý chứ không phải một phiên bản yếu hơn của cùng một thứ: nó mang cùng nhãn họ thông tin xác thực, nó liên kết với cùng slot, và các Recipes của nó không kết xuất gì, vì thông tin xác thực thuộc về engine mà chính Recipe của component quản lý.
Hai bản phát hành
aggregate-authored.yaml ràng buộc slot theo cách do tác giả cung cấp: nhà phát triển gắn thông tin xác thực trong Aggregate, và phần gắn kèm viết cả hai lá:
features: root_password: type: core/secret-value values: key: MARIADB_ROOT_PASSWORD origin: root-password-in-the-clearNhánh ủy quyền ràng buộc slot theo cách do engine quản lý, và việc ràng buộc đó thuộc về người vận hành: engine có sở hữu thông tin xác thực hay không là do Recipe mà Manifest chọn quyết định, vì vậy release-delegated.yaml gắn core/generated-secret vào mục của nó cho db, và aggregate-delegated.yaml là Aggregate đã viết nhưng không có khối features::
components: db: features: root_password: type: core/generated-secretCả hai bản phát hành dùng chung manifest.yaml, tệp ràng buộc cả ba kiểu cho target Terraform, nên Manifest không phải là chỗ hai bản khác nhau:
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.0Chính sách
policy.rego, được gắn trên đồ thị build:
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 liệt kê các lá mà payload của lần gắn này mang có đường dẫn được Feature được gắn khai báo là nhạy cảm, mỗi lá dưới dạng một đường dẫn phân cách bằng dấu chấm có tiền tố trụ cột. Payload được đọc là payload mà lần gắn rốt cuộc mang, nên một lá nằm ở một giá trị mà schema của Feature khai báo là default cũng được nêu tên cùng với một lá do tác giả viết tại đó. Có hai hệ quả, và ví dụ xoay quanh cả hai:
- Một lá chỉ xuất hiện ở nơi có một khai báo bao phủ nó — khai báo nêu tên lá đó, hoặc nêu tên một đối tượng chứa nó, được so khớp theo từng đoạn trên đường dẫn phân cách bằng dấu chấm. Không có gì được đọc từ chính văn bản của đường dẫn và không giá trị nào được kiểm tra. Vì vậy
key, được viết bên cạnhorigintrong cùng lần gắn, không bao giờ xuất hiện: Feature của nó không khai báo gì về nó. - Một lần gắn có payload không mang gì tại một lá đã khai báo thì không đóng góp gì vào danh sách. Lần gắn của release ủy quyền mang câu trả lời cho toàn bộ lần gắn và hoàn toàn không có danh sách theo từng lá, vì khóa bị lược khỏi dữ liệu truyền đi khi nó rỗng.
Lần gắn nằm trong .aggrega-config.yaml ở vai trò ir-verdict, là vai trò nhận đồ thị build:
plugins: governance: - uri: governance/rego:0.9.0 role: ir-verdict with: sources: - policy.regoMột vai trò phán quyết chỉ trả về chấp nhận hoặc từ chối và không gì khác. Nó có thể dừng lần build này; nó không thể viết lại Aggregate cho tuân thủ, vì đường thực thi phát đi một phán quyết không có cách nào áp dụng phán quyết đó như một thay đổi. Một Release muốn có dạng ủy quyền thì có được nó bằng cách gắn Feature ủy quyền — không bao giờ bằng việc một chính sách âm thầm thay thế.
Build cả hai
aggrega build --release release-negative-authored.yaml --auto-pull # expected to failaggrega build --release release-delegated.yaml --auto-pull--auto-pull điền lockfile trong quá trình build; chạy aggrega pull --release release-<arm>.yaml một lần trước đó cũng làm điều tương tự và cho phép các lần build sau chạy
mà không cần cờ. Đầu ra được render và các lockfile là được sinh ra, không được phát hành kèm:
ví dụ này commit các đầu vào của nó và sinh lại mọi thứ còn lại.
Kết quả trả về
Release do tác giả viết bị từ chối và bản build thoát với mã 1. E0005 là
chẩn đoán mà một lần từ chối của policy mang theo — xem
tài liệu tham khảo chẩn đoán:
[… 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 violationHãy đọc đường dẫn leaf. Payload của attachment mang hai giá trị; lời từ chối
nêu tên values.origin và không nhắc đến values.key. Chỉ một câu đó là
việc đánh dấu theo từng leaf đang làm đúng nhiệm vụ — một attachment, hai leaf của payload, một
khai báo, một lần từ chối.
Lời từ chối cũng đến trước khi bất cứ thứ gì được render. Thư mục dist/infra-authored/
hoàn toàn không được tạo ra, nên không có cây artifact dở dang nào phải dọn dẹp
và không có gì trên đĩa mà một bước sau có thể nhầm là output.
Release ủy quyền build thành công, thoát với mã 0 và ghi ra hai tệp.
dist/infra-delegated/terraform/aggrega.modules.tf, cấu hình gốc
của ranh giới:
# 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"}và dist/infra-delegated/terraform/modules/db/main.tf, tệp mở đầu bằng một
khối chú thích # xác định bản build, rồi chứa ràng buộc provider AWS,
resource và output địa chỉ mà Recipe công bố:
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 là dạng ủy quyền xuất hiện trong output: engine giữ thông tin xác thực, và Release không nêu tên dữ liệu bí mật nào ở bất cứ đâu. Release được cho phép đã render một artifact thực sự chứ không phải vượt qua nhờ không render gì cả.
Đối chứng: thay vào đó đặt câu hỏi ở mức toàn bộ attachment
Hoán đổi nguồn được gắn trong .aggrega-config.yaml:
sources: - policy-attachment-wide.regopolicy-attachment-wide.rego là cùng một phép duyệt nhưng dựa trên attachment.sensitive
— một giá trị boolean cho toàn bộ attachment — thay vì dựa trên danh sách theo từng leaf:
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])}Build lại cả hai release — và đặt lại policy.rego sau đó, vì phần còn lại của
trang này giả định có nó. Giờ cả hai đều bị từ chối, với cùng một câu:
[… 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Đó không phải là quy tắc hoạt động sai — mà là quy tắc được hỏi một câu hỏi thô hơn
và trả lời nó một cách chính xác. sensitive đọc những gì các thực thể khai báo: ở đây nó
là true vì slot khai báo rằng bất cứ thứ gì gắn vào nó đều xử lý dữ liệu bí mật,
và slot nói vậy bất kể ai lấp đầy nó. Attachment được ủy quyền
không tự viết gì nhưng vẫn là sensitive, nên một quy tắc dựa trên câu trả lời đó hoàn toàn không thể
phân biệt hai release. Release được ủy quyền là một bản build mà quy tắc theo từng leaf
cho phép còn quy tắc ở mức toàn bộ attachment không có cách nào cho phép.
Sự kiện độ nhạy cảm thứ ba, sensitive_inject, cũng không giúp được gì: nó nêu tên
các khóa phân phối có khóa provides được tham chiếu được khai báo là nhạy cảm. Ở đây
slot đóng về phân phối và Feature do tác giả cung cấp không công bố trụ cột
provides nào, nên trên workspace này nó không nêu tên gì cả. Trong ba sự kiện,
chỉ danh sách theo từng leaf trả lời được “payload của attachment này mang dữ liệu ở đâu”,
đó chính là điều mà quy tắc nội bộ quan tâm.
Để xem cả ba sự kiện cạnh nhau, cùng với dạng payload và các trường hợp mà mỗi sự kiện là câu hỏi đúng, xem các sự kiện về attachment mà một chính sách quản trị đọc. Về bản thân socket — các vai trò, mức độ nghiêm trọng của phán quyết, kênh đầu vào của người vận hành — xem socket chính sách, và về vị trí của chính sách trong sản phẩm, Quản trị và Tuân thủ.
Mục tiêu này làm lộ ra điều gì về dạng do tác giả viết
Recipe cơ sở dữ liệu được quản lý đặt chỉ thị mật khẩu được quản lý riêng của engine một cách vô điều kiện và không đọc thông tin xác thực nào được tiêm vào, nên trên mục tiêu này, nó dừng bản build ngay tại chính phần đính kèm do tác giả viết, nêu tên slot, thay vì chấp nhận dữ liệu không có chỗ nào để đưa vào. Chính sách từ chối nó trước, ở nơi nó thực sự nằm: trong một tệp mà workspace giữ dưới hệ thống quản lý phiên bản. Đó là mối quan tâm về quản trị, và đó là một vấn đề tách biệt với những gì bất kỳ Recipe nào lẽ ra đã render.
Đó cũng là lý do vì sao hai Features là ngang hàng chứ không phải các lựa chọn thay thế có vị thế ngang nhau trên mọi mục tiêu. Hãy bind Feature do tác giả cung cấp ở nơi bạn thực sự nắm giữ thông tin xác thực, và Feature do engine quản lý ở nơi mục tiêu sở hữu nó. Release do tác giả viết trong ví dụ này chính là sự không khớp mà một quy tắc nội bộ có thể phát hiện một cách máy móc.
Plugin đến từ đâu
Mọi thực thể mà workspace này sử dụng đều đến từ catalog thư viện chuẩn đã được công bố: Component, hai Features, Recipe, hai FeatureRecipes và thực thể Plugin quản trị — được đọc từ registry hub mà .aggrega-config.yaml nêu tên, hoặc từ một bản checkout của catalog (lấy ở đâu) được chỉ định bằng --catalog.
uri: governance/rego:0.9.0 gọi tên thực thể Plugin đó. Đó là một định danh: một tọa độ <pluginType>/<name> cộng với một phiên bản, và cả hai nửa đều là một phần của dạng thức. Phiên bản là phiên bản mà plugin được công bố — hub công bố nó dưới dạng oci://hub.aggrega.ai/plugin/governance/rego:0.9.0. Phiên bản tham gia vào quá trình phân giải: một attachment gọi tên một phiên bản mà không thư mục catalog nào, không registry nào và cả chính binary aggrega cũng không chứa sẽ làm dừng bản build. Binary chỉ chứa thực thể của engine ở phiên bản thuộc bản phát hành của chính nó.
Khi được build với --catalog chỉ tới một bản checkout của catalog, ví dụ này không cần gì khác: với binary aggrega của bản phát hành mà attachment nêu, vốn tự chứa thực thể Plugin, mọi thực thể được phân giải mà không cần mạng, và engine chạy là engine được biên dịch vào binary aggrega. Khi không có nó, các thực thể được đọc từ hub.aggrega.ai.
Engine Rego được biên dịch vào binary của CLI, và phiên bản của nó là bản phát hành trình biên dịch đi kèm nó. Một trình biên dịch của bản phát hành khác đọc thực thể Plugin mà attachment nêu từ hub và chạy engine được biên dịch vào chính nó: phiên bản trong attachment định danh thực thể, chứ không chọn engine.
Các tệp
aggregate-authored.yaml— slotroot_passwordđược gắn bằngcore/secret-valuetrong Aggregate, với khóa phân phối và tài liệu bí mật do tác giả viết.aggregate-delegated.yaml— cùng cơ sở dữ liệu đó nhưng không có attachment nào: nhà phát triển không gắn gì cả.manifest.yaml— gắn kiểu component và cả hai kiểu Feature với các Recipes Terraform tương ứng. Được dùng chung cho cả hai release.release-negative-authored.yaml,release-delegated.yaml— mỗi nhánh một tệp, mỗi tệp códirectory:ranh giới riêng. Không có flag nào cho vị trí đầu ra, nên nếu hai release dùng chung một thư mục thì release thứ hai sẽ ghi đè release thứ nhất.release-delegated.yamlcũng gắn slot, trên mục của nó chodb, bằngcore/generated-secret, không viết gì cả. Feature nào lấp slot, và trong tài liệu nào, là khác biệt duy nhất giữa hai nhánh.policy.rego— quy định nội bộ, dựa trên việc đánh dấu theo từng leaf.policy-attachment-wide.rego— phương án đối chứng, dựa trên câu trả lời cho toàn bộ attachment. Không được gắn theo mặc định..aggrega-config.yaml— registry mặc định và attachment governance.
Tạo ví dụ
Bạn có thể build ví dụ này bằng các lệnh bên dưới, hoặc để trợ lý AI của bạn build giúp bạn.
Ghi ví dụ vào một thư mục mới đặt theo tên của nó:
aggrega scaffold --example policy-payload-leaf-sensitivitySau đó nó in ra các lệnh cần chạy tiếp theo. Lệnh đầu tiên chuyển vào thư mục mới:
cd policy-payload-leaf-sensitivityBuild
aggrega build --release release-negative-authored.yaml --auto-pull # refused; exits 1aggrega build --release release-delegated.yaml --auto-pull # buildsVới trợ lý AI
Một trợ lý AI được thiết lập với các công cụ của Aggrega cũng có thể làm như vậy: hãy dán prompt này vào trợ lý.
Chỉ dùng các công cụ của Aggrega và không tự tạo thư mục nào. Nếu thư mục Workspace chưa có thư mục `policy-payload-leaf-sensitivity`, hãy gọi công cụ `scaffold` một lần với `example` đặt thành `policy-payload-leaf-sensitivity` và không có `dir`: công cụ này ghi ví dụ vào một thư mục `policy-payload-leaf-sensitivity` mới. Sau đó gọi công cụ `build` với `workspace_root` đặt thành `policy-payload-leaf-sensitivity`, `release` đặt thành `release-negative-authored.yaml`, `auto_pull` đặt thành true và `write` đặt thành true: bản dựng này được dự định là sẽ bị từ chối, vì vậy hãy đọc cho tôi lời từ chối. Tiếp theo gọi công cụ `build` theo cùng cách với `release` đặt thành `release-delegated.yaml`. Cho tôi biết bản dựng thứ hai đó đã ghi những tệp nào; chúng nằm trong `policy-payload-leaf-sensitivity/dist/`.