Políticas de acesso como código
Cerca de 38 minutos min de leitura, com 13 exemplos em 11 seções.
Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros
Traduzido do livro em inglês, edição 2026.11.31. Leia o original
Nesta página
- Modele a requisição como a do Trino
- Gere os dados que a política lê
- Negue por padrão, depois permita por papel
- Filtre por atributo: região, consentimento e finalidade
- Retorne a decisão como um único documento
- Teste a política em Rego
- Verifique quem vê o quê a partir de uma tabela de decisão
- Saiba onde o regopy difere do OPA
- Escreva as mesmas regras em Cedar
- O que dá errado em produção
- O que este capítulo decidiu
Ao final deste capítulo, você saberá escrever as regras de acesso de uma plataforma de dados como uma única política que nega por padrão e devolve filtros de linha e máscaras de coluna como dados. A política permite por papel e restringe por atributo, e um motor pode aplicar a decisão inteira. Você a escreverá em Rego, a linguagem de políticas do Open Policy Agent (OPA), vai testá-la da forma como opa test, o executor de testes do OPA, faz, vai conferi-la contra uma tabela de quem vê o quê que os proprietários dos dados podem ler, vai saber em que pontos o motor em processo usado neste livro difere do OPA, e verá as mesmas regras em Cedar, uma linguagem de políticas mais restrita.
Cada grupo que lê o armazém de dados da plataforma, dos agentes de suporte ao assistente de cursos, precisa de algo diferente. Os agentes de suporte atendem cada um uma região, americas, emea ou apac, e precisam dos dados de contato dos alunos para responder aos chamados. Os instrutores veem os alunos e as avaliações dos próprios cursos, sem os dados de contato. O marketing pode alcançar apenas alunos que concordaram em receber e-mails de marketing. As finanças conciliam pagamentos, e a coluna legada card_number de billing.payments nunca pode mostrar mais do que os últimos quatro dígitos. Os cientistas de dados veem learner_id como armazenado, para unir tabelas por ele, com as colunas pessoais pseudonimizadas e o texto livre ocultado (redigido). O assistente de curso lê apenas as avaliações cujos autores concordaram com o treinamento de IA. O capítulo 1 mostrou uma regra, os agentes de suporte veem apenas a própria região, e a aplicou em uma consulta. As regras de cada grupo precisam estar em um só lugar, declaradas com exatidão, e testadas antes que alguém dependa delas.
Os termos deste capítulo são os que o restante do livro usa. Uma política é código que responde se uma requisição pode prosseguir. Uma decisão é a resposta de uma política. O principal é quem pede, um papel é um grupo de principais com a mesma função, e um atributo é qualquer outro fato que uma regra lê, sobre o principal, os dados ou a requisição. Um filtro de linha limita quais linhas uma consulta retorna, e uma máscara de coluna altera a forma como os valores de uma coluna são exibidos, como a pseudonimização, que substitui um identificador por um substituto consistente.
A política da plataforma está em governance/policies/access.rego, e seus testes estão em governance/policies/access_test.rego. O módulo compartilhado do livro, lib.policy, carrega ambos no regopy 1.5.2, a ligação em Python do rego-cpp, a implementação em C++ do Rego feita pela Microsoft, que avalia as políticas dentro do processo Python, sem nenhum servidor para executar.
Modele a requisição como a do Trino
Um motor de políticas responde a perguntas sobre requisições, portanto o formato de uma requisição decide quais sistemas podem fazer essas perguntas. A premissa do OPA é retirar a política do serviço que a aplica: o OPA "permite desacoplar a política desse serviço de software", de modo que ela possa ser lida, versionada e testada por conta própria (filosofia do OPA). O serviço envia um documento JSON que descreve a requisição, e a política o lê como input. O Trino, um motor SQL de código aberto, faz exatamente isso: para cada verificação de acesso que uma consulta exige, seu plugin OPA envia um documento com context.identity, o usuário e seus grupos, e action, a operação e o recurso, até o catálogo, o esquema, a tabela e as colunas (Trino 484, controle de acesso OPA).
A política da plataforma lê os mesmos campos, portanto decide a requisição do Trino para ler colunas, SelectFromColumns, da forma como o Trino a envia. O Trino precisa de mais do que essa decisão. Ele quer cada filtro de linhas e máscara de coluna como SQL, sendo o filtro de linhas no formato {"expression": "clause"}, em que a política devolve uma coluna e um valor (Trino 484, controle de acesso OPA). Ele também pergunta sobre outras verificações, como ExecuteQuery e AccessCatalog, que a regra allow desta política nega (OpaAccessControl.java no Trino 484). O Capítulo 6 mostra o que um módulo ao lado da política precisa devolver para elas. lib.policy.request monta as requisições da plataforma no formato do Trino, e o próximo exemplo o usa para um agente de suporte emea, agent-a05, que lê três colunas de support.tickets:
1"""The request a support agent's read sends the policy, shaped as Trino's OPA plugin sends it. The point rests on the printed `action`: the operation SelectFromColumns, and the table with the columns the query reads."""2import json34from lib import policy56# A support agent's query reads three columns of the tickets table: the request Trino's OPA plugin would send for it.7# no groups here, because the policy reads them from users.toml; no purpose either, since request adds one only when given8request = policy.request("agent-a05", "support.tickets", ["ticket_id", "opened_at", "body"])9print(json.dumps(request, indent=2))
python trino-shaped-request.py{
"context": {
"identity": {
"user": "agent-a05"
}
},
"action": {
"operation": "SelectFromColumns",
"resource": {
"table": {
"catalogName": "platform",
"schemaName": "support",
"tableName": "tickets",
"columns": [
"ticket_id",
"opened_at",
"body"
]
}
}
}
}
A operação é SelectFromColumns, o nome que o Trino dá a uma leitura, e a tabela fica sob action.resource.table, com seu catálogo, esquema, nome e as colunas que a consulta acessa. A requisição da plataforma difere da do Trino em dois pontos que importam. Ela omite context.identity.groups, porque a política busca os grupos de um usuário no mesmo arquivo que os seus atributos, governance/users.toml, de modo que os testes e a política leem uma única fonte de verdade. E ela pode trazer um campo purpose no nível superior, como ai-training, que o Trino não envia. Atrás do Trino, recomendamos derivar a finalidade da identidade, por exemplo dando ao pipeline de treinamento um usuário de serviço próprio, em vez de confiar em um valor que o cliente define.
Regra prática: Modele a entrada da política como as requisições do motor que vai aplicá-la, campo por campo, e acrescente apenas o que esse motor não consegue enviar, no nível superior, onde um revisor a enxerga. Se o seu motor não for o Trino, comece pelo formato de requisição dele e mantenha o formato em uma única função, como faz lib.policy.request, para que testes e chamadores não possam se desalinhar.
Gere os dados que a política lê
A requisição informa quem pede o quê. Tudo o mais de que uma regra precisa além da requisição, como os grupos de cada usuário e a classificação de cada coluna, vem de um segundo documento, que a OPA chama de data. Um fato nesse documento é tão atual quanto a sua fonte, e cada fato que a política da plataforma lê já tem um dono. Usuários e seus atributos ficam em governance/users.toml. A classificação de cada coluna fica em governance/metadata.toml, o arquivo de metadados revisado que o capítulo 2 indexa pelo ID de campo do Iceberg. E qual instrutor leciona qual curso está na própria tabela learning.courses. Digitar qualquer um desses dados na política, ou copiá-los para um segundo arquivo, cria uma cópia que alguém precisa lembrar de atualizar.
lib.policy.data_document constrói o documento a partir dessas três fontes sempre que uma política é carregada, e nunca a partir de algo digitado:
1"""The data the policy reads besides the request, built from the files that own each fact. The point rests on the last two lines: instructor 17's courses come from learning.courses, not from anything typed."""2from lib import policy34# What the policy reads besides the request, built from the files that own each fact.5# the document's one top-level key, which the policy reads as data.platform6data = policy.data_document()["platform"]78print("users, from governance/users.toml:", len(data["users"]))9print("agent-a05:", data["users"]["agent-a05"])10print("instructor-17:", data["users"]["instructor-17"])1112classifications = data["classifications"]13print("tables, from governance/metadata.toml:", len(classifications))14print("columns classified:", sum(len(columns) for columns in classifications.values()))15print("crm.learners.email:", classifications["crm.learners"]["email"])16print("billing.payments.card_number:", classifications["billing.payments"]["card_number"])1718courses = data["instructor_courses"]19print("instructors with courses, from learning.courses:", len(courses))20# instructor IDs are string keys in the document, so the lookup is "17"21print("instructor 17's courses:", courses["17"])
python generated-policy-data.pyusers, from governance/users.toml: 8
agent-a05: {'groups': ['support'], 'region': 'emea'}
instructor-17: {'groups': ['instructor'], 'instructor_id': 17}
tables, from governance/metadata.toml: 10
columns classified: 77
crm.learners.email: personal
billing.payments.card_number: sensitive
instructors with courses, from learning.courses: 48
instructor 17's courses: [2, 75, 80, 87, 103, 134]
Cada fato no documento vem do arquivo ou tabela que o possui, e a saída rotula cada contagem com a sua fonte: os usuários em governance/users.toml, as colunas classificadas nas tabelas de governance/metadata.toml e os instrutores em learning.courses. agent-a05 tem um grupo e uma região, e instructor-17 um grupo e um ID de instrutor, mas nada em users.toml diz quais cursos o instrutor 17 leciona. O documento encontra [2, 75, 80, 87, 103, 134] em learning.courses. Quando a plataforma publica mais um dos cursos deles, o filtro de linhas do instrutor passa a incluí-lo na próxima vez que os dados da política forem gerados, sem nenhuma edição em lugar algum. Uma classificação funciona da mesma forma: mudar card_number de sensitive exigiria uma única alteração revisada em metadata.toml, e a política acompanharia.
Regra prática: Gere os dados da política a partir do arquivo ou tabela que possui cada fato, toda vez que você carregar a política, e nunca copie um fato para dentro da política nem para um segundo arquivo. Quando um fato ainda não tem dono, como a região de um agente de suporte, dê a ele um único arquivo, revisado como código, como a plataforma faz com users.toml.
Negue por padrão, depois permita por papel
Com a requisição e os seus dados definidos, a primeira coisa que uma política precisa resolver é o que acontece com uma requisição que nenhuma regra previu. O princípio de padrões à prova de falhas de Saltzer e Schroeder é "Basear as decisões de acesso em permissão, e não em exclusão" (Saltzer and Schroeder, 1975). Em Rego, isso é um valor padrão. Uma regra cujo corpo nunca é avaliado como verdadeiro não tem valor, o que Rego chama de indefinido, e o OPA usa o padrão quando todas as regras que compartilham um nome estão indefinidas (OPA policy language). Com default allow := false, uma requisição que nenhuma regra de allow atende é negada, seja quem for que a envie e seja o que for que peça.
O controle de acesso baseado em papéis, formalizado pela primeira vez por Ferraiolo e Kuhn em 1992, concede acesso pela função que um principal exerce, e não por quem ele é. Na plataforma, um papel é um grupo em users.toml, e o objeto readable da política associa cada grupo às tabelas que ele pode ler. Uma requisição é permitida quando é uma leitura, algum grupo do usuário pode ler a tabela e nada de que os filtros de linha do grupo dependem está ausente:
default allow := false
allow if {
input.action.operation == "SelectFromColumns"
readable_by_a_group
not missing_attribute
}
A última linha protege contra uma falha que a seção sobre produção mostra ao removê-la. Imprima o mapa e decida quatro requisições para ver o padrão em ação:
1"""Which groups may read which tables, then four requests decided by the default-deny policy. The points rest on the four decisions and their reasons, printed last."""2from lib import policy34rego = policy.interpreter()56# The groups the policy knows, and the tables each may read: the role part of the policy.7readable = policy.evaluate(rego, "data.platform.access.readable", {})8for group, tables in readable.items():9 print(f"{group} may read:", ", ".join(tables))1011# Who may read what. Anything no rule allows is denied, including a user or an operation the policy has never seen.12requests = [13 policy.request("finance-1", "billing.payments", ["amount"]),14 policy.request("marketing-1", "billing.payments", ["amount"]),15 policy.request("someone-else", "crm.learners", ["learner_id"]),16]17delete = policy.request("finance-1", "billing.payments", ["amount"])18# the same request as finance's read, asking to delete instead19delete["action"]["operation"] = "DeleteFromTable"20for request in requests + [delete]:21 decision = policy.decide(request, rego)22 who, table = request["context"]["identity"]["user"], request["action"]["resource"]["table"]23 print(f"{who}, {request['action']['operation']} on {table['schemaName']}.{table['tableName']}:",24 "allowed" if decision["allow"] else "denied", "|", "; ".join(decision["reasons"]))
python allow-by-role.pyai may read: learning.courses, learning.reviews
data-science may read: analytics.course_performance, analytics.learner_activity, billing.payments, crm.learners, learning.courses, learning.enrollments, learning.events, learning.reviews
finance may read: billing.payments, learning.courses, learning.enrollments
instructor may read: learning.courses, learning.enrollments, learning.reviews
marketing may read: crm.learners, learning.courses, marketing.audience
support may read: crm.learners, support.tickets
finance-1, SelectFromColumns on billing.payments: allowed | finance may read billing.payments
marketing-1, SelectFromColumns on billing.payments: denied | no group of this user may read this table
someone-else, SelectFromColumns on crm.learners: denied | no group of this user may read this table
finance-1, DeleteFromTable on billing.payments: denied | DeleteFromTable is not an operation this policy allows
Somente o que uma regra concede é permitido. Finanças pode ler billing.payments, e o motivo nomeia o grupo que permitiu. Marketing não pode, e tampouco someone-else, um usuário que a política nunca conheceu, porque nada concede acesso a nenhum dos dois. A quarta requisição é de finanças novamente, pedindo para excluir em vez de ler. Nenhuma regra menciona DeleteFromTable, então ela também é negada, e o motivo explica por quê. Uma política que tentasse listar o que é proibido precisaria de uma regra para essa operação; esta não precisa de nenhuma. Cada decisão carrega os seus motivos, de modo que uma negação pode ser explicada à pessoa que a recebeu e registrada em log.
Regra prática: Comece toda política com default allow := false, e permita apenas por meio de regras que nomeiem o papel e o recurso. Mantenha o mapa de papéis para tabelas em um único lugar, onde um revisor possa lê-lo por inteiro de uma vez, e dê a cada decisão um motivo. Quando uma requisição for negada e deveria ter sido permitida, adicione uma regra que a permita; nunca enfraqueça o padrão.
Filtre por atributo: região, consentimento e finalidade
Papéis dizem quais tabelas um grupo pode ler; eles não conseguem dizer quais linhas. O guia do NIST sobre controle de acesso baseado em atributos define a abordagem geral, na qual o acesso é decidido por atributos do sujeito, do objeto, das operações solicitadas e, às vezes, do ambiente. Ele trata um papel como um desses atributos (NIST SP 800-162). A alternativa, um papel para cada combinação, é o que o guia do NIST chama de "explosão de papéis".
A plataforma mostra por quê. O suporte por região exigiria três papéis de suporte, e somar o consentimento do marketing e uma finalidade para treinamento de IA multiplicaria os papéis de novo. Em vez disso, a política mantém um papel por função e lê três atributos. A região é um atributo do principal, vindo de users.toml. O consentimento é um atributo dos dados: as colunas marketing_consent e ai_training_consent em crm.learners. A finalidade é um atributo da requisição. Cada um deles se torna um filtro de linhas, uma condição estruturada sobre uma coluna que o motor acrescenta à consulta. O filtro do agente de suporte lê a região do agente:
row_filters contains {"column": "support_region", "equals": user.region} if {
"support" in groups
table in {"crm.learners", "support.tickets"}
}
Leituras feitas por agentes de suporte, um instrutor, o marketing e um cientista de dados mostram o que cada atributo faz, sendo que o cientista de dados lê avaliações duas vezes, uma sem finalidade e outra para ai-training:
1"""Row filters the policy builds for seven reads, from three attributes: the agent's region, the learner's consent and the request's purpose. The points rest on the analyst's two review reads, with and without a purpose."""2import json34from lib import policy56rego = policy.interpreter()78# Region is the agent's attribute, consent the learner's, and purpose the request's. Each becomes a row filter.9reads = [10 ("agent-a01", "support.tickets", ["ticket_id"], None),11 ("agent-a05", "support.tickets", ["ticket_id"], None),12 ("agent-a09", "support.tickets", ["ticket_id"], None),13 ("instructor-17", "learning.reviews", ["rating"], None),14 ("marketing-1", "crm.learners", ["email"], None),15 ("analyst-1", "learning.reviews", ["rating", "body"], None),16 # the same read with a purpose, the one attribute the requester supplies17 ("analyst-1", "learning.reviews", ["rating", "body"], "ai-training"),18]19for user, table, columns, purpose in reads:20 decision = policy.decide(policy.request(user, table, columns, purpose), rego)21 who = user + (f" for {purpose}" if purpose else "")22 # json shows the consent filter with its learner_consented key, not a column23 print(f"{who} reads {table}, row filters:", json.dumps(decision["row_filters"]))24 if "body" in columns:25 print(f"{who} reads {table}, body shown as:", decision["column_masks"]["body"])
python attributes-as-row-filters.pyagent-a01 reads support.tickets, row filters: [{"column": "support_region", "equals": "americas"}]
agent-a05 reads support.tickets, row filters: [{"column": "support_region", "equals": "emea"}]
agent-a09 reads support.tickets, row filters: [{"column": "support_region", "equals": "apac"}]
instructor-17 reads learning.reviews, row filters: [{"column": "course_id", "in": [2, 75, 80, 87, 103, 134]}]
marketing-1 reads crm.learners, row filters: [{"column": "marketing_consent", "equals": true}, {"column": "status", "equals": "active"}]
analyst-1 reads learning.reviews, row filters: []
analyst-1 reads learning.reviews, body shown as: redact
analyst-1 for ai-training reads learning.reviews, row filters: [{"learner_consented": "ai_training_consent"}]
analyst-1 for ai-training reads learning.reviews, body shown as: redact_contacts
A finalidade é o que muda a visão de um cientista de dados sobre o texto das avaliações. Sem ela, toda avaliação é visível, mas o texto, body, aparece como redact. Para ai-training, permanecem apenas as avaliações de alunos que concordaram com o treinamento de IA, e o texto volta como redact_contacts, com os dados de contato removidos. Os três agentes recebem a mesma regra com um valor por região, a partir de um único papel, e o filtro do instrutor 17 lista os cursos dele, gerados a partir de learning.courses. O marketing recebe dois filtros, consentimento concedido e conta ativa, e o motor aplica os dois. O filtro de treinamento de IA, learner_consented, testa o autor da avaliação, não a avaliação, de modo que aplicá-lo exige uma junção com crm.learners. Um aluno que se cadastrou antes de a plataforma perguntar sobre treinamento de IA não tem resposta em ai_training_consent, segundo a ficha de dados da plataforma, então a aplicação do filtro precisa tratar uma resposta desconhecida como não.
A finalidade é o único atributo fornecido pelo solicitante, por isso ela só revela mais sob uma condição mais restrita: informar ai-training mostra o texto das avaliações, mas apenas dos alunos que consentiram e sem os dados de contato. Omiti-la, ou informar qualquer outra finalidade, obtém de qualquer modo o que o papel permite, com o texto oculto.
Regra prática: Modele cada condição como um atributo do principal, dos dados ou da requisição, lido por uma regra por papel, em vez de como outro papel. Quando um atributo vier do solicitante, como ocorre com a finalidade, deixe-o liberar o acesso apenas sob uma condição mais restrita, de modo que omiti-lo, ou informá-lo errado, volte ao que o papel já permite.
Retorne a decisão como um único documento
Um sim ou não não consegue carregar os filtros de linha que os atributos produzem. Uma decisão em Rego não precisa ser sim ou não, porque as políticas do OPA podem representar decisões como dados estruturados, de booleanos a mapas de listas de mapas (filosofia do OPA). A política da plataforma usa dados estruturados para devolver toda a sua resposta como um único documento, data.platform.access.decision, com quatro chaves: allow, os row_filters, as column_masks e os reasons. lib.policy.decide pede esse documento com uma única consulta e o devolve como um dicionário Python.
Os filtros e as máscaras são dados, nunca SQL. Um filtro nomeia uma coluna e um valor ou uma lista de valores, ou, no caso do consentimento, a coluna de consentimento do aluno. Uma máscara é um nome, um dentre redact, last4, pseudonymize e redact_contacts. Quem aplica a decisão transforma cada um deles em SQL com o seu próprio código, de modo que nada que uma requisição ou um registro de usuário contenha, como uma região digitada em users.toml, possa chegar a uma consulta como texto SQL. As máscaras seguem a classificação de cada coluna. Colunas sensíveis ficam ocultas para todos, exceto os últimos quatro dígitos de um número de cartão, que o financeiro vê. Colunas pessoais são mostradas ao suporte, que precisa dos dados de contato, e mascaradas para os demais, conforme o trabalho de cada um exige. E uma coluna que os metadados não classificam é considerada sensível:
classification(column) := level if {
level := data.platform.classifications[table][column]
} else := "sensitive"
Tome o marketing lendo quatro colunas de crm.learners, três delas classificadas nos metadados. A quarta, linkedin_url, representa uma coluna que um pipeline acrescentou e que ninguém ainda classificou:
1"""The whole decision for one read: marketing's four columns of crm.learners, one of them unclassified. The point rests on the masks and the reasons, which give one line per mask and per group that allowed the read."""2import json34from lib import policy56# Marketing reads four columns of crm.learners. `linkedin_url` stands for a column added to the table and not yet7# classified in governance/metadata.toml.8request = policy.request("marketing-1", "crm.learners", ["full_name", "email", "phone", "linkedin_url"])9# with no interpreter given, decide loads the platform's policy itself10decision = policy.decide(request)11print(json.dumps(decision, indent=2))12print("keys:", ", ".join(sorted(decision)))
python one-decision-document.py{
"allow": true,
"column_masks": {
"linkedin_url": "redact",
"phone": "redact"
},
"reasons": [
"linkedin_url is sensitive, shown as redact",
"marketing may read crm.learners",
"phone is personal, shown as redact"
],
"row_filters": [
{
"column": "marketing_consent",
"equals": true
},
{
"column": "status",
"equals": "active"
}
]
}
keys: allow, column_masks, reasons, row_filters
O marketing obtém a leitura, com seus dois filtros de linha, e duas das quatro colunas são mascaradas. phone é pessoal, e o marketing não precisa dele para o e-mail. linkedin_url não está classificada, então é tratada como sensível até que alguém a revise. full_name e email não têm máscara, e uma coluna sem máscara é mostrada como armazenada, o que o marketing precisa para enviar um e-mail. As razões trazem uma linha para cada grupo que permitiu a leitura e uma para cada máscara, de modo que o documento se explica por si. Uma negação traz filtros e máscaras vazios, porque a política constrói os dois resultados com duas regras separadas, então nada a jusante pode confundir uma negação com uma leitura com algumas colunas mascaradas.
Regra prática: Retorne um documento de decisão por requisição, contendo a permissão, os filtros de linha, as máscaras de coluna e as razões, e leia-o como um todo. Mantenha filtros e máscaras como nomes e valores que o seu código de aplicação da decisão traduz, nunca como SQL escrito pela política. Se um motor precisar de SQL vindo da política, como o Trino precisa para os seus filtros de linha e máscaras de coluna (Trino 484, controle de acesso com OPA), gere-o em uma única função testada entre os dois.
Teste a política em Rego
O documento de decisão é o que um teste pode comparar, e isso importa porque uma política decide quem vê dados pessoais, e uma mudança nela pode ampliar o acesso sem que ninguém perceba em um diff. A resposta do OPA são testes escritos em Rego: um teste é uma regra cujo nome tem o prefixo test_, e "Se a regra de teste estiver indefinida ou gerar um valor que não seja verdadeiro, o resultado do teste é reportado como FAIL" (teste de políticas do OPA). Um teste monta sua requisição com with, que substitui parte de input ou data para uma única expressão.
O motor do livro, regopy, não tem opa test, então lib.policy.run_tests desempenha esse papel. Ele encontra todas as regras test_ nos arquivos _test.rego da pasta, avalia cada uma e informa PASS quando a regra é verdadeira, FAIL quando é falsa ou indefinida, e ERROR quando a avaliação falha. Cada teste da plataforma define o usuário e a ação como dois caminhos separados, cada um com um valor literal, por motivos que a seção sobre regopy mostra:
test_finance_sees_only_the_last_four_digits if {
decision := access.decision with input.context.identity.user as "finance-1"
with input.action as {"operation": "SelectFromColumns", "resource": {"table": {"schemaName": "billing", "tableName": "payments", "columns": ["amount", "card_number"]}}}
decision.allow
decision.row_filters == []
decision.column_masks == {"card_number": "last4"}
}
Os testes cobrem o allow, os filtros e as máscaras de cada grupo, e as formas de negar uma requisição: uma tabela que o grupo não recebe, uma operação que não seja leitura, um usuário que a política não conhece e um agente de suporte sem região.
1"""Runs every test in the platform's Rego test file and counts the passes. The point rests on the last line, the tests passed out of all of them."""2from collections import Counter34from lib import policy56# Every `test_` rule in governance/policies/access_test.rego, run by name: PASS, FAIL or ERROR, as `opa test` reports.7results = policy.run_tests()8for test, result in results.items():9 print(f"{result}: {test}")10# len(results) counts every test, so one that fails or errors still shows in the total11print("tests passed:", f"{Counter(results.values())['PASS']} of {len(results)}")
python policy-unit-tests.pyPASS: test_support_reads_only_its_own_region
PASS: test_support_without_a_region_is_denied
PASS: test_marketing_sees_only_consenting_active_learners
PASS: test_a_group_only_reads_its_own_tables
PASS: test_finance_sees_only_the_last_four_digits
PASS: test_data_science_never_sees_card_numbers
PASS: test_data_science_sees_pseudonyms_not_people
PASS: test_an_unclassified_column_is_hidden
PASS: test_an_unknown_user_is_denied
PASS: test_an_instructor_sees_only_their_courses
PASS: test_the_assistant_reads_only_consented_reviews
PASS: test_training_reads_only_consented_reviews_without_contacts
tests passed: 12 of 12
Um teste que verifica apenas decision.allow deixaria passar a maioria dos erros, por isso todo teste de leitura permitida compara por completo os filtros de linha e as máscaras de coluna. No teste de finanças, decision.row_filters == [] falha se a política acrescentar qualquer filtro às leituras de finanças, e decision.column_masks == {"card_number": "last4"} falha se ela mascarar uma coluna a mais ou a menos, ou mostrar o número do cartão de outra forma. A execução informa 12 of 12 testes aprovados.
Regra prática: escreva um teste para cada regra que conceda ou restrinja acesso, e um para cada forma de negar uma requisição, e compare filtros e máscaras por completo, não chaves isoladas. Execute os testes a cada mudança na política e nos dados que ela lê.
Verifique quem vê o quê a partir de uma tabela de decisão
Testes unitários são escritos em Rego por quem escreve a política. As pessoas que são donas dos dados, como a liderança de suporte ou a equipe financeira, também devem poder verificar a política, sem precisar ler Rego. Uma tabela de decisão tem uma linha por requisição, dizendo quem lê qual tabela e o que essa pessoa deve receber de volta, nos termos do trabalho dela.
A tabela da plataforma é lib.policy.WHO_SEES_WHAT, uma lista de linhas em Python. Cada linha informa um usuário, uma tabela, as colunas lidas e uma finalidade opcional; depois, se a leitura é permitida, quais colunas os filtros da linha testam e quais colunas são mascaradas, e de que forma. Cada linha passa por lib.policy.decide, que retorna o documento de decisão, e o exemplo imprime uma linha para cada linha da tabela, no formato para mostrar aos donos dos dados:
1"""Each row of the who-sees-what table run through the policy and printed as one line, with the count of rows the policy matches. The point rests on the last line, the count of rows whose decision matches the outcome its row expects."""2from lib import policy34rego = policy.interpreter()56# Each row of lib.policy.WHO_SEES_WHAT is a request and the decision a reviewer expects for it.7matching = 08for case in policy.WHO_SEES_WHAT:9 decision = policy.decide(policy.request(case.user, case.table, case.columns, case.purpose), rego)10 # matches returns True or False, which add as 1 or 011 matching += policy.matches(case, decision)12 who = case.user + (f" ({case.purpose})" if case.purpose else "")13 shown = "allowed" if decision["allow"] else "denied"14 # a consent filter has no column key, so filtered_on reads its learner_consented key15 filters = ", ".join(policy.filtered_on(decision)) or "-"16 masks = ", ".join(f"{column}: {mask}" for column, mask in decision["column_masks"].items()) or "-"17 print(f"{who:26} {case.table:17} {shown:8} rows: {filters:29} masks: {masks}")18print("rows of the table the policy matches:", f"{matching} of {len(policy.WHO_SEES_WHAT)}")
python who-sees-what.pyagent-a05 crm.learners allowed rows: support_region masks: -
agent-a05 billing.payments denied rows: - masks: -
instructor-17 learning.reviews allowed rows: course_id masks: body: redact_contacts
instructor-17 crm.learners denied rows: - masks: -
marketing-1 crm.learners allowed rows: marketing_consent, status masks: phone: redact
finance-1 billing.payments allowed rows: - masks: card_number: last4
analyst-1 billing.payments allowed rows: - masks: card_number: redact
analyst-1 crm.learners allowed rows: - masks: email: pseudonymize, notes: redact
analyst-1 learning.reviews allowed rows: - masks: body: redact
analyst-1 (ai-training) learning.reviews allowed rows: ai_training_consent masks: body: redact_contacts
assistant-1 learning.reviews allowed rows: ai_training_consent masks: body: redact_contacts
someone-else crm.learners denied rows: - masks: -
rows of the table the policy matches: 12 of 12
Lendo a tabela de cima a baixo, as regras de cada papel aparecem como resultados. A política corresponde a 12 of 12 linhas: o agente de suporte filtrado por região e sem acesso a pagamentos; o instrutor filtrado por curso e sem acesso à tabela de alunos; a equipe financeira vendo card_number como last4, enquanto o cientista de dados vê redact; e as duas leituras de avaliações feitas pelo cientista de dados, uma com finalidade e outra sem. Um revisor que achar que uma linha está errada pode dizer isso em um pull request sem saber qual regra a produziu.
Regra prática: mantenha uma tabela de quem vê o quê no repositório, junto com a política, execute-a com os testes unitários e mostre sua forma impressa aos donos dos dados, em termos que eles consigam conferir. Quando um dono discordar de uma linha, altere primeiro a linha, e deixe que a linha que falha guie a mudança na política.
Saiba onde o regopy difere do OPA
Os testes da plataforma rodam no regopy porque os exemplos do livro precisam funcionar offline, em segundos, dentro do Python, e o OPA é um programa separado. O regopy 1.5.2 é parecido com o OPA. Seu motor afirma que oferece suporte ao Rego v1.18.1 conforme o OPA o define, e que passa em todas as suítes de teste não relacionadas a built-ins que o OPA publica. O README dele lista os built-ins que ele não suporta, como net.* e http.send (README do rego-cpp na v1.5.2), mas o regopy também difere do OPA de maneiras que esse README não lista. A política e os testes da plataforma evitam cada um dos casos a seguir, e o próprio OPA é a referência para qualquer coisa em produção.
O primeiro grupo roda sem nenhum erro:
1"""Small policies that regopy answers differently from OPA, each printed with the answer regopy gives. The prose's points rest on the printed values, and the bound and literal-mock lines are the controls where regopy agrees with OPA."""2import json34from regopy import Input, Interpreter567def ask(rules: str, query: str, request: dict) -> str:8 """One query's answer from regopy: the value bound to x, or "undefined"."""9 rego = Interpreter()10 rego.add_module("example", "package example\n" + rules)11 rego.set_input(Input(request))12 output = str(rego.query(query))13 # regopy writes undefined as a bare word; otherwise the binding for x is the answer14 return output if output == "undefined" else json.dumps(json.loads(output)["bindings"]["x"])151617admins_only = 'default allow := false\nallow if input.user == "admin"\n'18# no variable in the query19print("a false decision, queried on its own:", ask(admins_only, "data.example.allow", {"user": "guest"}))20# bound to x, the same false decision comes back as a value21print("the same decision, bound to a variable:", ask(admins_only, "x := data.example.allow", {"user": "guest"}))2223pre_1_0 = 'allow { input.user == "admin" }\n' # no `if`: OPA 1.x refuses to load this24print("a rule in pre-1.0 syntax:", ask(pre_1_0, "x := data.example.allow", {"user": "admin"}))2526# regoin is never defined, so deny is undefined and not deny is true for any request27typo = 'region := "emea"\ndefault allow := false\nallow if not deny\ndeny if input.region != regoin\n'28print("a deny with a misspelt, unbound variable, for apac:", ask(typo, "x := data.example.allow", {"region": "apac"}))2930mocks = """region := input.user.region31emea := {"region": "emea"}32with_a_literal := seen if { seen := region with input.user as {"region": "emea"} }33with_a_reference := seen if { seen := region with input.user as emea }34"""35print("region under a mock written as a literal:", ask(mocks, "x := data.example.with_a_literal", {"user": {"region": "apac"}}))36# the mock refers to the rule emea, which regopy ignores, so the real input's region comes back37print("region under a mock that refers to a rule:", ask(mocks, "x := data.example.with_a_reference", {"user": {"region": "apac"}}))
python regopy-silent-differences.pya false decision, queried on its own: undefined
the same decision, bound to a variable: false
a rule in pre-1.0 syntax: true
a deny with a misspelt, unbound variable, for apac: true
region under a mock written as a literal: "emea"
region under a mock that refers to a rule: "apac"
- Uma decisão falsa volta como indefinida. Ao pedir
data.example.allowsozinho, o regopy respondeundefinedonde o valor éfalse, então "negado" não pode ser distinguido de "nenhuma decisão". Vinculada a uma variável, a mesma consulta dáfalse.lib.policyvincula cada decisão que lê. - Sintaxe pré-1.0 é executada. Desde o OPA 1.0,
ifé obrigatório em toda regra econtainspara regras de múltiplos valores (notas de versão do OPA v1.0.0), e o changelog do rego-cpp registra que ele deixou de dar suporte ao Rego v0 (changelog do rego-cpp). Ainda assim, o regopy avaliaallow { ... }e respondetrue, então uma política pode passar aqui e falhar ao carregar no OPA, e também atrás do Trino. - Uma variável não vinculada desliga uma regra. O OPA exige que uma variável em uma comparação seja vinculada por outra expressão na mesma regra, e rejeita a política caso contrário (linguagem de política do OPA). O regopy a executa mesmo assim. Uma
denycomregoinescrito errado no lugar deregionfica silenciosamente indefinida, entãoallow if not denypermite uma requisição deapac, como mostratrue. - Um mock que se refere a outra regra é ignorado. Em uma política cuja regra
regionlêinput.user.region, um mock escrito como literal,with input.user as {"region": "emea"}, dá"emea". Escrito como uma referência a uma regra que contém o mesmo objeto, dá o"apac"da entrada real.
O segundo grupo falha, e uma falha basta para derrubar o Python. Um caso acrescenta um teste a uma cópia dos testes da plataforma; o outro formata a mesma string a partir de nove fontes:
1"""One test that replaces the whole input, and what that does to the interpreter: every query fails, and printing a failed output ends Python. The points rest on the printed error count, the assert that true does not succeed, and the signal the crash ends with."""2import signal3import subprocess4import sys5import tempfile6from collections import Counter7from pathlib import Path89from lib import policy1011# The platform's tests, plus one that replaces the whole input at once rather than one path at a time.12whole_input = """13test_finance_reads_payments if {14 access.decision.allow with input as {"context": {"identity": {"user": "finance-1"}}, "action": {"operation": "SelectFromColumns", "resource": {"table": {"schemaName": "billing", "tableName": "payments", "columns": ["amount"]}}}}15}16"""17with tempfile.TemporaryDirectory() as name:18 folder = Path(name)19 for path in policy.POLICIES.glob("*.rego"):20 (folder / path.name).write_text(path.read_text(encoding="utf-8"), encoding="utf-8")21 with open(folder / "access_test.rego", "a", encoding="utf-8") as tests:22 tests.write(whole_input)23 results = policy.run_tests(folder)24 print("tests that end in ERROR:", f"{Counter(results.values())['ERROR']} of {len(results)}")25 rego = policy.interpreter(folder, tests=True)26 succeeded = rego.query("true").ok()27 # no query succeeds here, not even true: the interpreter loads the file with the broken test28 assert not succeeded29 print("the query true succeeds:", succeeded)3031 # lib.policy checks each output before reading it, so a decision asked of this interpreter raises an error.32 try:33 policy.decide(policy.request("finance-1", "billing.payments", ["amount"]), rego)34 except RuntimeError as error:35 print("lib.policy.decide raises:", error)3637 # Printing one of those failed outputs, in a separate Python process.38 crash = "import sys; from pathlib import Path; from lib import policy; print(policy.interpreter(Path(sys.argv[1]), tests=True).query('true'))"39 ended = subprocess.run([sys.executable, "-c", crash, str(folder)], capture_output=True)40 # a negative return code names the signal that ended the process41 print("printing the failed output ends Python with:", signal.Signals(-ended.returncode).name)
python regopy-failed-outputs.pytests that end in ERROR: 13 of 13
the query true succeeds: False
lib.policy.decide raises: regopy couldn't evaluate data.platform.access.decision, so there is no decision to read
printing the failed output ends Python with: SIGSEGV
1"""One label formatted from nine sources, the schema taken from each in turn. The point rests on the printed lines where regopy's JSON is invalid: a source that keeps its quotes breaks the output."""2import json34from regopy import Input, Interpreter56# The same label, sprintf("%s.%s", [schema, input.table]), with the schema "crm" taken from nine places.7# crm is a rule and schema_of a function, two of the nine sources8helpers = 'crm := "crm"\nschema_of(x) := "crm" if x == 1\n'9cases = [10 ("from input.schema", "input.schema", "true"),11 ("from a rule", "crm", "true"),12 ("from a function", "schema_of(1)", "true"),13 ("from iterating over a set", "s", 'some s in {"crm"}'),14 ("from object.get, the key found", 'object.get(input, "schema", "public")', "true"),15 # namespace is not in the input, so object.get returns its default, crm16 ("from object.get, its default", 'object.get(input, "namespace", "crm")', "true"),17 ("from lower(input.schema)", "lower(input.schema)", "true"),18 ("from concat", 'concat("", ["c", "rm"])', "true"),19 ("from a local variable set to a literal", "v", 'v := "crm"'),20]21for name, schema, body in cases:22 rego = Interpreter()23 rego.add_module("example", f'package example\n{helpers}label := sprintf("%s.%s", [{schema}, input.table]) if {{ {body} }}\n')24 rego.set_input(Input({"schema": "crm", "table": "learners"}))25 try:26 print(f"{name}:", json.loads(str(rego.query("x := data.example.label")))["bindings"]["x"])27 except json.JSONDecodeError as error:28 print(f"{name}, regopy's invalid JSON:", error.doc)
python regopy-sprintf-quotes.pyfrom input.schema: crm.learners
from a rule: crm.learners
from a function: crm.learners
from iterating over a set: crm.learners
from object.get, the key found: crm.learners
from object.get, its default, regopy's invalid JSON: {"expressions":[true], "bindings":{"x":""crm".learners"}}
from lower(input.schema), regopy's invalid JSON: {"expressions":[true], "bindings":{"x":""crm".learners"}}
from concat, regopy's invalid JSON: {"expressions":[true], "bindings":{"x":""crm".learners"}}
from a local variable set to a literal, regopy's invalid JSON: {"expressions":[true], "bindings":{"x":""crm".learners"}}
- Substituir a entrada inteira quebra toda consulta. Um teste extra que escreve sua requisição como
with input as {...}, e avalia regras que chamam built-ins comosprintf, faz toda consulta daquele interpretador falhar. Todo teste então termina em ERROR, 13 of 13, e também a primeira consulta feita a um interpretador novo carregado com os mesmos arquivos, antes de qualquer teste rodar: até a consultatruefalha. Substituir um caminho por vez, como fazem os testes da plataforma, funciona. - Imprimir uma saída com falha derruba o Python. Converter uma dessas saídas com falha em string termina o processo com
SIGSEGV. Por issolib.policyverificaoutput.ok()antes de ler qualquer coisa, e uma decisão pedida àquele interpretador levanta um erro em vez disso:regopy couldn't evaluate data.platform.access.decision, so there is no decision to read. sprintfmantém aspas indevidas. Formatar uma string devolvida por alguns built-ins, como o valor padrão deobject.get,lowerouconcat, ou uma variável local definida com um literal, mantém as aspas. A saída do próprio regopy fica então em JSON inválido, que o wrapper Python dele não consegue interpretar, como mostra{"expressions":[true], "bindings":{"x":""crm".learners"}}. Strings vindas deinput, de uma regra, de uma função, de iteração e do valor encontrado porobject.getsão formatadas corretamente, e a política da plataforma formata apenas strings desse tipo.
Regra prática: Trate o regopy como um avaliador local rápido e o OPA como a referência. Escreva apenas Rego v1, vincule toda decisão a uma variável, simule a entrada um caminho por vez com valores literais e verifique se uma saída teve sucesso antes de lê-la. Antes que uma política proteja dados de produção, verifique e teste-a com o próprio OPA, com opa check --strict e opa test.
Escreva as mesmas regras em Cedar
Rego não é a única linguagem para políticas como as da plataforma. Os projetistas do Cedar o apresentam como uma linguagem para autorização expressiva, rápida, segura e analisável (Cutler et al., 2024), e ele adota uma visão mais restrita de uma decisão. Uma requisição em Cedar nomeia um principal, uma ação e um recurso, e a resposta segue três regras: negação por padrão, proibição tem precedência sobre permissão, e ignorar em caso de erro, que a documentação define como "se a avaliação de uma política retorna erro, a política não entra na resposta de autorização; ela é ignorada" (Cedar, authorization). Um esquema declara cada tipo de entidade, os tipos de principal e de recurso que uma requisição pode nomear, com seus atributos, e os atributos são obrigatórios a menos que o esquema os marque como opcionais (Cedar, schema). A validação verifica as políticas contra um esquema antes de qualquer requisição, e um conjunto que valida evita a maioria dos erros que a avaliação poderia lançar, para requisições que correspondem ao esquema (Cedar, validation). Os exemplos do livro executam Cedar com cedarpy 4.12.2, que encapsula a biblioteca Rust Cedar Policy para Python (cedarpy).
As regras da plataforma em Cedar estão em governance/policies/access.cedar, com o esquema em access.cedarschema. Um permit por grupo repete o mapa readable da política Rego. Um forbid restringe agentes de suporte aos alunos de sua própria região, e outro oculta colunas sensíveis de todos, exceto da visão de finanças sobre os números de cartão. lib.policy.cedar_entities gera os usuários, grupos, tabelas e colunas a partir do mesmo documento de dados que a política Rego lê, e o código acrescenta o primeiro aluno de crm.learners em cada região:
1"""The platform's Cedar policies checked against their schema, then asked the questions the Rego policy answers, over entities generated from its data. The points rest on the printed decisions, and on the misspelt-region error the schema gives before any request."""2import cedarpy34from lib import policy5from lib.platform import load67policies = policy.CEDAR_POLICIES.read_text(encoding="utf-8")8schema = policy.CEDAR_SCHEMA.read_text(encoding="utf-8")9print("policies valid against the schema:", cedarpy.validate_policies(policies, schema).validation_passed)10# misspells region in the policy's text, so the schema reports the attribute that User lacks11typo = cedarpy.validate_policies(policies.replace("principal.region", "principal.regoin"), schema)12# the validator's first error13print("with region misspelt:", typo.errors[0].error)1415# Entities generated from the files the Rego policy reads, plus the first learner of crm.learners in each region.16first = {}17for learner in load("crm.learners").select(["learner_id", "support_region"]).to_pylist():18 # setdefault keeps the first learner seen in each region19 first.setdefault(learner["support_region"], learner)20entities = policy.cedar_entities(learners=first.values())212223def ask(user: str, resource: str) -> cedarpy.AuthzResult:24 request = {"principal": f'User::"{user}"', "action": 'Action::"read"', "resource": resource, "context": {}}25 return cedarpy.is_authorized(request, policies, entities, schema)262728for user, kind, name in [("finance-1", "Column", "billing.payments.card_number"),29 ("analyst-1", "Column", "billing.payments.card_number"),30 ("analyst-1", "Column", "billing.payments.amount"),31 ("marketing-1", "Table", "billing.payments")]:32 print(f"{user} reads {name}:", ask(user, f'{kind}::"{name}"').decision.value)33for region, learner in sorted(first.items()):34 print(f"agent-a05 (emea) reads a learner in {region}:", ask("agent-a05", f'Learner::"{learner["learner_id"]}"').decision.value)35answer = ask("finance-1", 'Column::"billing.payments.card_number"')36# the policies that decided the answer, and those skipped on an error, come from its diagnostics37print("everything Cedar returns for finance-1's card numbers:", answer.decision.value, list(answer.diagnostics.reasons), list(answer.diagnostics.errors))
python cedar-same-rules.pypolicies valid against the schema: True
with region misspelt: for policy `policy6`, attribute `regoin` on entity type `User` not found
finance-1 reads billing.payments.card_number: Allow
analyst-1 reads billing.payments.card_number: Deny
analyst-1 reads billing.payments.amount: Allow
marketing-1 reads billing.payments: Deny
agent-a05 (emea) reads a learner in americas: Deny
agent-a05 (emea) reads a learner in apac: Deny
agent-a05 (emea) reads a learner in emea: Allow
everything Cedar returns for finance-1's card numbers: Allow ['policy3'] []
As decisões concordam com a política Rego onde o Cedar consegue expressá-las. Finanças pode ler a coluna card_number, e o cientista de dados não pode, onde o Rego permite a leitura e oculta a coluna. O cientista de dados pode ler amount, e marketing não pode ler pagamentos. O agente emea pode ler o aluno emea e nenhum dos outros. As políticas também validam contra o esquema, e escrever errado region gera um erro preciso antes de qualquer execução: for policy policy6, attribute regoin on entity type User not found.
O Rego não tem essa verificação por padrão. O mesmo erro de digitação em um atributo, user.regoin no filtro de linhas do agente de suporte, é indefinido tanto no OPA quanto no regopy, e opa check --strict o deixa passar, porque o OPA verifica referências contra um esquema apenas quando você o fornece (OPA policy language, schemas), e a plataforma não fornece nenhum. O filtro de linhas do agente desaparece, e somente um teste que compare os filtros, como test_support_reads_only_its_own_region, o detecta.
O Cedar devolve uma decisão e pouco mais. A última linha da saída é tudo o que ele devolve para os números de cartão de finanças: a decisão e o ID da política que a tomou. O cedarpy nomeia as políticas por posição, policy3 para a quarta, e não pelas anotações @id como finance-tables. A documentação do Cedar diz que @id não significa nada para a própria linguagem: sua CLI o usa para definir IDs de política, e outras interfaces os definem de outra forma (Cedar, syntax). Nada na resposta indica last4, a máscara que a política Rego devolve para os números de cartão de finanças, porque o Cedar pode permitir uma coluna mas não pode dizer como exibi-la. Essa regra passaria para o código de aplicação, fora da política e de seus testes. Com as linhas é igual. O Cedar decide um aluno de cada vez, então filtrar os alunos da plataforma significa uma requisição por aluno, ou a avaliação parcial experimental do Cedar, que devolve políticas residuais para as partes que ainda não consegue decidir, e cujo resultado não é uma decisão final de autorização (cedarpy). O artigo do Cedar apresenta o compromisso (trade-off) pelo outro lado: "A expressividade adicional do Rego é uma bênção, mas também uma maldição". Acrescenta que o Rego não oferece conceitos de autorização embutidos, como allow ou deny. O mesmo artigo relata que o Cedar é de 42.8 a 80.8 vezes mais rápido que o Rego na mediana, em três cargas de trabalho com relações transitivas, com Cedar 3.0.1 contra o Rego do OPA 0.61.0. Essas são medições de seus projetistas, não deste livro, e nada dizem sobre o regopy.
Regra prática: Escolha o Cedar quando toda pergunta for "este principal pode fazer isto com este recurso?", como nas verificações de permissão de uma aplicação, e você quiser um esquema para verificar cada política antes de ela ser executada. Escolha o Rego quando a resposta precisar carregar dados, como acontece com os filtros de linhas e as máscaras de colunas de um armazém de dados, ou quando o motor já consulta o OPA, como o Trino faz. Para o armazém de dados da plataforma, recomendamos o Rego.
O que dá errado em produção
Consideramos a falha mais prejudicial uma regra que deixa de se aplicar em silêncio porque um atributo está ausente, e ela acontece nas duas linguagens. Em Rego, "Expressões que se referem a valores indefinidos também são indefinidas" (OPA policy language). O filtro de linhas do agente de suporte obtém seu valor de user.region, então, para um usuário sem região, o filtro simplesmente não existe. Uma regra que permite por grupo continua permitindo, e sem filtro significa todas as linhas.
Faça uma cópia da política e dos testes da plataforma, em uma pasta temporária, e remova a linha not missing_attribute de allow. Depois, adicione um agente de suporte com o grupo dele e sem região, como acontece quando alguém recebe um papel antes de alguém definir sua região, e peça às duas políticas os tickets do agente:
1"""The support policy with and without its guard, asked for a support agent's tickets. The prose's points rest on the printed reasons, row filters and regions seen with each version, and on the test the copy without the guard fails."""2import tempfile3from pathlib import Path45from lib import policy6from lib.platform import load78# A support agent added to users.toml with their group, before anyone has set their region.9data = policy.data_document()10data["platform"]["users"]["agent-new"] = {"groups": ["support"]}11request = policy.request("agent-new", "support.tickets", ["ticket_id", "body"])12# every region with a ticket, the candidates for what the agent may see13regions = sorted(set(load("support.tickets").column("support_region").to_pylist()))1415# A copy of the platform's policy and tests, with one line taken out of `allow`: the missing-attribute guard.16with tempfile.TemporaryDirectory() as name:17 folder = Path(name)18 for path in policy.POLICIES.glob("*.rego"):19 # the guard's line in allow is indented with a tab, and this removes it20 (folder / path.name).write_text(path.read_text(encoding="utf-8").replace("\tnot missing_attribute\n", ""), encoding="utf-8")2122 for label, policies in [("with the guard", policy.POLICIES), ("without the guard", folder)]:23 decision = policy.decide(request, policy.interpreter(policies, data=data))24 # a region counts when the decision allows the read and every row filter names it, so no filters means every region25 seen = [r for r in regions if decision["allow"] and all(f["equals"] == r for f in decision["row_filters"])]26 print(f"{label}, allowed:", decision["allow"])27 print(f"{label}, reasons:", "; ".join(decision["reasons"]))28 print(f"{label}, row filters:", decision["row_filters"])29 print(f"{label}, regions whose tickets the agent sees:", ", ".join(seen) or "none")3031 failing = [test for test, result in policy.run_tests(folder).items() if result != "PASS"]32print("tests that fail without the guard:", ", ".join(failing))
python missing-region-guard.pywith the guard, allowed: False
with the guard, reasons: support's row filter needs the user's region, and there is none
with the guard, row filters: []
with the guard, regions whose tickets the agent sees: none
without the guard, allowed: True
without the guard, reasons: support may read support.tickets; support's row filter needs the user's region, and there is none
without the guard, row filters: []
without the guard, regions whose tickets the agent sees: americas, apac, emea
tests that fail without the guard: test_support_without_a_region_is_denied
Sem a guarda, o agente é autorizado, com filtros de linhas [], e vê os tickets de americas, apac, emea, incluindo todas as mensagens e dados de contato de cada aprendiz. As razões já informam que a região está ausente; nada em allow perguntou. Com a guarda, o agente é negado, e o motivo indica o que está faltando: support's row filter needs the user's region, and there is none. default allow := false também não ajudou, porque uma regra permitiu. Um teste detecta o problema, test_support_without_a_region_is_denied, e é por isso que os testes da política incluem o caso do atributo ausente.
Cedar falha do mesmo modo, por meio de ignorar em caso de erro. Remova a verificação de has region da regra forbid dos agentes de suporte nas políticas Cedar da plataforma, e ela passa a ler principal.region de um agente que não tem esse atributo:
1"""Cedar's support forbid with and without its `has region` check, asked about a support agent with no region. The points rest on the printed decisions with each version, and on the validation error the unguarded policy gets."""2import cedarpy34from lib import policy5from lib.platform import load67guarded = policy.CEDAR_POLICIES.read_text(encoding="utf-8")8unguarded = guarded.replace("principal has region && ", "") # the same forbid, without its `has` check9schema = policy.CEDAR_SCHEMA.read_text(encoding="utf-8")1011# A support agent with no region yet, as when a role is given before anyone sets one, and the first learner of crm.learners in each region.12data = policy.data_document()13data["platform"]["users"]["agent-new"] = {"groups": ["support"]}14first = {}15for learner in load("crm.learners").select(["learner_id", "support_region"]).to_pylist():16 first.setdefault(learner["support_region"], learner)17entities = policy.cedar_entities(learners=first.values(), data=data)1819for name, policies in [("with `has region`", guarded), ("without it", unguarded)]:20 for region, learner in sorted(first.items()):21 request = {"principal": 'User::"agent-new"', "action": 'Action::"read"',22 "resource": f'Learner::"{learner["learner_id"]}"', "context": {}}23 answer = cedarpy.is_authorized(request, policies, entities, schema)24 print(f"{name}, a learner in {region}:", answer.decision.value)25 # answer is the last learner's request, in emea, the last region in sorted order26 print(f"{name}, policies skipped on an error:", list(answer.diagnostics.errors))27# the first error the validator returns for the unguarded policies28print("validation without it:", cedarpy.validate_policies(unguarded, schema).errors[0].error)
python cedar-missing-region.pywith `has region`, a learner in americas: Deny
with `has region`, a learner in apac: Deny
with `has region`, a learner in emea: Deny
with `has region`, policies skipped on an error: []
without it, a learner in americas: Allow
without it, a learner in apac: Allow
without it, a learner in emea: Allow
without it, policies skipped on an error: ['error while evaluating policy `policy6`: `User::"agent-new"` does not have the attribute `region`']
validation without it: for policy `policy6`, unable to guarantee safety of access to optional attribute `region` on entity type `User`
Sem a verificação, o Cedar permite que um agente de suporte sem região leia os aprendizes das três regiões. Ao avaliar a forbid, ocorre um erro, o Cedar ignora essa política, e a regra permit de suporte continua valendo. Com a verificação, o mesmo agente é negado em relação a todos os aprendizes. Passar o esquema para is_authorized não impediu o problema, porque o esquema declara region como opcional, já que usuários fora do suporte não têm esse atributo. A validação impediu, antes de qualquer requisição: for policy policy6, unable to guarantee safety of access to optional attribute region on entity type User.
Outras falhas a observar:
- Um atributo com grafia errada é indefinido, não um erro.
user.regoinno lugar deuser.regionpassa emopa check --strict, e o filtro de suporte desaparece como acontece com uma região ausente. Compare filtros completos nos testes e forneça um esquema ao OPA se quiser a verificação antes de qualquer teste ser executado. - Uma regra de negação que lê um atributo ausente falha aberta. A guarda corrige
allow; umadenyouforbidexige o mesmo cuidado. Negue explicitamente quando um atributo obrigatório estiver ausente, e escreva o teste para isso antes da regra. - Políticas que ninguém consegue testar. Regras mantidas nas configurações de um mecanismo ou em visões feitas à mão por papel não podem ser testadas unitariamente nem comparadas por diferenças, então se desviam. Mantenha a política, seus testes e sua tabela de decisões no repositório, e execute os três em cada alteração.
- O regopy aceita e o OPA recusa. Sintaxe pré-1.0 e variáveis não vinculadas executam no regopy. Verifique cada política com
opa check --strictantes de implantá-la no OPA. - Dados que mudaram sob a política. Mover um agente de suporte para outra região é uma edição em
users.toml, e a decisão só acompanha a mudança quando o documento de dados é reconstruído. Reconstrua-o sempre que suas fontes mudarem, e implante-o junto com a política.
O que este capítulo decidiu
-
Uma política, em Rego,
governance/policies/access.rego, nega por padrão, permite por grupo e restringe por três atributos: a região do agente, o consentimento do aprendiz e a finalidade da requisição. -
As requisições têm a forma das requisições OPA do Trino, montadas por
lib.policy.request, mais umpurposeopcional no nível superior; os grupos vêm deusers.toml, e não da requisição. -
Os dados da política são gerados por
lib.policy.data_documenta partir deusers.toml,metadata.tomlelearning.courses, e nunca digitados à mão. -
Cada decisão é um único documento com
allow,row_filters,column_masksereasons. Filtros e máscaras são dados, nunca SQL, e as máscaras sãoredact,last4,pseudonymizeeredact_contacts. Uma negação não traz filtros nem máscaras. -
Fatos ausentes falham de forma fechada: uma coluna que os metadados não classificam é tratada como sensível, e um usuário cujo filtro de linhas precisa de um atributo ausente é negado.
-
A única finalidade que a política conhece é
ai-training, que limita as revisões a aprendizes que concordaram com o treinamento de IA e mostra o texto deles com os dados de contato removidos. Uma leitura sem finalidade recebe o que o papel permite, com o texto das revisões oculto. -
Dois tipos de teste são executados a cada alteração: os testes unitários de Rego, por meio de
lib.policy.run_tests, e a tabela de quem vê o quê,lib.policy.WHO_SEES_WHAT. -
regopy para os exemplos, OPA como referência: somente Rego v1, cada decisão vinculada a uma variável, entrada simulada um caminho por vez com literais, e toda saída verificada antes de ser lida.
-
Cedar serve para comparação (
governance/policies/access.cedar). Ele se adapta a verificações de permitir ou negar sobre recursos isolados; o armazém de dados da plataforma precisa de filtros e máscaras como dados, por isso usa Rego. Uma política de acesso só é tão clara quanto seus testes são completos. Escrever as regras como código significa que uma mudança em quem vê o quê é um diff que um revisor consegue ler, e um teste pode ser executado antes de alguém depender dele.
Este capítulo, nesta edição
Edição 2026.11.31Exemplos aprovados em 19 de nov de 202613 de 13 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.31.