Aplicando políticas em consultas

Cerca de 46 minutos min de leitura, com 16 exemplos em 13 seções.

Edição 2026.11.31 Exemplos aprovados em 19 de nov de 2026 108 de 108 exemplos passam O que mudou

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

Ao final deste capítulo, você será capaz de aplicar decisões de acesso a toda consulta que a plataforma executa. Você vai reescrever cada consulta para que toda tabela que ela lê seja substituída por uma subconsulta que mantém apenas as linhas que o usuário pode ver e mascara as colunas que ele não pode ver, vai negar toda consulta que leia qualquer outra coisa, vai testar quem recebe o quê executando consultas reais e vai explicar onde uma reescrita feita antes do DuckDB deixa de proteger alguma coisa.

Uma política protege o armazém da plataforma de aprendizagem online somente se valer para toda consulta que chega a ele, e esse armazém guarda os dados de contato dos alunos, seus pagamentos e os textos que eles escrevem. O Capítulo 5 escreveu a política de acesso da plataforma em Rego. Dados um usuário, uma tabela e as colunas que ele deseja, e opcionalmente o motivo, a política devolve uma decisão: se a leitura deve ser allow, quais filtros de linha mantêm as linhas que o usuário pode ver, quais máscaras de coluna alteram a forma como uma coluna é exibida (redact, last4, pseudonymize ou redact_contacts) e os reasons. Uma decisão, sozinha, não faz nada. O SQL de um agente de suporte chega ao DuckDB como texto, então algo entre os dois precisa aplicar a decisão a cada tabela que esse texto lê, qualquer que seja a forma como a consulta foi escrita.

O módulo compartilhado do livro lib.enforce aplica as decisões; chamamos isso de camada de aplicação. Sua Enforcer mantém uma conexão DuckDB com uma view para cada tabela do catálogo (lib.warehouse.connect), o esquema das tabelas, a política e uma chave para pseudônimos. Os usuários nunca recebem a conexão. Enforcer.sql(query, user) reescreve a consulta de um usuário e executa a reescrita. Um serviço expõe apenas lib.enforce.answer, que a chama e devolve as linhas: nunca a relação, um identificador da conexão ou Enforcer.run, que executa SQL escrito pela camada com a chave anexada. O código usa o sqlglot na versão 30.33.0 e o DuckDB na versão 2.0.0.

Encontre todas as tabelas e colunas que uma consulta lê

Última alteração na edição 2026.11.27

Uma política só pode decidir sobre o que lhe é perguntado, por isso a camada precisa conhecer todas as tabelas que uma consulta lê e as colunas que ela lê de cada uma. Extrair isso do texto SQL é um problema de análise sintática com armadilhas: *, aliases, junções com USING, expressões de tabela comuns (CTEs) e identificadores em qualquer capitalização. O sqlglot analisa uma consulta e a transforma em uma árvore, e sua etapa qualify resolve cada coluna em relação a um esquema, qualifica-a com sua tabela e expande * nas colunas que ele representa, quando há um esquema contra o qual expandir (qualify na versão v30.24.0). A camada constrói esse esquema ao iniciar, listando as tabelas do catálogo e lendo as colunas e os tipos de cada uma a partir da view lib.warehouse.connect criada para ela, de modo que uma view que o DuckDB mantém para qualquer outra finalidade nunca entra no esquema.

Quatro consultas, cada uma com uma armadilha, mostram o que Enforcer.reads retorna: as colunas sobre as quais a política é consultada, que devem corresponder ao que cada consulta nomeia.

tables-a-query-reads.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""The columns four queries read from each table, and how each dialect normalizes the quoted name "LEARNERS". Theprose's point rests on the query with a CTE and on the normalization lines at the end."""import sqlglotfrom sqlglot import expfrom sqlglot.optimizer.normalize_identifiers import normalize_identifiersfrom lib.catalog import open_catalogfrom lib.enforce import Enforcer# only these two tables are loaded, so the layer's schema holds nothing elseplatform = Enforcer(open_catalog(["crm.learners", "support.tickets"]))# What each query reads, found by sqlglot's qualify against the catalog's schema, with `*` expanded.queries = {    "every column": "select * from crm.learners",    "a join": """select l.country, count(*) as tickets                 from crm.learners as l join support.tickets as t using (learner_id) group by all""",    # exclude drops notes from the CTE, so the reads name every other column of crm.learners    "a CTE": """with emea as (select * exclude (notes) from crm.learners where support_region = 'emea')                select email from emea""",    "names in capitals": 'select EMAIL from "CRM"."LEARNERS"',}for name, sql in queries.items():    for table, columns in platform.reads(sql).items():        print(f"{name}, {table}: {', '.join(columns)}")# DuckDB resolves quoted capitals to the lowercase table. Whether sqlglot lowercases them depends on the dialect.capitals = 'select count(*) from "CRM"."LEARNERS"'print('DuckDB, "CRM"."LEARNERS":', f"{platform.connection.sql(capitals).fetchall()[0][0]:,} rows")for dialect in ["duckdb", "trino", "postgres"]:    # the name the dialect's parser resolves the quoted identifier to    table = normalize_identifiers(sqlglot.parse_one('select * from "LEARNERS"', read=dialect), dialect=dialect).find(exp.Table)    print(f'{dialect} normalizes "LEARNERS" to:', table.name)
Saídapython tables-a-query-reads.py
every column, crm.learners: ai_training_consent, city, closed_at, country, date_of_birth, email, full_name, learner_id, marketing_consent, notes, phone, signup_at, status, street_address, support_region
a join, crm.learners: country, learner_id
a join, support.tickets: learner_id
a CTE, crm.learners: ai_training_consent, city, closed_at, country, date_of_birth, email, full_name, learner_id, marketing_consent, phone, signup_at, status, street_address, support_region
names in capitals, crm.learners: email
DuckDB, "CRM"."LEARNERS": 5,000 rows
duckdb normalizes "LEARNERS" to: learners
trino normalizes "LEARNERS" to: learners
postgres normalizes "LEARNERS" to: LEARNERS

As leituras seguem o que a consulta nomeia, não o que ela retorna. SELECT * lê todas as colunas de crm.learners, e a junção lê learner_id das duas tabelas, porque USING as compara, embora nenhuma delas apareça na saída. A CTE retorna apenas email, mas nomeia todas as colunas de crm.learners exceto notes, então a camada pergunta sobre todas elas. As leituras de uma consulta podem ser mais do que aquilo que ela retorna, mas nunca menos. "CRM"."LEARNERS" também resolve para crm.learners, porque a camada normaliza os identificadores da mesma forma que o DuckDB os resolve: o DuckDB retorna 5,000 rows de crm.learners para esse nome. O dialeto importa. O sqlglot converte "LEARNERS" para minúsculas no DuckDB e no Trino, e o mantém como LEARNERS no PostgreSQL, por isso a camada normaliza com o dialeto do motor que executa a consulta.

qualify tem uma lacuna que define o desenho da camada: ele falha em uma coluna desconhecida de uma tabela conhecida, mas ignora uma tabela que não está de forma alguma no esquema, deixando o * dessa tabela sem expansão. Execute-o em uma junção com marketing.audience, que representa uma tabela que um pipeline gravou depois que o esquema foi lido, e depois envie essa consulta e outras cinco leituras pela camada:

unknown-tables-denied.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Runs sqlglot's qualify on a join with a table the schema lacks, then sends that join and five other reads throughthe enforcement layer. The prose's point rests on the qualify line, where the star stays, and on the denial lines."""import sqlglotfrom sqlglot.optimizer.qualify import qualifyfrom lib.catalog import open_catalogfrom lib.enforce import Denied, Enforcerplatform = Enforcer(open_catalog(["crm.learners"]))# marketing.audience stands for a table a pipeline wrote after the schema was read. qualify alone lets it through.query = "select * from crm.learners as l join marketing.audience as a on a.learner_id = l.learner_id"print("qualify on its own:", qualify(sqlglot.parse_one(query, read="duckdb"), schema=platform.schema, dialect="duckdb").sql("duckdb"))# The enforcement layer denies anything that isn't a catalog table, before it asks the policy.attempts = {    "a table missing from the catalog": query,    "a column the table doesn't have": "select shoe_size from crm.learners",    # scan_crm_learners is the scan lib.warehouse registers for crm.learners, and DuckDB resolves it like a table    "the scan behind a view": "select count(*) from scan_crm_learners",    "a Parquet file": "select count(*) from read_parquet('data/platform/learners.parquet')",    "a table function": "select count(*) from query_table('crm.learners')",    "a statement that isn't a query": "summarize crm.learners",}for name, sql in attempts.items():    try:        platform.rewrite(sql, "analyst-1")        print(f"{name}: allowed")    except Denied as reason:        print(f"{name}: denied, {reason}")# What those reads would do on the layer's own connection, without the rewrite in front of it.rows = lambda sql: f"{platform.connection.sql(sql).fetchall()[0][0]:,} rows"print("the scan, run directly:", rows("select count(*) from scan_crm_learners"))print("the table function, run directly:", rows("select count(*) from query_table('crm.learners')"))try:    rows("select count(*) from read_parquet('data/platform/learners.parquet')")except Exception as error:    print("the file, run directly:", str(error).split(":")[0])# the layer turned external access off, and DuckDB refuses to turn it back on while the database runstry:    platform.connection.execute("set enable_external_access = true")except Exception as error:    print("turning external access back on:", str(error).split(": ", 1)[1])
Saídapython unknown-tables-denied.py
qualify on its own: SELECT * FROM "crm"."learners" AS "l" JOIN "marketing"."audience" AS "a" ON "a"."learner_id" = "l"."learner_id"
a table missing from the catalog: denied, not a table in the catalog: marketing.audience AS a
a column the table doesn't have: denied, Column 'shoe_size' could not be resolved. Line: 1, Col: 16
the scan behind a view: denied, not a table in the catalog: scan_crm_learners
a Parquet file: denied, not a table in the catalog: READ_PARQUET('data/platform/learners.parquet')
a table function: denied, not a table in the catalog: QUERY_TABLE('crm.learners')
a statement that isn't a query: denied, only a single query is allowed
the scan, run directly: 5,000 rows
the table function, run directly: 5,000 rows
the file, run directly: Permission Error
turning external access back on: Cannot enable external access while database is running

Sozinho, qualify retorna a consulta com SELECT * intacto e sem erro, de modo que uma camada que confiasse nele perguntaria à política sobre crm.learners e deixaria marketing.audience passar sem verificação. A camada nega toda tabela fora do catálogo antes de perguntar qualquer coisa à política, e o próprio qualify nega uma coluna que a tabela não possui. As outras quatro leituras mostram por que essa regra é ampla. lib.warehouse registra a varredura de cada tabela sob um nome próprio, como scan_crm_learners. Executada diretamente na conexão da camada, essa varredura retorna 5,000 rows de aprendizes em estado bruto. query_table lê qualquer tabela que o seu texto nomeia, e retorna 5,000 rows quando executado diretamente. read_parquet lê um arquivo, e SUMMARIZE não é uma consulta que a reescrita consiga analisar. As três primeiras não são tabelas do catálogo e a última não é uma consulta, por isso as quatro são negadas. A conexão da camada também tem a opção enable_external_access do DuckDB desativada, de modo que uma leitura de arquivo que passasse pela reescrita ainda falharia, com um Permission Error (Protegendo o DuckDB).

Regra prática: Pergunte à política sobre cada tabela e coluna que uma consulta nomeia, com * expandido contra o esquema do catálogo, e negue tudo o que esse esquema não contém: tabelas desconhecidas, arquivos, funções de tabela e instruções diferentes de uma única consulta. Uma negação custa uma pergunta à equipe da plataforma; uma passagem sem verificação custa o que a tabela contiver.

Permitir apenas tabelas do catálogo, CTEs e subconsultas

Última alteração na edição 2026.11.31

Negar nomes que o catálogo não contém não basta por si só, porque uma consulta pode ler dados por fontes que não são nomes de tabela. Uma função de tabela pode aparecer sob LATERAL, ou em uma subconsulta na lista de seleção. Fora do escopo de uma CTE, ou antes de a CTE ser definida, o DuckDB resolve o nome dela para qualquer outra coisa que a conexão tenha com esse nome. Uma verificação que inspeciona apenas nomes de tabela, e aceita qualquer nome que uma CTE use, deixa passar os dois casos.

Por isso, a camada verifica as fontes contra uma lista de permissão. Enforcer.check_sources percorre a consulta inteira e exige que toda fonte FROM e JOIN, em todos os níveis, seja uma tabela do catálogo, uma CTE no escopo ou uma subconsulta, e que um LATERAL seja aplicado sobre uma subconsulta. Todo o resto é negado, incluindo funções de tabela onde quer que apareçam, VALUES, UNNEST e junções entre parênteses. Uma CTE está no escopo de sua própria consulta, abaixo dela e nas CTEs seguintes, e uma CTE recursiva também no ramo recursivo do seu UNION. Uma lista de permissão falha de forma segura diante de um tipo de fonte que ninguém previu.

Uma consulta que passa pela camada não pode alterar nada. A função escalar write_log do DuckDB escreve no log de consultas do motor. duckdb_functions() marca essas funções: has_side_effects é "true se esta função altera o estado do banco de dados" (DuckDB, duckdb_functions). Na versão 2.0.0 ela também marca funções que apenas variam, como random e uuid. A camada nega toda função marcada, e toda macro que chame uma delas, como pg_sleep, lendo a lista a partir de duckdb_functions() quando inicia. Uma lista ordenada à mão em perigosas e inofensivas pode ficar desatualizada em uma atualização sem que ninguém perceba, e uma leitura governada raramente precisa de um número aleatório.

lib.enforce mantém os casos como um teste de regressão, source_cases, que o CI do capítulo 10 executa junto com o teste de ordem abaixo. Executá-los mostra cada negação e se algo foi registrado:

catalog-sources-only.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Runs the allowlist's regression cases through the layer and prints each denial with its reason; a case passes when it'sdenied exactly when it must be and its parse logs nothing. The prose's points rest on the count of cases that pass, the functions-denied line and the allowed-query line at the end."""from lib.catalog import open_catalogfrom lib.enforce import MUST_ALLOW, MUST_DENY, Enforcer, source_casesplatform = Enforcer(open_catalog(["crm.learners", "support.tickets"]))# The allowlist's regression test, lib.enforce.source_cases, which chapter 10's CI runs too: queries that read data# other than through a catalog table, a call to each function DuckDB marks as having side effects, and a query the# layer must still allow. A case passes when the layer denies it exactly when it must, and its parse logs nothing.cases = source_cases(platform)for case in cases:    if case["case"] in MUST_DENY:        print(f"{case['case']}:", f"denied, {case['reason']}" if case["denied"] else "ALLOWED")functions = [case for case in cases if case["must"] == "deny" and case["case"] not in MUST_DENY]print("functions with side effects:", ", ".join(case["case"].removeprefix("the function ") for case in functions))print("functions with side effects, denied:", f"{sum(case['denied'] for case in functions)} of {len(functions)}")print("cases whose parse sqlglot logged, quoting the query:", f"{sum(case['logged'] for case in cases)} of {len(cases)}")passing = [case for case in cases if case["denied"] == (case["must"] == "deny") and not case["logged"]]print("cases that pass:", f"{len(passing)} of {len(cases)}")# What two of the cases do on the layer's own connection, without the layer in front of it.# the name is used before its CTE is defined, so DuckDB resolves it to the scan of the same namebefore_the_cte = platform.connection.sql(MUST_DENY["a CTE's name before the CTE"]).fetchall()[0][0]print("a CTE's name before the CTE, run directly:", f"{before_the_cte:,} rows")# turns on DuckDB's query log, the one write_log writes into, so the entries below are what the call leftplatform.connection.execute("CALL enable_logging('QueryLog')")platform.connection.sql(MUST_DENY["a function that writes DuckDB's log"]).fetchall()logged = [message for (message,) in platform.connection.sql("select message from duckdb_logs where type = 'QueryLog'").fetchall()]print("the log function, run directly, query-log entries it leaves:", logged)# the query the allowlist must admit: a CTE, a join and a scalar subquery over catalog tablesfor name, query in MUST_ALLOW.items():    print(f"{name}, allowed:", f"{platform.sql(query, 'agent-a05').fetchall()[0][0]:,} rows")
Saídapython catalog-sources-only.py
a table function in FROM: denied, not a table in the catalog: QUERY_TABLE('crm.learners')
a table function in a scalar subquery: denied, not a table in the catalog: QUERY_TABLE('crm.learners')
a table function under LATERAL: denied, a LATERAL that isn't a subquery: LATERAL QUERY_TABLE('crm.learners')
a catalog-qualified name: denied, not a table in the catalog: memory.crm.learners
an information_schema view: denied, not a table in the catalog: information_schema.tables
a CTE's name outside its scope: denied, not a table in the catalog: other
a CTE's name before the CTE: denied, not a table in the catalog: scan_crm_learners
a function that writes DuckDB's log: denied, a function DuckDB marks as having side effects: write_log
a statement sqlglot keeps as text: denied, only a single query is allowed
functions with side effects: current_connection_id, current_query, current_query_id, current_transaction_id, currval, error, gen_random_uuid, nextval, pg_sleep, random, setseed, setval, sleep_ms, stats, uuid, uuidv4, uuidv7, vector_type, write_log
functions with side effects, denied: 19 of 19
cases whose parse sqlglot logged, quoting the query: 0 of 29
cases that pass: 29 of 29
a CTE's name before the CTE, run directly: 5,000 rows
the log function, run directly, query-log entries it leaves: ["select write_log('an entry', log_type := 'QueryLog')", 'an entry']
a CTE, a join and a scalar subquery, allowed: 61 rows

Cada caso que a camada deve negar é recusado antes que qualquer política seja consultada, com um motivo que nomeia a fonte. A análise não pode deixar rastro próprio. O sqlglot registra como texto qualquer instrução que mantém, como um CALL, com os valores incluídos (código-fonte do sqlglot, v30.24.0), por isso a camada silencia os avisos do analisador, e cada caso verifica que nada foi registrado. Os 29 of 29 casos passam.

Na conexão própria da camada, dois casos mostram o que essas negações impedem. O nome usado antes da sua CTE lê a varredura do mesmo nome, 5,000 rows de aprendizes brutos, e write_log deixa ["select write_log('an entry', log_type := 'QueryLog')", 'an entry'] no log de consultas: a sua própria instrução e uma entrada que nenhuma consulta fez. Toda função com efeitos colaterais é negada, 19 of 19.

A lista de permissão também precisa deixar passar consultas comuns. Executada como agent-a05, o agente de suporte da EMEA, uma CTE, uma junção e uma subconsulta escalar sobre tabelas do catálogo retornam 61 rows.

Regra prática: Verifique toda fonte contra uma lista de permissão de tabelas do catálogo, CTEs no escopo e subconsultas, negue o resto, e negue toda função que o motor marque como tendo efeitos colaterais, lida da própria lista dele. Mantenha os casos como teste de regressão para cada alteração na camada e cada atualização do motor, e acrescente um para cada novo tipo de fonte ou função.

Mascarar referências a colunas vaza dados

Última alteração na edição 2026.11.27

Com as colunas conhecidas, a aplicação óbvia reescreve as referências: sempre que a consulta seleciona email e a decisão mascara essa coluna, seleciona o mascaramento no lugar. Ela precisa apenas da lista de colunas da primeira seção, e parece correta nas consultas que as pessoas testam. Ela falha porque uma consulta pode ler uma coluna sem selecioná-la, e o DuckDB pode devolver uma coluna sem citá-la pelo nome.

Enforcer.mask_select_list faz a reescrita de colunas, mantida apenas para mostrar sua falha. Testamos com cinco leituras voltadas para o e-mail do aprendiz 2, executadas como analyst-1, um cientista de dados que pode ler crm.learners com email e as demais colunas pessoais pseudonimizadas, e texto livre como notes ocultado. A primeira saída é a reescrita de uma leitura simples, com qualquer e-mail armazenado substituído por um marcador, pois os exemplos nunca imprimem um. Preveja quantas das cinco a reescrita interrompe:

select-list-masks-leak.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Masks the email in the select list only, then runs five reads aimed at one learner's email through that rewrite andprints what each returns. The prose's point rests on the five attack lines, each of which returns learner 2's ID, thestored email, or an error that holds it."""import reimport duckdbfrom lib.catalog import open_catalogfrom lib.enforce import EMAIL, Enforcerplatform = Enforcer(open_catalog(["crm.learners"]))# analyst-1, a data scientist, may read crm.learners with `email` pseudonymized. The attacks aim at learner 2.email = platform.connection.sql("select email from crm.learners where learner_id = 2").fetchall()[0][0]print("the column rewrite:", platform.mask_select_list("select learner_id, email from crm.learners", "analyst-1"))attacks = {    "a WHERE on the raw column": f"select learner_id from crm.learners where email = '{email}'",    "the whole row as a struct": "select struct_extract(l, 'email') from crm.learners as l where learner_id = 2",    "COLUMNS(...)": "select columns('^email$') from crm.learners where learner_id = 2",    "to_json": "select to_json(l) ->> 'email' from crm.learners as l where learner_id = 2",    "a cast error": "select learner_id from crm.learners where cast(email as integer) = 0",}for name, sql in attacks.items():    try:        # the column rewrite changes only the select list, so every other clause reads the stored email        answer = str(platform.run(platform.mask_select_list(sql, "analyst-1")).fetchall())    except duckdb.Error as error:        answer = str(error).splitlines()[0]    print(f"{name}:", re.sub(EMAIL, "<a stored email>", answer))      # the book never prints a stored email
Saídapython select-list-masks-leak.py
the column rewrite: SELECT "learners"."learner_id" AS "learner_id", SHA256($pseudonym_key || CAST("learners"."email" AS TEXT)) AS "email" FROM "crm"."learners" AS "learners"
a WHERE on the raw column: [(2,)]
the whole row as a struct: [('<a stored email>',)]
COLUMNS(...): [('<a stored email>',)]
to_json: [('<a stored email>',)]
a cast error: Conversion Error: Could not convert string '<a stored email>' to INT32 when casting from source column email

A reescrita de colunas não interrompe nenhuma das cinco. Sua reescrita da leitura simples está correta: email volta como um hash. As cinco leituras passam por ela de três maneiras:

  • Um WHERE sobre a coluna bruta nunca passa pela lista de seleção, então compara o e-mail armazenado. O analista adivinha um e-mail e recebe de volta o ID do aprendiz 2, [(2,)], que liga essa pessoa a cada linha que pode ser unida por learner_id.
  • A linha inteira como struct, COLUMNS(...) e to_json devolvem o e-mail armazenado, [('<a stored email>',)], sem nenhuma referência de coluna chamada email que a reescrita possa encontrar: o DuckDB expande a linha, ou casa nomes de colunas com um padrão, por conta própria.
  • Um erro de conversão imprime um e-mail armazenado em sua mensagem. Os erros de conversão do DuckDB incluem o valor, e a documentação do PostgreSQL alerta que "a maioria das funções de conversão inclui seus valores de entrada nas mensagens de erro que produzem" (PostgreSQL 18, Regras e Privilégios).

Mascarar a coluna onde a consulta a nomeia, inclusive na cláusula WHERE, impediria a primeira e a última leitura. Não consegue impedir as três do meio, pois elas nunca nomeiam a coluna.

Regra prática: Não aplique máscaras reescrevendo referências a colunas. Por mais formas de referência que você cubra, o motor tem mais maneiras de ler uma coluna do que a reescrita consegue reconhecer. Aplique a máscara onde os dados se originam, para que toda leitura veja o valor mascarado, como faz a próxima seção.

Substitua cada tabela por uma subconsulta filtrada e mascarada

Última alteração na edição 2026.11.27

A reescrita de referências a colunas vaza dados porque a tabela original permanece na consulta. A correção substitui a tabela. Enforcer.rewrite substitui cada tabela do catálogo na consulta, sob o alias que a própria consulta lhe dá, por uma subconsulta construída a partir da decisão do usuário:

  • todas as colunas da tabela, na ordem da tabela, de modo que *, um struct ou COLUMNS(...) veja a forma que espera;
  • cada coluna que a consulta lê, como armazenada ou mascarada conforme indica a decisão, dentro de um CASE sobre os filtros de linha que uma seção posterior explica;
  • cada coluna que ela não lê, como um NULL tipado, já que a política não foi consultada sobre ela;
  • uma cláusula WHERE com todos os filtros de linha da decisão.

Tudo o que a consulta do usuário faz, desde seu WHERE até suas leituras de struct, passa então a acontecer sobre essa subconsulta. É o modelo que o plugin OPA do Trino segue, em que um filtro de linha se comporta essencialmente como uma cláusula WHERE adicional, como mostra a seção sobre motores.

Considere instructor-17, que lê as avaliações baixas entre as avaliações dos próprios cursos. A política mantém as avaliações dos próprios cursos e remove os dados de contato de body. A reescrita impressa mostra como:

table-rewrite.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Rewrites instructor-17's query over the reviews, prints the rewrite and runs it. The prose's point rests on the tworesult lines: how many reviews come back, and how many of them still hold an email."""import sqlglotfrom lib.catalog import open_catalogfrom lib.enforce import Enforcerplatform = Enforcer(open_catalog(["learning.reviews"]))# instructor-17 reads the low ratings of their courses' reviews. The policy filters reviews to their six courses and# shows `body` with contact details removed.query = "select course_id, rating, body from learning.reviews where rating <= 2"# the query as text, with the reviews table replaced by a subquery built from the decisionrewritten = platform.rewrite(query, "instructor-17")print(sqlglot.transpile(rewritten, read="duckdb", write="duckdb", pretty=True)[0])print("reviews returned:", len(platform.run(rewritten).fetchall()))print("of them holding an email:", platform.run(f"select count(*) from ({rewritten}) where body like '%@%'").fetchall()[0][0])
Saídapython table-rewrite.py
SELECT
  "reviews"."course_id" AS "course_id",
  "reviews"."rating" AS "rating",
  "reviews"."body" AS "body"
FROM (
  SELECT
    CAST(NULL AS BIGINT) AS review_id,
    CAST(NULL AS BIGINT) AS learner_id,
    CASE WHEN source.course_id IN (2, 75, 80, 87, 103, 134) THEN source.course_id END AS course_id,
    CASE WHEN source.course_id IN (2, 75, 80, 87, 103, 134) THEN source.rating END AS rating,
    CASE
      WHEN source.course_id IN (2, 75, 80, 87, 103, 134)
      THEN REGEXP_REPLACE(
        REGEXP_REPLACE(source.body, '[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+', '[email]', 'g'),
        '\+?\(?[0-9][0-9 ().-]{6,}[0-9]',
        '[phone]',
        'g'
      )
    END AS body,
    CAST(NULL AS TIMESTAMPTZ) AS posted_at
  FROM learning.reviews AS source
  WHERE
    source.course_id IN (2, 75, 80, 87, 103, 134)
) AS "reviews"
WHERE
  "reviews"."rating" <= 2
reviews returned: 9
of them holding an email: 0

A consulta retorna 9 avaliações, e 0 delas contêm um e-mail. A consulta do instrutor permanece por fora, qualificada mas sem outras alterações. Por dentro, course_id e rating passam como armazenados, e body como a máscara redact_contacts, cada um dentro de um CASE sobre o filtro de linha, uma lista literal dos cursos do instrutor; e as colunas que a consulta não lê passam como NULLs tipados.

As cinco leituras que derrotaram a reescrita de colunas, executadas por analyst-1 através da reescrita de tabelas, e por meio de lib.enforce.answer, a função que um serviço chama em sua fronteira:

table-rewrite-holds.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Sends the five reads from the column rewrite through the table rewrite, and through `answer`, the service's boundary.It then shows what the analyst receives and what the platform team's log holds. The prose's point rests on the five attacklines, the operator's log line and the relation line."""import loggingimport refrom lib.catalog import open_catalogfrom lib.enforce import EMAIL, Enforcer, QueryFailed, answerplatform = Enforcer(open_catalog(["crm.learners"]))operator_log = []                     # the platform team's log, kept in a list here so the example can print itlogging.getLogger("lib.enforce").addHandler(handler := logging.Handler())handler.emit = lambda record: operator_log.append(record.getMessage().splitlines()[0])# The five attacks on the column rewrite, run by analyst-1 again: through the table rewrite this time, and through# `answer`, the function a service calls at its boundary.email = platform.connection.sql("select email from crm.learners where learner_id = 2").fetchall()[0][0]attacks = {    "a WHERE on the raw column": f"select learner_id from crm.learners where email = '{email}'",    "the whole row as a struct": "select struct_extract(l, 'email') from crm.learners as l where learner_id = 2",    "COLUMNS(...)": "select columns('^email$') from crm.learners where learner_id = 2",    "to_json": "select to_json(l) ->> 'email' from crm.learners as l where learner_id = 2",    "a cast error": "select learner_id from crm.learners where cast(email as integer) = 0",}# a pseudonym is 64 hex digits, shortened here; the example never prints a stored emailshorten = lambda text: re.sub(r"\b([0-9a-f]{8})[0-9a-f]{56}\b", r"\1…", re.sub(EMAIL, "<a stored email>", text))for name, sql in attacks.items():    try:        # answer returns the rows, or raises QueryFailed with a generic message, as a service sees it        got = str(answer(platform, sql, "analyst-1"))    except QueryFailed as error:        got = f"{type(error).__name__}, {error}"    print(f"{name}:", shorten(got))for line in operator_log:    print("in the operator's log:", shorten(line))      # a pseudonym, 64 hex digits, shortened# Why `answer` returns rows: the relation Enforcer.sql returns is a handle on the layer's connection, and runs any SQL.# the relation is a handle on the layer's connection, so its .query runs SQL of its own thererelation = platform.sql("select learner_id from crm.learners", "analyst-1")print("the relation, running SQL of its own:", shorten(str(relation.query("r", "select email from crm.learners where learner_id = 2").fetchall())))print("what answer returns:", type(answer(platform, "select learner_id from crm.learners", "analyst-1")).__name__)
Saídapython table-rewrite-holds.py
a WHERE on the raw column: []
the whole row as a struct: [(None,)]
COLUMNS(...): [(None,)]
to_json: [(None,)]
a cast error: QueryFailed, the query failed: the platform team can see why
in the operator's log: a query by analyst-1 failed in the engine: Conversion Error: Could not convert string 'e4f62f1a…' to INT32 when casting from source column email
the relation, running SQL of its own: [('<a stored email>',)]
what answer returns: list

A reescrita barra as cinco. O WHERE retorna [], porque, dentro da subconsulta, email já é o pseudônimo. As leituras do struct, de COLUMNS(...) e de to_json retornam NULL, e não o pseudônimo, porque essas consultas não citam nenhuma coluna além de learner_id. A política não foi consultada sobre nenhuma outra coluna, e o NULL tipado não dá valor às demais. Uma leitura que a reescrita não consegue enxergar falha de forma restritiva. O erro de conversão agora traz um pseudônimo em vez de um e-mail, e answer oculta até isso: ele busca as linhas dentro de um bloco try, converte qualquer erro do motor em QueryFailed e grava a mensagem do DuckDB no log da equipe de plataforma, que o exemplo imprime após as cinco leituras. O analista recebe QueryFailed, the query failed: the platform team can see why.

answer retorna linhas, e não uma relação, porque uma relação do DuckDB executa qualquer SQL em sua conexão. A relação do analista, quando solicitada por um e-mail, retorna [('<a stored email>',)].

Gerar a subconsulta para cada consulta, em vez de escrever uma view por papel, é o que a mantém em sintonia com a política. As decisões da plataforma dependem de região, cursos, consentimento e finalidade, e uma view feita à mão para cada combinação é a "explosão de papéis" descrita pelo NIST, em que as condições se tornam "numerosos papéis ad hoc e de associação limitada" (NIST SP 800-162). Tais views divergiriam da política na primeira vez que alguém editasse apenas uma delas.

Regra prática: Substitua toda tabela protegida por uma subconsulta gerada a partir da decisão, sob o alias da própria consulta, e deixe a consulta do usuário sem outras alterações. Dê às colunas não lidas um NULL tipado. Se os usuários precisarem de leituras de linha inteira para exibir valores, consulte a política sobre todas as colunas de cada tabela, para que as máscaras cubram todas elas, ao custo de requisições e registros de auditoria que citam colunas que a consulta nunca usou.

Escreva cada máscara como SQL em um só lugar

Última alteração na edição 2026.11.31

A política nomeia uma máscara; a camada decide em que SQL ela se torna. Manter esse mapeamento em um só lugar, a tabela MASKS em lib.enforce e o NULL tipado ao lado, significa que uma correção em uma máscara chega a todas as tabelas que a usam, e a política nunca carrega SQL, o que seria código chegando como dado. A reescrita de tabelas chama lib.enforce.masked para cada coluna mascarada e imprime o SQL para as quatro máscaras que a política nomeia:

masks-as-sql.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Prints the SQL the enforcement layer writes for each of the four masks the policy names, and counts DuckDB's functionsnamed like HMAC. The prose's points rest on the pseudonymize line and on the HMAC count."""import duckdbfrom sqlglot import expfrom lib.enforce import masked# The four masks the policy names, as the SQL the enforcement layer writes for them.# the column's type, which the redact mask casts its NULL tofor kind, column, type_ in [("redact", "date_of_birth", "DATE"), ("last4", "card_number", "VARCHAR"),                            ("pseudonymize", "email", "VARCHAR"), ("redact_contacts", "body", "VARCHAR")]:    # redact is a typed NULL; the other masks' SQL comes from lib.enforce's MASKS table    print(f"{kind}:", masked(kind, exp.column(column), type_).sql("duckdb"))# The pseudonymize mask hashes the key followed by the value, because DuckDB has no HMAC function to call.# DuckDB's function catalog, searched for any name containing hmac, whatever its casehmac = duckdb.sql("select count(*) from duckdb_functions() where function_name ilike '%hmac%'").fetchall()[0][0]print("DuckDB functions named like HMAC:", hmac)
Saídapython masks-as-sql.py
redact: CAST(NULL AS DATE)
last4: RIGHT(REGEXP_REPLACE(card_number, '[^0-9]', '', 'g'), 4)
pseudonymize: SHA256($pseudonym_key || CAST(email AS TEXT))
redact_contacts: REGEXP_REPLACE(REGEXP_REPLACE(body, '[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+', '[email]', 'g'), '\+?\(?[0-9][0-9 ().-]{6,}[0-9]', '[phone]', 'g')
DuckDB functions named like HMAC: 0

Cada máscara faz um trabalho:

  • redact é um NULL convertido para o tipo da coluna, de modo que a coluna mantém seu tipo para qualquer coisa que a consulta faça com ela, como uma união ou uma função de data.
  • last4 mantém os últimos quatro dígitos de um número de cartão, depois de remover tudo o que não é dígito.
  • pseudonymize é um hash com chave, SHA-256 sobre a chave seguida do valor, porque o DuckDB na versão 2.0.0 não tem uma função HMAC: duckdb_functions() lista 0 funções com nome semelhante. Onde o seu motor tiver uma, prefira HMAC (RFC 2104).
  • redact_contacts substitui e-mails e números de telefone em texto livre por [email] e [phone].

Imagine alguém com uma lista dos e-mails da plataforma, que faz o hash de cada um e procura entre os pseudônimos que analyst-1 vê em crm.learners:

pseudonym-key.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Hashes a list of emails the way the layer hashes pseudonyms, with and without its key, then rotates the key and countsthe pseudonyms that change. The prose's points rest on the three count lines: the matches without the key and with it, andthe pseudonyms that change on rotation."""from lib.catalog import open_catalogfrom lib.enforce import Enforcer# The pseudonyms analyst-1, the platform's data scientist, sees in crm.learners. Someone holding a list of the# platform's emails hashes each one and looks for it among them, first without the key and then with it.# an example key, not a secret: production keeps the real one where only the layer can read itplatform = Enforcer(open_catalog(["crm.learners"]), key="example-key-not-a-secret")seen = platform.sql("select learner_id, email from crm.learners", "analyst-1").to_arrow_table()platform.connection.register("seen", seen)# a guess is an email's hash; the second also puts the key first, as the layer hashes a pseudonymfor name, guess in [("without the key", "sha256(email)"), ("with the key", "sha256($pseudonym_key || email)")]:    matched = platform.run(f"select count(*) from crm.learners where {guess} in (select email from seen)").fetchall()[0][0]    print(f"pseudonyms matched from a list of emails, {name}: {matched:,} of {seen.num_rows:,}")# A new key gives every learner a new pseudonym, so data pseudonymized under the old key no longer joins.platform.key = "example-key-rotated"rotated = platform.sql("select learner_id, email from crm.learners", "analyst-1").to_arrow_table()# pairs each learner's old and new pseudonym, row by rowchanged = sum(a != b for a, b in zip(seen["email"].to_pylist(), rotated["email"].to_pylist()))print("pseudonyms that change when the key is rotated:", f"{changed:,} of {seen.num_rows:,}")
Saídapython pseudonym-key.py
pseudonyms matched from a list of emails, without the key: 0 of 5,000
pseudonyms matched from a list of emails, with the key: 5,000 of 5,000
pseudonyms that change when the key is rotated: 5,000 of 5,000

A chave é o que faz de um pseudônimo um pseudônimo. Sem ela, os hashes coincidem com 0 of 5,000 pseudônimos; com ela, coincidem com 5,000 of 5,000, de modo que quem tiver a chave e uma lista de e-mails pode identificar cada pseudônimo nela. A chave pertence somente à camada. Ela fica fora da política, que é código lido em revisões de código, e fora da consulta, onde um usuário que escolhesse a chave poderia calcular pseudônimos de e-mails adivinhados. A camada passa a chave ao DuckDB como parâmetro de consulta, para que ela fique fora do texto da consulta que o log do DuckDB registra, como mostra o capítulo 8, e a camada recusa qualquer consulta de usuário que traga um parâmetro, já que um chamado $pseudonym_key receberia a chave. Em produção, guarde a chave em um gerenciador de segredos que só a camada possa ler. Troque-a quando houver suspeita de vazamento, e planeje o que a troca implica: 5,000 of 5,000 pseudônimos mudam, então dados pseudonimizados com a chave antiga não se unem aos dados com a nova.

redact_contacts são duas expressões regulares, e vale medir o que elas removem. Os chamados e avaliações da plataforma trazem todos os dados pessoais que o gerador colocou neles, rotulados por construção, o que o capítulo 3 chama de a verdade. Cada texto passa pela máscara aqui, e os rótulos contam o que sobrevive:

redact-contacts-recall.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Applies the redact_contacts mask to every ticket and review, then counts the labelled personal data still left in themasked text, and the phone replacements made in the tickets. The prose's points rest on the 'left in the text' lines, thereplacement count, and the assert on the tickets' card, IBAN and date lines."""import duckdbfrom sqlglot import expfrom lib.enforce import maskedfrom lib.platform import load# The redact_contacts mask, run over every ticket and review, against the personal data the generator placed in them# (pii_spans, labelled by construction).con = duckdb.connect()# each table registers under its short name, which the queries below usefor name in ["support.tickets", "learning.reviews", "pii_spans"]:    con.register(name.split(".")[-1], load(name))mask = masked("redact_contacts", exp.column("body"), "VARCHAR").sql("duckdb")# a span counts as left when its exact text is still in the masked body, which the row_id join findscounts = con.sql(f"""    with masked as (select 'tickets' as source, ticket_id as row_id, {mask} as body from tickets                    union all select 'reviews', review_id, {mask} from reviews)    select source, entity, count(*), count(*) filter (where contains(masked.body, pii_spans.text))    from pii_spans join masked using (source, row_id) group by all order by all""").fetchall()# the phone pattern takes every card number, IBAN and date in the tickets, so none is left in the masked textleft_in_tickets = {entity: left for source, entity, _, left in counts if source == "tickets"}assert all(left_in_tickets[entity] == 0 for entity in ("CREDIT_CARD", "IBAN_CODE", "DATE_TIME"))for source, entity, placed, left in counts:    print(f"{source}, {entity}, left in the text: {left:,} of {placed:,}")# The phone pattern also takes card numbers, IBANs and dates, which are digits too.replaced = con.sql(f"select sum(len(regexp_extract_all({mask}, '\\[phone\\]'))) from tickets").fetchall()[0][0]print("[phone] replacements in tickets:", f"{replaced:,}")
Saídapython redact-contacts-recall.py
reviews, EMAIL_ADDRESS, left in the text: 0 of 120
reviews, PERSON, left in the text: 798 of 798
tickets, CREDIT_CARD, left in the text: 0 of 213
tickets, DATE_TIME, left in the text: 0 of 196
tickets, EMAIL_ADDRESS, left in the text: 0 of 423
tickets, IBAN_CODE, left in the text: 0 of 236
tickets, LOCATION, left in the text: 210 of 210
tickets, PERSON, left in the text: 1,657 of 1,657
tickets, PHONE_NUMBER, left in the text: 0 of 439
[phone] replacements in tickets: 1,520

A máscara remove os dados de contato e deixa os nomes. Nas avaliações, que instrutores e o assistente leem por meio desta máscara, restam 0 of 120 e-mails e 798 of 798 nomes.

Nos tickets, restam 0 of 439 números de telefone, mas o padrão de telefone faz 1,520 substituições. Números de cartão, IBANs e datas também são dígitos, então o padrão os captura igualmente, e nenhum deles permanece. Nomes e endereços de rua permanecem, então a máscara não torna um texto anônimo.

Regra prática: Mantenha o SQL de cada máscara em uma única tabela na camada de imposição, e deixe a política nomear máscaras, nunca escrevê-las. Gere cada pseudônimo com uma chave secreta que só a camada possui, passada como parâmetro. Meça cada máscara de texto contra dados rotulados antes que uma política dependa dela, e nomeie as máscaras pelo que removem, para que ninguém leia redact_contacts como "anonimizado".

Crie filtros de linha a partir dos dados da decisão

Última alteração na edição 2026.11.27

Máscaras mudam como um valor é exibido; filtros de linha decidem quais linhas um usuário recebe. Eles chegam em uma decisão como dados, em três formatos: uma coluna igual a um valor, uma coluna em uma lista de valores e uma verificação de consentimento sobre o aprendiz a que uma linha pertence. lib.enforce.row_filter transforma cada um deles em uma condição SQL, com os valores escritos como literais SQL pelo sqlglot, nunca colados no texto SQL. Ele nega a consulta para um formato que não conhece ou para uma coluna que a tabela não tem, e a camada verifica a coluna de um filtro de consentimento contra crm.learners antes de montar a verificação. O Capítulo 5 fez a política retornar filtros como dados justamente por essa razão: nada que uma requisição carregue pode chegar a uma consulta como código.

O formato de consentimento é o que exige cuidado. O assistente de curso, assistant-1, pode ler avaliações somente de aprendizes que concordaram que seu texto seja usado para treinar a IA da plataforma, e esse consentimento fica em crm.learners, que o assistente não pode ler. A camada o transforma em um semi-join, um teste de que o learner_id da avaliação está entre os aprendizes que consentiram, e o executa com o acesso próprio da camada a crm.learners:

row-filters-from-data.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Prints the condition the layer writes for each row filter in three decisions, then the reviews the assistant readsthrough its consent filter, and the denial of its read of the learners table. The prose's points rest on the read countsand the consent counts, and on the denied read at the end."""from lib.catalog import open_catalogfrom lib.enforce import Enforcer, row_filterplatform = Enforcer(open_catalog(["crm.learners", "learning.reviews", "support.tickets"]))# Each row filter in a decision, as the condition the enforcement layer writes for it.for user, table in [("agent-a05", "support.tickets"), ("instructor-17", "learning.reviews"), ("assistant-1", "learning.reviews")]:    # the decision for this read; its row filters are data, written as SQL in the loop below    decision = platform.decide(user, {table: set()})[table]    for rule in decision["row_filters"]:        print(f"{user}, {table}: {row_filter(rule, platform.columns(table)).sql('duckdb')}")# A filter's values come from data, so a value that looks like SQL stays a value.odd = {"column": "support_region", "equals": "emea' or '1' = '1"}print("a region that looks like SQL:", row_filter(odd, platform.columns("support.tickets")).sql("duckdb"))# The assistant's consent filter reads crm.learners, which the assistant itself may not read.total = platform.connection.sql("select count(*) from learning.reviews").fetchall()[0][0]read = platform.sql("select count(*) from learning.reviews", "assistant-1").fetchall()[0][0]print("reviews the assistant reads:", f"{read:,} of {total:,}")# a null consent means no answer was recorded, so the label reads 'never asked'by_consent = platform.connection.sql("""select coalesce(l.ai_training_consent::varchar, 'never asked'), count(*)    from learning.reviews r join crm.learners l using (learner_id) group by all order by all""").fetchall()for consent, reviews in by_consent:    print(f"reviews whose author's AI-training consent is {consent}: {reviews:,}")try:    platform.sql("select count(*) from crm.learners", "assistant-1")except Exception as reason:    print("the assistant reading crm.learners:", reason)
Saídapython row-filters-from-data.py
agent-a05, support.tickets: source.support_region = 'emea'
instructor-17, learning.reviews: source.course_id IN (2, 75, 80, 87, 103, 134)
assistant-1, learning.reviews: source.learner_id IN (SELECT consent.learner_id FROM crm.learners AS consent WHERE consent.ai_training_consent IS TRUE)
a region that looks like SQL: source.support_region = 'emea'' or ''1'' = ''1'
reviews the assistant reads: 436 of 3,000
reviews whose author's AI-training consent is false: 955
reviews whose author's AI-training consent is never asked: 1,609
reviews whose author's AI-training consent is true: 436
the assistant reading crm.learners: assistant-1 may not read crm.learners: no group of this user may read this table

Os valores de cada filtro se tornam literais SQL, então um valor continua sendo um valor, e um consentimento sem resposta conta como não. A região do agente e os cursos do instrutor se tornam uma igualdade e uma lista com IN, e uma região escrita para parecer SQL continua sendo uma única string, com as aspas duplicadas. O filtro de consentimento testa IS TRUE, de modo que os autores de avaliações de 1,609, que se cadastraram antes de a plataforma fazer a pergunta e não têm resposta registrada, contam como não consentidores, assim como os que disseram não.

O assistente lê avaliações de 436 of 3,000, que são as de autores que disseram sim. A requisição do próprio assistente para crm.learners é negada, com o motivo da política: a leitura dessa tabela pelo semi-join pertence à camada, não ao usuário.

Regra prática: Monte cada filtro de linha a partir dos valores da decisão com um construtor SQL, e negue qualquer formato de filtro ou coluna que a camada não reconheça. Trate um consentimento desconhecido como ausência de consentimento. Quando um filtro precisar de uma tabela que o usuário não pode ler, leia-a com o acesso próprio da camada dentro da subconsulta, e nunca ampliando o acesso do usuário.

Condicione cada coluna aos filtros de linha

Última alteração na edição 2026.11.27

Os filtros de linha ficam na cláusula WHERE da subconsulta, e a consulta do usuário envolve a subconsulta, então é tentador supor que o DuckDB aplica os filtros primeiro. O SQL não garante ordem, e um otimizador move as condições para onde forem mais baratas. Uma condição do usuário que pode falhar, como uma conversão de tipo, pode então ser executada sobre linhas que os filtros descartam, e um erro genérico não ajuda: que a consulta falhe revela algo sobre uma linha que o usuário talvez não possa ver.

A documentação do PostgreSQL nomeia esse vazamento: uma função que pode falhar dependendo de seus argumentos pode revelar informações significativas sobre linhas não vistas se for executada antes dos filtros de linha da view. No PostgreSQL, uma view marcada com security_barrier impede que “funções e operadores escolhidos com malícia recebam valores de linhas até que a view tenha concluído seu trabalho”, e apenas funções marcadas com LEAKPROOF ainda podem ser executadas primeiro (PostgreSQL 18, Rules and Privileges). O DuckDB não tem nenhum dos dois.

Por isso, a camada torna a ordem irrelevante. Cada coluna que a consulta lê sai da subconsulta como CASE WHEN <row filters> THEN <value> END, como em a reescrita do instrutor. As condições do usuário passam a depender do resultado dos filtros: seja qual for a ordem em que o DuckDB avalia, em uma linha que os filtros descartam ele vê NULL em todas as colunas.

lib.enforce.order_cases testa cada formato de filtro que a camada escreve: a igualdade do agente de suporte, a lista IN do instrutor e o semi-join de consentimento do assistente de curso. Cada caso copia a tabela filtrada, com uma coluna body que tem dígitos nas linhas que o filtro mantém e texto nas linhas que ele descarta, e então executa uma consulta que converte body para número. Essa conversão só falha se enxergar o valor de uma linha descartada:

row-filter-order.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Runs the evaluation-order test for each filter shape the layer writes, with the filter in a WHERE alone and as the layerwrites it. The prose's point rests on the consent semi-join's two lines, and on the count at the end."""from lib.enforce import order_cases# The evaluation-order regression test, lib.enforce.order_cases, which chapter 10's CI runs on every DuckDB upgrade.# For each shape of row filter the layer writes, it takes a real user's filter and a copy of the filtered table whose# `body` holds digits in the rows the filter keeps and text in the rows it drops. A query that casts `body` to a number# fails only if the cast sees a dropped row's value. It runs over the filter in a WHERE alone, and over the layer's# subquery.cases = order_cases()for case in cases:    for form, safe in [("with the filter in WHERE only", case["safe_with_where_only"]),                       ("as the layer writes it", case["safe_as_written"])]:        print(f"{case['shape']}, {form}: the cast {'never saw' if safe else 'saw'} a dropped row's value")print("filter shapes the layer's subquery keeps safe:", f"{sum(case['safe_as_written'] for case in cases)} of {len(cases)}")
Saídapython row-filter-order.py
equality, with the filter in WHERE only: the cast never saw a dropped row's value
equality, as the layer writes it: the cast never saw a dropped row's value
IN list, with the filter in WHERE only: the cast never saw a dropped row's value
IN list, as the layer writes it: the cast never saw a dropped row's value
consent semi-join, with the filter in WHERE only: the cast saw a dropped row's value
consent semi-join, as the layer writes it: the cast never saw a dropped row's value
filter shapes the layer's subquery keeps safe: 3 of 3

Condicionar cada coluna é o que mantém o semi-join de consentimento seguro. Com o filtro somente na cláusula WHERE, a igualdade e a lista IN eram seguras, mas o semi-join de consentimento não: o DuckDB executou a conversão sobre avaliações cujos autores não haviam consentido. Da forma como a camada os escreve, 3 of 3 formatos de filtro impedem que a conversão alcance linhas descartadas. Os dois primeiros eram seguros por escolha do otimizador na versão 2.0.0, e não por qualquer garantia; por isso, o teste roda a cada atualização. O custo da proteção é avaliar os filtros novamente em cada coluna que a consulta lê.

Regra prática: Nunca dependa da ordem de avaliação do motor para manter as condições de um usuário longe das linhas que um filtro descarta. Faça com que cada valor que a consulta de um usuário pode ler dependa dos filtros de linha, e teste cada formato de filtro a cada atualização do motor. Quando um motor tiver uma barreira própria, como as views com security_barrier do PostgreSQL, use-a também.

Teste quem vê o quê executando consultas

Última alteração na edição 2026.11.27

O capítulo 5 verifica a política com uma tabela de quem-vê-o-quê, lib.policy.WHO_SEES_WHAT: uma lista de requests, cada uma com a decisão que um revisor espera para ela. Isso testa as decisões, não o que os usuários recebem, o que também depende da reescrita, do SQL das máscaras e dos dados. lib.enforce.observe executa cada caso pela camada como o usuário do caso e compara o que volta com o que está armazenado: quantas linhas e quais colunas diferem. Um caso concorda com sua decisão quando o usuário é negado exatamente quando o caso diz que deve ser, recebe menos linhas do que as armazenadas exatamente quando o caso espera um filtro de linhas, e recebe valores alterados exatamente nas colunas que o caso espera mascaradas:

who-sees-what-in-queries.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Runs chapter 5's who-sees-what cases as queries and compares what each user gets with what is stored, then readsmarketing.audience, which has no metadata. The prose's points rest on the agreement count and on the two marketing lines."""from lib import pipelines, policyfrom lib.catalog import open_catalogfrom lib.enforce import Enforcer, agrees, observecatalog = open_catalog(["crm.learners", "learning.reviews", "billing.payments", "learning.enrollments", "learning.courses"])pipelines.run(catalog, "marketing_audience")          # a copy of learners' names and emails, with no metadata yetplatform = Enforcer(catalog)# Chapter 5's who-sees-what table, run as queries: what each user gets, against what's stored. A column is "changed"# when at least one value the user gets differs from the stored one.agreeing = 0for case in policy.WHO_SEES_WHAT:    got = observe(platform, case.user, case.table, case.columns, case.purpose)    who = case.user + (f" for {case.purpose}" if case.purpose else "")    if got is None:        print(f"{who}, {case.table}: denied")    else:        print(f"{who}, {case.table}: {got['rows']:,} of {got['stored']:,} rows, changed: {', '.join(got['changed']) or 'none'}")    agreeing += agrees(case, got)print("cases where what the user gets agrees with the decision:", f"{agreeing} of {len(policy.WHO_SEES_WHAT)}")# marketing.audience is a table marketing may read, but nobody has classified its columns, so the policy treats each# one as sensitive: marketing gets every row, and no value in any column.rows = platform.sql("select * from marketing.audience", "marketing-1").fetchall()# a column counts as shown when one of its values isn't None, which is what a redact mask returnsshown = sum(any(value is not None for value in column) for column in zip(*rows))print("marketing-1, marketing.audience, which has no metadata, rows:", f"{len(rows):,}")print("marketing-1, marketing.audience, which has no metadata, columns with a value:", f"{shown} of {len(rows[0])}")
Saídapython who-sees-what-in-queries.py
agent-a05, crm.learners: 1,581 of 5,000 rows, changed: none
agent-a05, billing.payments: denied
instructor-17, learning.reviews: 69 of 3,000 rows, changed: body
instructor-17, crm.learners: denied
marketing-1, crm.learners: 1,861 of 5,000 rows, changed: phone
finance-1, billing.payments: 17,562 of 17,562 rows, changed: card_number
analyst-1, billing.payments: 17,562 of 17,562 rows, changed: card_number
analyst-1, crm.learners: 5,000 of 5,000 rows, changed: email, notes
analyst-1, learning.reviews: 3,000 of 3,000 rows, changed: body
analyst-1 for ai-training, learning.reviews: 436 of 3,000 rows, changed: body
assistant-1, learning.reviews: 436 of 3,000 rows, changed: body
someone-else, crm.learners: denied
cases where what the user gets agrees with the decision: 12 of 12
marketing-1, marketing.audience, which has no metadata, rows: 1,829
marketing-1, marketing.audience, which has no metadata, columns with a value: 0 of 5

O que os usuários recebem concorda com a decisão em 12 of 12 casos. A agente de suporte da EMEA recebe os aprendizes da sua região como armazenados. O marketing recebe apenas os aprendizes ativos que consentiram, com phone alterado, e o analista recebe todos os aprendizes com email e notes alterados. As duas últimas linhas tratam de marketing.audience, que um pipeline grava e que ninguém ainda classificou. O marketing pode lê-la e recebe 1,829 linhas, com 0 of 5 colunas contendo algum valor, porque a política trata uma coluna não classificada como sensível.

O teste se justifica em uma alteração. Suponha que um pull request adicione analyst-1 ao grupo de suporte da EMEA, para que possa ajudar com tickets. É uma alteração de duas linhas em governance/users.toml, em um grupo e na região de que o filtro de linhas do suporte precisa. O código abaixo faz essa alteração em memória e executa os mesmos casos contra ela:

group-change-caught.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Makes one change to the users file in memory, runs the who-sees-what cases again, and runs chapter 5's decision checkon the same change. The prose's points rest on the lines that say which cases fail, and on the decision count."""from lib import policyfrom lib.catalog import open_catalogfrom lib.enforce import Enforcer, agrees, observe# A pull request changes one user in governance/users.toml, in two lines: analyst-1 joins support, with the region# support's row filter needs, EMEA, to help with tickets.# the users file as a document, changed here in memory and not on diskdata = policy.data_document()data["platform"]["users"]["analyst-1"] = {"groups": ["data-science", "support"], "region": "emea"}platform = Enforcer(open_catalog(["crm.learners", "learning.reviews", "billing.payments"]),                    rego=policy.interpreter(data=data))# The who-sees-what cases, run as queries with the change in place. The cases are unchanged: they say what each# user should get, and the change was meant to touch support tickets only.failing = 0for case in policy.WHO_SEES_WHAT:    got = observe(platform, case.user, case.table, case.columns, case.purpose)    # got is None when the user is denied, which agrees only with a case that expects a denial    if not agrees(case, got):        failing += 1        who = case.user + (f" for {case.purpose}" if case.purpose else "")        print(f"fails, {who}, {case.table}, rows: {got['rows']:,} of {got['stored']:,}")        print(f"fails, {who}, {case.table}, columns changed: {', '.join(got['changed']) or 'none'}, "              f"expected: {', '.join(case.masked)}")print("cases that fail:", f"{failing} of {len(policy.WHO_SEES_WHAT)}")# Chapter 5's table, which checks the decisions themselves, on the same change.decisions = [policy.decide(policy.request(c.user, c.table, c.columns, c.purpose), platform.rego) for c in policy.WHO_SEES_WHAT]print("cases that fail as decisions:", f"{sum(not policy.matches(c, d) for c, d in zip(policy.WHO_SEES_WHAT, decisions))} of {len(decisions)}")
Saídapython group-change-caught.py
fails, analyst-1, crm.learners, rows: 1,581 of 5,000
fails, analyst-1, crm.learners, columns changed: none, expected: email, notes
fails, analyst-1, learning.reviews, rows: 3,000 of 3,000
fails, analyst-1, learning.reviews, columns changed: none, expected: body
fails, analyst-1 for ai-training, learning.reviews, rows: 436 of 3,000
fails, analyst-1 for ai-training, learning.reviews, columns changed: none, expected: body
cases that fail: 3 of 12
cases that fail as decisions: 3 of 12

A alteração faz 3 of 12 casos falharem, e nenhum deles é sobre tickets. Todos os três são leituras de aprendizes e de avaliações feitas pelo analista. Em crm.learners, o analista agora recebe 1,581 of 5,000 linhas sem nenhuma coluna alterada: o filtro de região do suporte se aplica a elas, e as máscaras de colunas pessoais da política se aplicam apenas a usuários fora do suporte, então todo e-mail e toda nota chegam como armazenados. O texto das avaliações, que um cientista de dados normalmente não consegue ler de modo algum, ou lê com os contatos removidos para treinamento de IA, chega inteiro. A tabela de decisões do capítulo 5 falha nos mesmos casos, 3 of 12; este teste mostra o que o analista recebe.

Regra prática: Execute os casos de quem-vê-o-quê como consultas pela camada em toda alteração nas políticas, no arquivo de usuários, nos metadados ou na própria camada, e faça o build falhar quando algum caso discordar. Corrija um caso que falha alterando a política ou o arquivo de usuários. Altere um caso somente quando os responsáveis pelos dados concordarem que o que o usuário deve receber mudou.

Ocultar grupos pequenos em relatórios

Última alteração na edição 2026.11.31

Filtros de linhas e máscaras decidem quais linhas e valores um usuário vê. Agregados são um segundo canal: uma contagem ou uma média sobre poucas pessoas descreve essas pessoas. A defesa habitual é um tamanho mínimo de grupo, abaixo do qual um grupo relatado é ocultado. O número é uma regra prática, não uma medição. Um acordo público de uso de dados dos US Centers for Medicare & Medicaid Services fixa 11, e acrescenta que "nenhum uso de percentuais ou de outras fórmulas matemáticas pode ser empregado se elas resultarem na exibição de uma célula com menos de 11" (CMS-R-0235L). A plataforma usa o mesmo mínimo, 11, e o mantém em governance/enforcement.toml, onde uma alteração é revisada como uma mudança de política, e lib.enforce.minimum_group_size o lê.

Os instrutores recebem um relatório diário de curso com os alunos e o progresso médio por curso e por país do aluno, gerado por uma tarefa que lê países que os instrutores podem não ler. Os instrutores podem ler as matrículas de seus próprios cursos com o progresso de cada uma. Combinando essas duas coisas, obtém-se o relatório de instructor-17:

small-groups-difference.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Builds instructor-17's daily course report, counts its cells under the minimum and its cells of one learner, and matcheseach cell of one against the enrollments the instructor may read. The prose's points rest on the cell and lookup counts, andon the last line, which shows the differencing."""from lib.catalog import open_catalogfrom lib.enforce import Enforcer, minimum_group_sizeplatform = Enforcer(open_catalog(["crm.learners", "learning.courses", "learning.enrollments"]))minimum = minimum_group_size()print("minimum group size:", minimum)count = lambda sql: platform.connection.sql(f"select count(*) from ({sql})").fetchall()[0][0]# The platform's daily course report for instructor-17: learners and average progress, per course and learner country.# The report job reads learners' countries, which instructors may not read.platform.connection.execute("""create view mine as    select e.course_id, e.progress_pct, e.enrolled_at::date as day, l.country    from learning.enrollments e join crm.learners l using (learner_id)    where e.course_id in (select course_id from learning.courses where instructor_id = 17)""")platform.connection.execute("""create view report as    select course_id, country, count(*) as learners, avg(progress_pct) as progress from mine group by all""")print("cells in the report:", count("from report"))# the minimum is the threshold: a cell with fewer learners than it is held backprint("cells under the minimum:", count(f"from report where learners < {minimum}"))# instructor-17 may read their courses' enrollments, with each one's progress. A cell of one learner, matched on its# progress, names that learner's country.# what instructor-17 may read: enrollments with each one's progress, and no countryseen = platform.sql("select course_id, progress_pct from learning.enrollments", "instructor-17").to_arrow_table()platform.connection.register("seen", seen)print("cells of one learner:", count("from report where learners = 1"))print("learners a cell of one names:", count("""from report as cell where learners = 1 and (select count(*) from seen    where seen.course_id = cell.course_id and seen.progress_pct = cell.progress) = 1"""))print("cells shown with the minimum:", count(f"from report where learners >= {minimum}"))# The minimum doesn't stop differencing. An enrollment that arrives alone in its course on its day, in a cell already# shown, raises that cell by one in the next day's report, and the instructor sees which enrollment arrived.# an enrollment alone in its course that day, whose country already has the minimum on earlier daysrevealed = count(f"""from mine as m    where (select count(*) from mine as o where o.course_id = m.course_id and o.day = m.day) = 1      and (select count(*) from mine as o where o.course_id = m.course_id and o.country = m.country and o.day < m.day) >= {minimum}""")print("learners whose country the daily report reveals anyway:", f"{revealed} of {count('from mine')}")
Saídapython small-groups-difference.py
minimum group size: 11
cells in the report: 63
cells under the minimum: 51
cells of one learner: 6
learners a cell of one names: 3
cells shown with the minimum: 12
learners whose country the daily report reveals anyway: 92 of 482

Uma célula com um único aluno revela o país de seu aluno a qualquer pessoa que consiga encontrar esse aluno, e o instrutor consegue: ao comparar a média de progresso da célula com as suas próprias matrículas, ele identifica exatamente 3 alunos. O relatório tem 63 células, das quais 51 estão abaixo do mínimo e 6 contêm um único aluno cada.

Com o mínimo, 12 células são exibidas, e nenhuma dessas consultas funciona. O mínimo não impede a diferenciação. Uma matrícula que chega sozinha em seu curso naquele dia, numa célula que já é exibida, aumenta essa célula em um no relatório do dia seguinte, e o instrutor vê qual matrícula chegou. Isso revela o país de 92 of 482 alunos.

Diferenciação, a comparação de relatórios consecutivos, é o ataque que Denning, Denning e Schwartz chamaram de rastreador. Eles mostraram que "o comprometimento de conjuntos pequenos de consultas pode, de fato, quase sempre ser realizado com a ajuda de fórmulas características chamadas rastreadores" (Denning et al., 1979).

A Snowflake, que aplica um tamanho mínimo de grupo em seu motor, afirma que suas políticas "não garantem que um agente malicioso não possa usar consultas deliberadas para obter dados potencialmente sensíveis" (políticas de agregação da Snowflake). Contra a diferenciação, recomendamos ruído, como na privacidade diferencial (Dwork e Roth, 2014), em vez de limiares mais altos, e Privacy Engineering for Data Teams trata do assunto.

Regra prática: Oculte todo grupo relatado abaixo do mínimo em governance/enforcement.toml, e trate o mínimo como proteção contra a busca de uma pessoa específica, nunca contra a diferenciação. Não divida um relatório por um atributo que seu leitor pode não ler, enviado a um leitor que pode ver as linhas por trás dele: o relatório do instrutor por país é uma tabela de consulta de países. Remova o detalhamento, ou relate-o somente depois de torná-lo ruidoso.

Entregue as mesmas políticas a um motor que as aplique

Última alteração na edição 2026.11.27

Em produção, a aplicação pertence ao motor que todas as ferramentas consultam, porque o princípio da mediação completa de Saltzer e Schroeder afirma que "todo acesso a todo objeto deve ser verificado quanto à autoridade" (Saltzer and Schroeder, 1975), e uma política aplicada em uma ferramenta e não em outra viola esse princípio. O Trino, um motor SQL distribuído de código aberto, pode obter seu controle de acesso do Open Policy Agent (OPA) por meio de um plugin, e o capítulo 5 moldou as requisições da plataforma à semelhança das do plugin, para que a mesma política pudesse servir aos dois. O Trino 484 oferece controle de acesso baseado em arquivo, OPA e Ranger, e nenhum para Cedar (Trino 484, Segurança).

O plugin faz ao OPA perguntas separadas, em URIs separados (Trino 484, controle de acesso OPA):

  • Se deve permitir uma operação, como SelectFromColumns, respondida com um booleano allow.
  • Filtros de linhas, GetRowFilters, para uma tabela. O OPA responde com uma lista de {"expression": ...}, e cada expressão "essencialmente se comporta como uma cláusula WHERE adicional". O URI é opcional, e o Trino não aplica filtragem de linhas quando ele não está definido.
  • Máscaras de colunas, GetColumnMask, para uma coluna, ou para um lote de colunas em opa.policy.batch-column-masking-uri. "Apenas uma única máscara de coluna pode ser retornada para uma determinada coluna."

Os nomes das operações e o local em que cada requisição coloca sua tabela ou coluna estão no código-fonte do plugin na tag 484 (OpaAccessControl.java, OpaHighLevelClient.java). A política de máscaras em lote da documentação lê filterResources[i].catalogName, enquanto o exemplo de requisição da própria documentação aninha esses campos sob .column, de modo que, como impressa, ela não corresponderia. Requisições montadas nesses formatos vão para a sua política:

trino-requests.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Builds requests in the shape Trino 484's OPA plugin sends, and runs them through the platform's policy. The prose'spoints rest on the allow lines, which the example asserts are False, and on the GetRowFilters and GetColumnMask lines."""import jsonfrom lib import metadata, policyfrom lib.enforce import row_filter# The platform's policy, with a support agent added before anyone set their region (chapter 5's missing-region case).data = policy.data_document()data["platform"]["users"]["agent-new"] = {"groups": ["support"]}rego = policy.interpreter(data=data)described = metadata.load()def trino_request(user: str, operation: str, resource: dict | None = None) -> dict:    """A request in the shape Trino 484's OPA plugin sends (OpaAccessControl, OpaHighLevelClient)."""    action = {"operation": operation} | ({"resource": resource} if resource else {})    return {"context": {"identity": {"user": user, "groups": []}, "softwareStack": {"trinoVersion": "484"}}, "action": action}# Trino asks `allow` about every operation: ExecuteQuery before any query runs, AccessCatalog for each catalog it names.for operation, resource in [("ExecuteQuery", None), ("AccessCatalog", {"catalog": {"name": "platform"}})]:    allowed = policy.decide(trino_request("agent-a05", operation, resource), rego)["allow"]    # allow admits only SelectFromColumns, so Trino's checks before any query are denied    assert allowed is False    print(f"allow, {operation}, agent-a05:", allowed)# GetRowFilters names a table. The policy's row_filters rule on its own skips `allow` and its missing-attribute guard,# so for agent-new it returns no filter, which Trino reads as no filtering. The answer comes from the decision instead,# for the same read asked as SelectFromColumns: its filters in Trino's SQL, or a filter that keeps no rows.for user, schema, table in [("agent-a05", "support", "tickets"), ("instructor-17", "learning", "reviews"),                            ("agent-new", "support", "tickets")]:    request = trino_request(user, "GetRowFilters", {"table": {"catalogName": "platform", "schemaName": schema, "tableName": table}})    print(f"GetRowFilters, {user}, {schema}.{table}, the rule alone:",          json.dumps(policy.evaluate(rego, "data.platform.access.row_filters", request)))    decision = policy.decide(policy.request(user, f"{schema}.{table}", []), rego)    columns = {c.name: "" for c in described[f"{schema}.{table}"].columns.values()}    # no table alias: Trino applies the filter to the table itself, as a WHERE clause on it    filters = [{"expression": row_filter(rule, columns, table=None).sql("trino")} for rule in decision["row_filters"]]    # a denied read gets a filter that keeps no rows    print(f"GetRowFilters, {user}, {schema}.{table}, answered:", json.dumps(filters if decision["allow"] else [{"expression": "false"}]))# GetColumnMask names one column, under action.resource.column. The policy reads the columns of a SelectFromColumns# request instead, so it masks nothing here until the request is translated.column = {"catalogName": "platform", "schemaName": "crm", "tableName": "learners", "columnName": "email", "columnType": "varchar"}decision = policy.decide(trino_request("analyst-1", "GetColumnMask", {"column": column}), rego)print("GetColumnMask as sent, analyst-1, crm.learners.email:", json.dumps(decision["column_masks"]), decision["reasons"][0])translated = policy.request("analyst-1", "crm.learners", [column["columnName"]])print("GetColumnMask translated, analyst-1, crm.learners.email:", json.dumps(policy.decide(translated, rego)["column_masks"]))
Saídapython trino-requests.py
allow, ExecuteQuery, agent-a05: False
allow, AccessCatalog, agent-a05: False
GetRowFilters, agent-a05, support.tickets, the rule alone: [{"column": "support_region", "equals": "emea"}]
GetRowFilters, agent-a05, support.tickets, answered: [{"expression": "support_region = 'emea'"}]
GetRowFilters, instructor-17, learning.reviews, the rule alone: [{"column": "course_id", "in": [2, 75, 80, 87, 103, 134]}]
GetRowFilters, instructor-17, learning.reviews, answered: [{"expression": "course_id IN (2, 75, 80, 87, 103, 134)"}]
GetRowFilters, agent-new, support.tickets, the rule alone: []
GetRowFilters, agent-new, support.tickets, answered: [{"expression": "false"}]
GetColumnMask as sent, analyst-1, crm.learners.email: {} GetColumnMask is not an operation this policy allows
GetColumnMask translated, analyst-1, crm.learners.email: {"email": "pseudonymize"}

Apontada para o Trino sem alterações, a política negaria as verificações que o Trino faz primeiro, porque sua regra allow admite apenas SelectFromColumns. allow é falso para ExecuteQuery, que o Trino pergunta antes de qualquer consulta ser executada, e para AccessCatalog.

A regra row_filters não testa a operação, então responde GetRowFilters, mas, sozinha, ela pula allow e a guarda de atributo ausente do capítulo 5. Para agent-new, um agente de suporte que ainda não tem região, ela retorna [], que o Trino interpreta como ausência de filtragem. Portanto, a resposta precisa vir da decisão para a mesma leitura, feita como SelectFromColumns: seus filtros, escritos em SQL do Trino pelo mesmo row_filter que a reescrita usa, ou, quando nega a leitura, [{"expression": "false"}], que não mantém nenhuma linha.

GetColumnMask nomeia a coluna em action.resource.column, enquanto a política lê as colunas de uma requisição SelectFromColumns; assim, como enviada, ela não mascara nada e a política rejeita a operação; traduzida, ela recebe pseudonymize. Em produção, essas traduções, a verificação allow e o SQL do Trino pertencem a um módulo Rego ao lado da política, para que o OPA possa responder diretamente ao Trino. Nenhum servidor OPA é executado aqui, então o código mostra apenas o que esse módulo precisa retornar. Mais um elemento corresponde diretamente ao Trino: o filtro de consentimento lê crm.learners, que o assistente talvez não possa ler, e o Trino permite que um filtro carregue um identity sob o qual será executado, "de modo que um filtro pode ter como alvo uma coluna que o usuário solicitante não pode ver".

Desde a versão 1.9.0, a API Compile do OPA também pode escrever cláusulas SQL WHERE a partir de uma política, por avaliação parcial (OPA v1.9.0, Filtragem de dados com OPA), mas ela precisa de um servidor OPA, que os exemplos não executam.

Regra prática: Coloque a aplicação no motor que todas as ferramentas consultam, com uma única política para ele e para qualquer reescrita como a deste capítulo. Com o Trino, responda a toda operação sobre a qual o plugin pergunta, defina os dois URIs, de filtros de linhas e de máscaras de colunas (sem eles, o Trino não aplica filtros nem máscaras), e retorne filtros de linhas somente a partir de uma decisão que permita a leitura. Crie testes a partir dos formatos de requisição do código-fonte do plugin, e não dos exemplos de política da documentação.

Consultar em nome de alguém

Última alteração na edição 2026.11.31

Um assistente que responde perguntas a partir do armazém é mais um usuário da camada, com uma escolha a fazer: qual identidade a sua consulta deve carregar? O assistente de cursos, assistant-1, tem acesso próprio, para avaliações de aprendizes que consentiram. Quando ele responde a uma pessoa, precisa consultar como essa pessoa, para que a resposta contenha exatamente o que ela poderia ler por conta própria. A orientação da OWASP para aplicações com modelos de linguagem diz o mesmo: "Implemente a autorização nos sistemas a jusante, em vez de confiar em um LLM para decidir se uma ação é permitida ou não" (OWASP LLM06:2025). O assistente em si pertence a Assistentes de Dados na Prática; esta seção trata de suas consultas.

instructor-17 pergunta ao assistente como são as avaliações de seus cursos, e o assistente escreve uma consulta. A ferramenta obtém o usuário a partir da sessão autenticada, nunca a partir do modelo ou da conversa, de modo que nenhum prompt pode alterar em nome de quem a consulta é executada:

assistant-on-behalf.py Python 3.12.15 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · regopy 1.5.2 · sqlglot 30.33.0 Aprovado
"""Runs the course assistant's review query as instructor-17 and as assistant-1, through a tool that takes the user fromthe signed-in session. The prose's point rests on the reviews-behind-it lines for each user."""from lib import policyfrom lib.catalog import open_catalogfrom lib.enforce import Enforcerplatform = Enforcer(open_catalog(["crm.learners", "learning.reviews"]))courses = set(policy.data_document()["platform"]["instructor_courses"]["17"])     # instructor-17's own coursesdef query_tool(session_user: str):    """The tool the course assistant calls to query the warehouse. The model writes the SQL; the user it runs as comes    from the signed-in session, never from the model or the conversation."""    # the user is the session's; the SQL is all the model contributes    return lambda sql: platform.sql(sql, user=session_user).fetchall()# instructor-17 asks the assistant how their courses' reviews look. The assistant writes this query.question = "select course_id, count(*) as reviews, round(avg(rating), 2) as rating from learning.reviews group by all"for runs_as in ["instructor-17", "assistant-1"]:    answer = query_tool(runs_as)(question)    print(f"run as {runs_as}, courses in the answer:", len(answer))    print(f"run as {runs_as}, reviews behind it:", sum(reviews for _, reviews, _ in answer))    # each answer row is (course, reviews, rating), so row[0] is the course    mine = [row for row in answer if row[0] in courses]    print(f"run as {runs_as}, instructor-17's reviews behind it:", sum(reviews for _, reviews, _ in mine))
Saídapython assistant-on-behalf.py
run as instructor-17, courses in the answer: 6
run as instructor-17, reviews behind it: 69
run as instructor-17, instructor-17's reviews behind it: 69
run as assistant-1, courses in the answer: 130
run as assistant-1, reviews behind it: 436
run as assistant-1, instructor-17's reviews behind it: 7

A identidade com que a consulta é feita decide o que a resposta abrange. A identidade do próprio assistente está errada nos dois sentidos: mostra ao instrutor o que ele não pode ver, e oculta o que ele pode. Executada como instructor-17, a resposta abrange seus 6 cursos e 69 avaliações. Executada como o assistente, abrange 130 cursos, a maioria de outros instrutores, e apenas 7 das avaliações do instrutor, aquelas cujos autores consentiram com o treinamento de IA. O mesmo vale para a recuperação: um assistente fundamentado em texto governado precisa de "armazenamentos de vetores e de embeddings que levem em conta permissões" (OWASP LLM08:2025).

Regra prática: Execute as consultas de um assistente em nome da pessoa a quem ele responde, com essa identidade obtida da sessão autenticada, e deixe a camada aplicar a decisão dessa pessoa. Use a identidade própria do assistente apenas para trabalho que ele realiza para ninguém em especial, ou seja, não para uma pessoa específica, como um resumo noturno de avaliações consentidas para as páginas dos cursos, e registre as duas identidades no registro de auditoria. Quem constrói o conjunto de treinamento do assistente consulta em seu próprio nome, com a finalidade ai-training, como faz o capítulo 9.

O que dá errado em produção

Última alteração na edição 2026.11.27

Uma camada de imposição falha ao deixar passar uma leitura que ninguém testou, e a maioria dessas falhas parece respostas corretas:

  • SELECT * escapa em uma tabela ausente do esquema. qualify deixa a estrela sem expansão e não levanta erro algum. Negue toda tabela que o catálogo não contém e reconstrua o esquema sempre que o catálogo mudar.
  • Agregados vazam grupos pequenos. Uma célula com um único registro identifica a pessoa a que ele corresponde, e diferenças entre relatórios identificam pessoas em células que atingem qualquer mínimo, como o exemplo do relatório mostrou. Defina o mínimo e remova detalhamentos por atributos que o leitor não pode ler.
  • Junções e cópias trazem de volta colunas mascaradas. Um pipeline com acesso total, como o que grava marketing.audience, copia email para uma tabela protegida apenas pela própria classificação. Sem classificação, a cópia fica oculta de todos, como o teste de quem vê o quê mostrou; classificada internal por engano, ela é exibida a qualquer um que possa ler a tabela. O capítulo 4 propaga classificações ao longo da linhagem para pegar esse caso. Colunas não mascaradas também se reidentificam por meio de junções: Sweeney constatou que 87% da população dos EUA provavelmente é única com base em CEP, sexo e data de nascimento, nos dados do censo de 1990 (Sweeney, 2002), e Golle, contando novamente, constatou 61% nesses mesmos dados de 1990 e 63% nos de 2000 (Golle, 2006). Rocher e colegas estimam, a partir de um modelo ajustado a dados do censo, que 15 atributos demográficos tornariam únicas 99.98% das pessoas em Massachusetts (Rocher et al., 2019).
  • Leituras diretas de arquivos contornam a reescrita. read_parquet, um caminho em FROM e funções de tabela leem dados sem citar uma tabela. Negue-os na reescrita e desligue enable_external_access, que o DuckDB então não religa: "Cannot enable external access while database is running". lock_configuration mantém todas as outras configurações como a camada as deixou; defina-o depois que a conexão da camada estiver totalmente configurada (Securing DuckDB), e não na criação, pois o capítulo 8 inicia o registro de consultas do DuckDB depois disso. Quem puder ler os arquivos do armazém no armazenamento não precisa de SQL, por isso as permissões de armazenamento fazem parte da imposição.
  • A capitalização dos identificadores decide com o que um nome corresponde. Uma camada que comparasse nomes sem normalizá-los deixaria "LEARNERS", que o DuckDB resolve para learners, alcançar a tabela bruta, como a primeira seção mostrou. Normalize com o dialeto do motor que executa a consulta antes de comparar qualquer nome.
  • Mensagens de erro imprimem valores. Os erros de conversão do DuckDB incluem o valor. A reescrita da tabela faz dele um valor mascarado, e a restrição de cada coluna mantém linhas descartadas fora do alcance, mas a mensagem ainda chega ao usuário, a menos que algo a impeça. Devolva um erro genérico na fronteira do serviço, como lib.enforce.answer faz, e registre a mensagem do motor apenas onde somente a equipe de plataforma a lê, à parte do log de auditoria, que o capítulo 8 mantém livre de valores. O PostgreSQL alerta que planos e tempos continuam sendo canais encobertos mesmo atrás de uma barreira de segurança (PostgreSQL 18, Rules and Privileges).
  • O DuckDB não é uma fronteira de segurança. "O DuckDB executa SQL com todos os privilégios do usuário que o executa, da mesma forma que um shell ou um interpretador de scripts" (Securing DuckDB). Uma reescrita dentro do mesmo processo protege os dados apenas enquanto os usuários não conseguirem alcançar o DuckDB por nenhum outro caminho. Trate a camada deste capítulo como um modelo testado do que um motor como o Trino impõe, e faça a imposição nele em produção.

O que este capítulo decidiu

Última alteração na edição 2026.11.27
  • A aplicação das regras substitui tabelas, não colunas. Cada tabela do catálogo se torna uma subconsulta gerada a partir da decisão; a reescrita de referências a colunas é mantida apenas para mostrar que ela vaza.
  • A camada falha de modo seguro (nega por padrão). Suas fontes são uma lista de permissões de tabelas do catálogo, CTEs no escopo e subconsultas. Ela nega funções com efeitos colaterais, parâmetros e qualquer coisa que não seja uma única consulta. Colunas que uma consulta não lê são tipadas como NULLs, e as que ela lê são condicionadas aos filtros de linha.
  • Os usuários recebem um único erro genérico de answer, e a mensagem do DuckDB vai para a equipe da plataforma.
  • As máscaras são SQL em um só lugar. A política nomeia as máscaras; lib.enforce escreve o SQL delas. Pseudônimos recebem chave (HMAC) com um segredo que só a camada possui, passada como parâmetro.
  • Os filtros de linha são construídos a partir de dados, com valores como literais. O consentimento é uma semijunção que a camada executa com o próprio acesso, e um consentimento desconhecido conta como não.
  • Quem vê o quê é testado como consultas: os casos do capítulo 5 passam pela camada a cada alteração.
  • Relatórios retêm grupos abaixo do tamanho mínimo de grupo, 11 em governance/enforcement.toml, e não fazem detalhamento por atributos que seus leitores podem não ter permissão de ler.
  • Assistentes consultam como a pessoa que atendem, com a identidade obtida da sessão.
  • Em produção, o motor aplica as regras: Trino com OPA, a partir da mesma política, com ambos os URIs definidos e os filtros de linha respondidos apenas por uma decisão permitida. Uma camada só é tão segura quanto os seus testes.

Este capítulo, nesta edição

Edição 2026.11.31Exemplos aprovados em 19 de nov de 202616 de 16 exemplos exemplos deste capítulo passam

Traduzido do livro em inglês, edição 2026.11.31.

Citar esta seção

Formato

Cada formato cita o livro em inglês, que esta tradução acompanha.

Todos os formatos citam esta edição. Seu link abre a edição atual, em que o título de cada seção indica quando seu texto foi alterado pela última vez. As datas de acesso e de recuperação são o dia em que você abre esta página.

Nesta página

Capítulo 6 de 10: Aplicando políticas em consultas

  1. Encontre todas as tabelas e colunas que uma consulta lê
  2. Permitir apenas tabelas do catálogo, CTEs e subconsultas
  3. Mascarar referências a colunas vaza dados
  4. Substitua cada tabela por uma subconsulta filtrada e mascarada
  5. Escreva cada máscara como SQL em um só lugar
  6. Crie filtros de linha a partir dos dados da decisão
  7. Condicione cada coluna aos filtros de linha
  8. Teste quem vê o quê executando consultas
  9. Ocultar grupos pequenos em relatórios
  10. Entregue as mesmas políticas a um motor que as aplique
  11. Consultar em nome de alguém
  12. O que dá errado em produção
  13. O que este capítulo decidiu

Voltar ao topoTodos os capítulos