Policy e Egress do OpenShell: Hands-On no Amazon EKS
Por Fabio Douek
Ir para seção
- Visão Geral
- Arquitetura
- Configuração
- Passo 1: Um servidor de eco
- Passo 2: Policies e profiles
- Testes
- Teste 1: Negação por padrão, e como é uma negação
- Teste 2: Regras por binário, e pinning
- Teste 3: Regras L7: audit, enforce e um bug
- Teste 4: Atualizações ao vivo
- Teste 5: Terminação de TLS
- Teste 6: Credenciais como placeholders
- Teste 7: Formas de sair
- Teste 8: Rotação e revogação
- Teste 9: O prover no CI
- Teste 10: Logs
- Resumo dos Resultados
- O Que o Policy Engine Não Resolve
- Limpeza
- Veredito
Explica (TLDR) como se eu fosse...
O robô na caixa de areia só consegue falar com o lado de fora através de um adulto, e o adulto tem uma lista de quem o robô pode chamar e qual ferramenta ele tem que usar. O robô também nunca recebe as chaves de verdade, só chaves de mentirinha que o adulto troca pelas de verdade na porta.
A lista funciona bem, mas você precisa escrevê-la com cuidado. Se você só disser "por favor, só leia", o adulto deixa a escrita passar e só cochicha sobre isso, e uma palavra escrita de um jeito estranho pode fazer ele abrir a porta errada.
Este post testa como o OpenShell controla o acesso de rede e as credenciais de um agente no Amazon EKS, usando credenciais reais do GitHub e da Anthropic que o agente recebe apenas como placeholders. Os controles funcionam em grande parte como documentado, incluindo o bloqueio dos endpoints de metadata da nuvem, independentemente do que a policy diga.
Para fins de due diligence: as regras HTTP ficam em audit por padrão, o que deixa passar um request que viola a regra e o registra como permitido; um bug em aberto pode reescrever o path de um request silenciosamente; uma credencial rotacionada continua funcionando para processos que já estavam rodando; e o uso da credencial em si não é registrado em log.
Eu examinei os controles de egress do OpenShell uma camada por vez: resolução de nomes, verificação de conexão por programa, regras de método e path HTTP, interceptação de TLS e substituição de credenciais. A maioria das respostas foi saudável e específica, com um 403 claro ou uma conexão recusada.
Achados a registrar: a configuração audit é o padrão e deixa violações passarem com apenas uma nota discreta no log, um bug de encoding de path altera requests sem deixar rastro, e rotacionar uma credencial não alcança processos que já estão rodando. Um programa adulterado é detectado e bloqueado.
Existe um conforto real em um design no qual o ambiente do agente não guarda nenhum segredo: ele só pode pedir, e o supervisor decide. Ver um push para o GitHub e uma chamada ao modelo funcionarem com placeholders fez essa promessa parecer concreta, e não teórica.
O atrito está nos padrões. Uma regra que só audita parece proteger você, e o log continua tranquilo enquanto ela deixa escritas passarem. Nomear essa lacuna cedo, como time, é mais fácil do que descobri-la depois de um incidente.
Pense no supervisor como um técnico de som que decide qual instrumento pode tocar em qual canal, e só conecta o sinal real na mesa. O agente toca com cabos falsos; a plateia ouve o som de verdade, e só nos canais para onde ele foi roteado.
A passagem de som encontrou algumas notas desafinadas. A configuração padrão só escuta e nunca silencia, um caractere estranho em um caminho muda a música que é tocada, e trocar um cabo no meio do show não chega aos músicos que já estavam no palco.
A proposta de valor é simples: os agentes recebem o acesso de que precisam com apenas placeholders no ambiente. Um push para o GitHub e uma chamada à API de um modelo rodaram com placeholders, as credenciais se recusaram a ir para o host errado, e os endpoints de metadata da nuvem continuam bloqueados independentemente do que a policy diga.
O posicionamento honesto: escreva policies com o enforcement ligado, nomeie exatamente os programas permitidos e verifique-as com o prover no CI. Com esses hábitos, este é um control plane forte para o egress de agentes no Kubernetes.
Visão Geral
O OpenShell, projeto CNCF Sandbox desde 2026-09-26, coloca cada agente em um sandbox que não consegue abrir uma conexão de rede sozinho. A parte 1 explicou o design, a parte 2 instalou o OpenShell 0.1.6 no Amazon EKS 1.37, e a parte 3 mostrou que um sandbox com a policy padrão não alcança absolutamente nada. Este post, parte 4 de 6, abre a rede uma regra de cada vez.
Um agente que não alcança nada não serve para muita coisa. Ele precisa de um índice de pacotes, de um host Git, de uma API de modelo e das credenciais para alguns deles. A resposta do OpenShell tem duas metades. Uma policy diz qual binário pode alcançar qual host e porta e, no caso de HTTP, qual método e path. Um provider guarda uma credencial, e o agente recebe um placeholder em vez do valor; o supervisor só troca o placeholder pelo valor real a caminho de um endpoint ao qual a credencial está vinculada.
Eu testei as duas metades no EKS com dez scripts: negação por padrão, regras por binário, regras REST de L7, atualizações ao vivo, terminação de TLS, credenciais (do GitHub e da Anthropic, reais), formas de sair do sandbox, rotação, o prover de policies e os logs. A maior parte funciona como documentado. Uma parte não funciona, e alguns padrões merecem atenção antes de você escrever a sua primeira policy. A parte 5 faz o mesmo para credenciais da AWS e SigV4, e a parte 6 faz um stress test no cluster.
Arquitetura
A única saída do agente é o seu próprio supervisor. A NetworkPolicy não dá ao Pod de workload nenhuma regra de egress: é o supervisor quem abre a conexão com o Pod, e o Sandbox Protocol roda sobre essa conexão. A parte 2 testou essa cerca e encontrou lacunas (um Pod cercado ainda alcança o IP do próprio node), então a primeira camada é o runtime. Dentro do Pod, o runtime do OpenShell roda como PID 1 e intercepta todo connect() e toda consulta DNS que o agente faz. Ele identifica o binário que fez a chamada e a repassa ao supervisor pelo Sandbox Protocol. Ele mesmo não decide nada.
O supervisor toma todas as decisões, nesta ordem:
- DNS da policy. Um nome recebe um endereço sintético de
198.18.0.0/15. O endereço real fica no supervisor, que depois se conecta ao endereço que ele mesmo resolveu e fixou. - L4. Binário, host e porta precisam corresponder a uma regra. O binário é a visão que o kernel tem do executável (
/proc/<pid>/exe), e o SHA-256 dele é registrado na primeira vez que ele se conecta. Uma negação aqui chega ao agente comoEACCESnoconnect(). - TLS. A menos que um endpoint diga
tls: skip, o supervisor termina o TLS com uma CA criada para o sandbox, para conseguir ler o request. - L7. Para endpoints com
protocol: rest, o método e o path precisam corresponder. Uma negação é um HTTP 403 com um corpo JSON. - Credenciais. Placeholders em headers, Basic auth, query strings e paths são substituídos por valores reais, mas apenas para um provider vinculado a este endpoint.
- Upstream. O supervisor abre a conexão real, com TLS real.
As policies têm uma metade estática e uma metade dinâmica. As seções de filesystem, Landlock e processos ficam fixas quando o sandbox inicia. A seção network_policies pode mudar enquanto ele roda, com openshell policy set (uma policy inteira) ou openshell policy update (um endpoint ou uma regra de cada vez). Os providers adicionam as próprias regras, chamadas _provider_<name>, a partir de um provider profile: um arquivo YAML com as variáveis de ambiente da credencial, os endpoints aos quais ela está vinculada e os binários que podem usá-los. O gateway não vem com nenhum profile; você os importa.
Configuração
Tudo roda no cluster da parte 2: dois nodes m7i.2xlarge, OpenShell 0.1.6, sandboxes em runc, e a CLI conectada por um kubectl port-forward.
Passo 1: Um servidor de eco
Os testes precisam de um destino que mostre o que realmente chega. O 00_echo.sh faz o deploy de um servidor Python de 40 linhas no namespace echo, que responde a todo request com o método, o path e os headers em JSON, e transmite uma linha por segundo em /slow. Ele roda a imagem de workload da série a partir do ECR, como usuário não root, sob o Pod Security restricted:
./00_echo.sh
# echo server ready: http://echo.echo.svc.cluster.local/
Passo 2: Policies e profiles
As policies dos testes são policies completas em policies/ (os testes 1, 7 e 10 compartilham uma, e o Teste 6 preenche um template), mais as do prover, em prover/. Todas começam do mesmo jeito, porque um sandbox em execução recusa uma policy que remova um path do filesystem ou altere o Landlock. A minha primeira policy do GitHub deixou /bin de fora, e o policy set respondeu filesystem read_only path '/bin' cannot be removed on a live sandbox:
version: 1
filesystem_policy:
include_workdir: true
read_only: [/bin, /usr, /lib, /proc, /dev/urandom, /etc, /var/log]
read_write: [/tmp, /dev/null]
landlock:
compatibility: best_effort
network_policies:
echo:
name: echo-read-only
endpoints:
- { host: echo.echo.svc.cluster.local, port: 80, protocol: rest, access: read-only, enforcement: enforce }
binaries:
- { path: /usr/bin/curl }
O profiles/ guarda três provider profiles: cópias dos exemplos de GitHub e Anthropic do OpenShell com binaries alterado para os paths da minha imagem, e o echo-demo, que vincula um token fictício ao servidor de eco. Os arquivos de exemplo avisam para fazer exatamente isso: “binaries é o controle de menor privilégio … então precisa nomear os paths da sua imagem.”
Testes
Teste 1: Negação por padrão, e como é uma negação
O 01_deny_and_dns.sh inicia um sandbox cuja policy nomeia um único endpoint: o servidor de eco, somente leitura, para o curl. Depois ele olha o DNS, um host que a policy não nomeia e um método que ela não permite.
$ openshell sandbox create --name deny --policy policies/echo-read-only.yaml
$ DNS inside the sandbox
echo.echo.svc.cluster.local 198.18.0.2
pypi.org 198.18.0.3
$ a host the policy doesn't name: the connection is refused (EACCES)
curl: curl: (7) Failed to connect to pypi.org port 443 after 1 ms: Couldn't connect to server
python3: PermissionError: [Errno 13] Permission denied
$ an allowed host, a method the policy doesn't allow: HTTP 403 with a JSON body
HTTP/1.1 403 Forbidden
X-OpenShell-Policy: echo
{"error":"policy_denied","layer":"l7","rule":"POST /items","detail":"POST /items not permitted by policy"}
GET /items -> 200
$ openshell logs deny
NET:REFUSE [MED] DENIED pypi.org [reason:policy_dns_ineligible]
NET:OPEN [MED] DENIED /usr/bin/python3.12(0) -> pypi.org:443 [reason:transparent_tcp_policy_denied]
NET:OPEN [INFO] ALLOWED /usr/bin/curl(0) -> echo.echo.svc.cluster.local:80 [policy:echo engine:opa]
HTTP:POST [MED] DENIED POST http://echo.echo.svc.cluster.local/items [policy:echo engine:l7] [reason:L7_REQUEST deny POST echo.echo.svc.cluster.local:
NET:OPEN [INFO] ALLOWED /usr/bin/curl(0) -> echo.echo.svc.cluster.local:80 [policy:echo engine:opa]
HTTP:GET [INFO] ALLOWED GET http://echo.echo.svc.cluster.local/items [policy:echo engine:l7]
$ openshell logs deny --level warn
OCSF events: 0
WARN lines: 2 (the network proxy's own log, L4 denials only)
[openshell_supervisor_network::proxy] Denied staged transparent connection destination=198.18.0.3:443 reason=endpoint pypi.org:443 is not allowed by a
[openshell_supervisor_network::proxy] Denied staged transparent connection destination=198.18.0.3:443 reason=endpoint pypi.org:443 is not allowed by a
Três coisas aqui.
O DNS responde para nomes fora da policy. O pypi.org não está na policy, mas mesmo assim recebe um endereço sintético de 198.18.0.0/15 (alguns nomes, como localhost e hostnames de metadata, são recusados de cara). O OpenShell coloca em staging os nomes que não aprovou, para que a conexão seguinte possa ser negada com o nome do binário no log e para que o policy advisor possa rascunhar uma regra a partir dela. A linha NET:REFUSE do log (policy_dns_ineligible) é o registro, no momento do DNS, de que o nome não está aprovado; a consulta é respondida mesmo assim. O DNS não é uma forma de saber o que é permitido.
Dois formatos de negação. Um host ou binário que a policy não permite falha no connect() com EACCES: o curl reporta “Couldn’t connect to server”, o Python levanta PermissionError: [Errno 13]. Um host permitido com um request que as regras L7 recusam recebe um HTTP 403 com um header X-OpenShell-Policy e um corpo JSON que nomeia a policy, a regra e a camada. Um agente consegue agir com base no segundo; o primeiro parece um erro de rede.
--level warn esconde todos os eventos OCSF. O OpenShell registra as suas decisões como eventos OCSF (Open Cybersecurity Schema Framework) no nível INFO, então um filtro warn descarta todos eles, inclusive as negações. O que sobra são os warnings do próprio proxy de rede, que por acaso cobrem as negações L4, mas não as L7. O tutorial do GitHub na documentação diz isso (“não os filtre com --level warn”); ainda assim, é um filtro ao qual é fácil recorrer.
Teste 2: Regras por binário, e pinning
Uma regra nomeia binários, além de hosts. O 02_binaries.sh permite o pypi.org para /usr/bin/curl (e, para a verificação de pinning, /sandbox/bin/fetch) e testa três binários:
$ openshell sandbox create --name bins --policy policies/curl-pypi.yaml
$ the same host from three binaries
/usr/bin/curl 200
python3 urllib.error.URLError: <urlopen error [Errno 13] Permission denied>
/sandbox/curl-copy (a copy) 000
NET:OPEN [MED] DENIED /usr/bin/python3.12(0) -> pypi.org:443 [reason:transparent_tcp_policy_denied]
NET:OPEN [MED] DENIED /sandbox/curl-copy(0) -> pypi.org:443 [reason:transparent_tcp_policy_denied]
why python3 is denied:
reason=binary '/usr/bin/python3.12' not allowed in policy 'pypi' (ancestors: [], cmdline: [])
$ binary pinning: /sandbox/bin/fetch is allowed by path
fetch, first use 200
fetch, second use 200
sha256 1ccbd3dae948 /usr/bin/curl
sha256 95b24cd3df3a /sandbox/bin/fetch
fetch, one byte changed 000
WARN: binary integrity violation: /sandbox/bin/fetch executable changed
OCSF: NET:OPEN [MED] DENIED -(0) -> pypi.org:443 [reason:transparent_tcp_identity_unavailable]
O python3 é negado, e o warning mostra por que ele seria negado mesmo que eu tivesse permitido /usr/bin/python3: a regra precisa nomear o executável real, /usr/bin/python3.12, porque o OpenShell compara com o /proc/<pid>/exe do kernel, não com um symlink. Uma cópia do curl em outro path é um binário diferente.
A segunda metade é o pinning de binário. A policy também permite /sandbox/bin/fetch, uma cópia do curl. A primeira conexão dele registra o SHA-256 do arquivo; depois que eu acrescentei um byte (as duas linhas sha256 foram capturadas depois dessa mudança, daí os hashes diferentes), o mesmo path foi recusado com “binary integrity violation … executable changed”. É isso que impede um agente de substituir um binário permitido por um binário próprio.
A negação aparece nos logs duas vezes: uma linha WARN do proxy que diz “binary integrity violation”, e um evento OCSF. O resumo de uma linha do OCSF nomeia o binário como - com o motivo transparent_tcp_identity_unavailable, porque a verificação de identidade falhou antes de um nome ser conhecido; a mensagem do evento JSON traz o texto de integridade. Se você cria alertas para adulteração, filtre por esse motivo, não pelo path do binário. A primeira versão do meu script fazia grep pelo path, não encontrou nada e, por um momento, me convenceu de que não havia evento nenhum.
Teste 3: Regras L7: audit, enforce e um bug
Para HTTP, uma regra pode ir além de host e porta. O protocol: rest liga a inspeção de requests, o access escolhe um preset (read-only é GET, HEAD e OPTIONS) ou o rules lista métodos e paths, e o enforcement diz se uma violação é bloqueada. O 03_l7_rules.sh roda os mesmos requests contra três versões da regra do servidor de eco:
$ openshell sandbox create --name l7 --policy policies/echo-audit.yaml (read-only, no enforcement field)
GET /items 200 echo got: GET /items
POST /items 200 echo got: POST /items
HTTP:GET [INFO] ALLOWED GET http://echo.echo.svc.cluster.local/items [policy:echo engine:l7]
HTTP:POST [INFO] ALLOWED POST http://echo.echo.svc.cluster.local/items [policy:echo engine:l7]
$ openshell policy set l7 --policy policies/echo-enforce.yaml (enforcement: enforce)
GET /items 200 echo got: GET /items
POST /items 403 policy_denied (l7)
$ openshell policy set l7 --policy policies/echo-rules.yaml (GET /public/**, DELETE /objects/*)
GET /public/report 200 echo got: GET /public/report
GET /private/report 403 policy_denied (l7)
GET /public/../private/report 403 policy_denied (l7)
GET /public/%2e%2e/private/report 403 policy_denied (l7)
DELETE /objects/backup 200 echo got: DELETE /objects/backup
DELETE /objects/backup%3Bold 200 echo got: DELETE /objects/backup
HTTP:DELETE [INFO] ALLOWED DELETE http://echo.echo.svc.cluster.local/objects/backup [policy:echo engine:l7]
O padrão é audit. Com access: read-only e sem o campo enforcement, o POST passou, e o log de uma linha o registrou como ALLOWED no nível INFO. O evento OCSF em JSON (Teste 10) até diz L7_REQUEST audit POST ... not permitted by policy na mensagem, mas a ação, a disposição e a severidade dele são Allowed, Allowed e Informational, então qualquer coisa que filtre por esses campos vê um request comum. Se você escreve access: read-only e espera somente leitura, adicione enforcement: enforce. O prover (Teste 9) se recusa a dar aval a regras em modo audit, o que é uma dica.
Os paths são normalizados antes da comparação. /public/../private/report e a forma dele com percent-encoding foram ambos comparados como /private/report e negados. Bom.
Um ponto e vírgula codificado muda o request. DELETE /objects/backup%3Bold chegou ao servidor de eco como DELETE /objects/backup: um objeto diferente. O log mostra o path reescrito como permitido, e nada diz que ele mudou. Esse é o #3902, aberto na 0.1.6: o canonicalizador de paths decodifica %3B para ; e depois o remove como parâmetro de path. Até isso ser corrigido, um agente pode ser levado a agir sobre um recurso que ele não nomeou. A issue menciona desligar a remoção de parâmetros como workaround, mas na 0.1.6 essa é uma opção interna, não um campo da policy: um endpoint com strip_path_parameters é rejeitado como campo desconhecido.
Teste 4: Atualizações ao vivo
A metade de rede de uma policy muda enquanto o sandbox roda. Com que rapidez? Por padrão, os supervisores fazem polling da configuração no gateway a cada 10 segundos. Uma configuração do gateway, config_delivery_mode = "push", a envia em vez disso pela sessão já existente do supervisor. O 04_live_updates.sh mede os dois: remove o pypi.org da policy, adiciona de volta sem --wait e repete o curl até ele passar.
$ openshell sandbox create --name live --policy policies/echo-l4.yaml (delivery: poll, the default)
$ openshell policy update live --add-endpoint pypi.org:443 --binary /usr/bin/curl (no --wait)
run 1: allowed 7.9 s after the update call
run 2: allowed 12.5 s after the update call
run 3: allowed 7.9 s after the update call
$ a 30-second download from the echo server, and an unrelated policy update 8 s in
lines received: 9 of 30
curl: (18) transfer closed with outstanding read data remaining
exit 18
$ helm upgrade openshell --reuse-values --set gatewayConfig.openshell\.gateway.config_delivery_mode=push
gateway back after 24.0 s
$ openshell policy update live --add-endpoint pypi.org:443 --binary /usr/bin/curl (delivery: push)
run 1: allowed 1.3 s after the update call
run 2: allowed 1.3 s after the update call
run 3: allowed 1.3 s after the update call
$ helm upgrade openshell --reuse-values --set gatewayConfig.openshell\.gateway.config_delivery_mode=poll
gateway.toml now: config_delivery_mode = "poll"
Com polling, a nova regra levou de 7,9 a 12,5 segundos para funcionar; com push, 1,3 segundo todas as vezes. Esses tempos incluem um round trip de sandbox exec por tentativa; a parte 6 mede só a entrega. O push vem desligado por padrão, então conte com cerca de 10 segundos até que uma regra que você adiciona para um agente que está esperando entre em vigor.
A troca exige uma mudança no Helm, e o chart tem duas armadilhas. Ele recusa gatewayConfig.openshell.gateway.config_delivery_mode como map aninhado (“defines “openshell.gateway” both as a nested map and a dotted top-level table”); a chave precisa ser o nome da tabela com pontos, que o --set escreve como gatewayConfig.openshell\.gateway.config_delivery_mode. E reverter com =null sob --reuse-values deixou push no gateway.toml renderizado nas minhas execuções, então o script define poll explicitamente e verifica o resultado.
A parte do meio da saída importa mais. Um download em streaming de 30 segundos do servidor de eco parou depois de 9 linhas quando eu adicionei uma regra sem relação: curl exit 18, “transfer closed with outstanding read data remaining”. Isso está documentado: toda nova revisão de policy fecha as conexões abertas sob a anterior, inclusive as de longa duração. É a escolha segura, já que uma conexão não pode sobreviver à regra que a permitiu, mas significa que uma mudança de policy interrompe todos os streams do sandbox, não só os que ela afeta. Agentes com streams de modelo de longa duração ou WebSockets vão ver erros sempre que a policy mudar, e uma issue aberta relata que uma renovação rotineira do token de um provider faz o mesmo (#4945).
Teste 5: Terminação de TLS
Para ler requests e trocar credenciais, o supervisor precisa enxergar dentro do TLS. Ele cria uma CA para cada sandbox, emite um certificado por host na hora e aponta as variáveis de ambiente usuais para o bundle da CA. O 05_tls.sh verifica quais ferramentas confiam nela:
$ openshell sandbox create --name tls --policy policies/tls.yaml
$ the certificate curl sees for pypi.org
subject: CN=pypi.org
issuer: CN=OpenShell Sandbox CA; O=OpenShell
$ the sandbox CA, and the variables that point at it
subject=CN = OpenShell Sandbox CA, O = OpenShell
notAfter=Jan 1 00:00:00 4096 GMT
CURL_CA_BUNDLE=/run/openshell-supervisor-ca/material/ca-bundle.crt
DENO_CERT=/run/openshell-supervisor-ca/material/ca.crt
GIT_SSL_CAINFO=/run/openshell-supervisor-ca/material/ca-bundle.crt
NODE_EXTRA_CA_CERTS=/run/openshell-supervisor-ca/material/ca.crt
REQUESTS_CA_BUNDLE=/run/openshell-supervisor-ca/material/ca-bundle.crt
SSL_CERT_FILE=/run/openshell-supervisor-ca/material/ca-bundle.crt
AWS_CA_BUNDLE: not set
$ each tool, as is and without the variable it reads
as is without the variable
curl (CURL_CA_BUNDLE, SSL_CERT_FILE) ok SSL certificate problem: self-signed certificate in certificate chain
python3 (SSL_CERT_FILE) ok CERTIFICATE_VERIFY_FAILED
git (GIT_SSL_CAINFO) ok server certificate verification failed
AWS CLI 2.39 (REQUESTS_CA_BUNDLE) ok CERTIFICATE_VERIFY_FAILED
O certificado que o curl vê para o pypi.org é emitido pela “OpenShell Sandbox CA”. Todas as ferramentas que eu testei confiam nela de cara, por meio de uma das seis variáveis que o OpenShell define, e falham sem a sua variável:
- o curl lê
CURL_CA_BUNDLEouSSL_CERT_FILE, - o módulo
ssldo Python lêSSL_CERT_FILE, - o git lê
GIT_SSL_CAINFO, - a AWS CLI 2.39 lê
REQUESTS_CA_BUNDLEparaaws s3 lse outras chamadas comuns.
A pesquisa para esta série dizia que a AWS CLI precisaria de AWS_CA_BUNDLE, que o OpenShell não define. Para aws s3 ls, não precisa: REQUESTS_CA_BUNDLE basta. Mas o aws s3 cp pode escolher o cliente de transferência CRT da CLI, que lê apenas AWS_CA_BUNDLE, e então falha no TLS sem essa variável. A parte 5 tem os detalhes; a versão curta é definir AWS_CA_BUNDLE=/run/openshell-supervisor-ca/material/ca-bundle.crt em todo sandbox que roda a AWS CLI. Use o path literal: $REQUESTS_CA_BUNDLE não seria expandido no ENV de uma imagem nem no sandbox create --env.
Dois detalhes: o certificado da CA é válido até o ano 4096, e a chave privada nunca entra no workload; quem a guarda é o supervisor. Ferramentas que trazem a própria lista de CAs e ignoram essas variáveis (alguns binários Go, Java com o próprio trust store) precisam de configuração, ou de um endpoint com tls: skip, o que também desliga as regras L7 e a substituição de credenciais para aquele endpoint.
Teste 6: Credenciais como placeholders
Esta é a feature que diferencia o OpenShell de um simples proxy de egress. O 06_credentials.sh cria três providers a partir do meu ambiente: um fine-grained token do GitHub com acesso a um único repositório privado, uma API key da Anthropic e um token fictício para o servidor de eco. Os valores vão do ambiente do meu shell para o gateway (--credential GITHUB_TOKEN lê a variável; o valor nunca aparece em uma linha de comando) e, de lá, para nenhum lugar que o agente consiga ver.
$ openshell profile import -f profiles/{github,anthropic,echo-demo}.yaml
NAME TYPE CATEGORY SOURCE SCOPE
anthropic provider INFERENCE user workspace
echo-demo provider OTHER user workspace
github provider SOURCE CONTROL user workspace
$ openshell provider create --type github|anthropic|echo-demo --credential <KEY> (values read from the environment)
✓ Created provider e-github
✓ Created provider e-anthropic
✓ Created provider e-echo
$ openshell sandbox create --name creds --provider e-github --provider e-anthropic --provider e-echo --policy github-push.yaml
$ what the sandbox holds
GITHUB_TOKEN openshell:resolve:env:v4243678679748032648_GITHUB_TOKEN
ANTHROPIC_API_KEY openshell:resolve:env:v4243678679748032648_ANTHROPIC_API_KEY
ECHO_TOKEN openshell:resolve:env:v4243678679748032648_ECHO_TOKEN
$ what the echo server receives (a dummy token)
sent: Bearer openshell:resolve:env:v42436786797480326...
got: Bearer demo-token-1
$ GitHub: gh and git are in the provider profile
gh api user: User
git ls-remote: 47 refs
curl api.github.com: 000
python3 (own rule): 200
$ git push to a new branch, then delete it (allowed for this one repository by the sandbox policy)
branch on GitHub after push: 1
branch on GitHub after delete: 0
$ a placeholder sent where it isn't bound, and a spoofed Host header
GitHub placeholder to the echo server: {"error":"credential_endpoint_mismatch","message":"Credential is not authorized for this request endpoint"}
Host: api.github.com to the echo server: {"error":"request_authority_mismatch","message":"HTTP request authority does not match the authorized tunnel endpoint"}
$ Anthropic: a Messages API call with the placeholder key
model: claude-haiku-5-5
reply: hello from an OpenShell sandbox
tokens: 29 in, 15 out
$ openshell logs creds (credential decisions)
FINDING:BLOCKED [HIGH] "Provider credential used at an unauthorized endpoint" [type:openshell.provider_credential.endpoint_mismatch]
HTTP:GET [HIGH] DENIED GET [policy:_provider_e_echo engine:request-authority] [reason:request_authority_mismatch]
FINDING:BLOCKED [HIGH] "HTTP request authority does not match the authorized tunnel endpoint" [type:openshell.http.request_authority_mismatc
HTTP:POST [INFO] ALLOWED POST https://api.anthropic.com/v1/messages [policy:_provider_e_anthropic engine:l7]
Seguindo a ordem:
O sandbox guarda placeholders. Cada variável é openshell:resolve:env:v<revision>_<NAME>. É isso que um agente comprometido encontraria no seu ambiente, em /proc ou em qualquer coisa que ele escreva.
O destino recebe o valor real. O servidor de eco, vinculado ao token fictício, recebeu Bearer demo-token-1. O supervisor fez a troca no caminho de saída. Isso tem dois lados: o servidor de eco devolveu o valor na resposta, e o sandbox o leu. Qualquer endpoint permitido que ecoe ou armazene o que recebe pode devolver uma credencial real ao agente; a parte 5 cobre uma fraqueza conhecida desse tipo para credenciais da AWS.
O GitHub funciona pelos binários do profile. O gh api user e o git ls-remote usaram o token do GitHub sem conhecê-lo. O curl com o mesmo placeholder não chegou a lugar nenhum: o profile do GitHub permite gh e git, não curl. O git envia o token como HTTP Basic auth, que o supervisor decodifica, resolve e codifica de novo.
O binding é por endpoint, não por binário. Eu dei ao python3 uma regra própria para api.github.com na policy do sandbox, e o Python usou o placeholder do GitHub com sucesso. O provider nunca nomeou o Python. A documentação do OpenShell diz isso claramente: a resolução estática de placeholders tem escopo de endpoint, e a injeção de credenciais com escopo de binário está no roadmap. Até lá, qualquer binário que qualquer regra deixe alcançar um endpoint vinculado pode usar a credencial.
Escritas precisam de uma policy, não de outro token. O profile permite apenas clone e fetch. Uma segunda regra na policy do sandbox permite git-receive-pack para um repositório, e o push para uma branch descartável passou; o script deletou a branch em seguida. O mesmo token continuaria sendo recusado em um push para qualquer outro repositório.
Os placeholders não viajam. O placeholder do GitHub enviado ao servidor de eco recebeu um 403 credential_endpoint_mismatch, então um agente não consegue vazar uma credencial enviando o placeholder dela para um servidor que ele controla. Um request para o servidor de eco com Host: api.github.com recebeu um 403 request_authority_mismatch, vindo de uma verificação separada: o header Host precisa corresponder ao destino real da conexão, então um header forjado também não consegue puxar a credencial de outro host.
Anthropic. Uma chamada à Messages API para o claude-haiku-5-5 com a chave placeholder retornou a resposta que eu pedi.
Teste 7: Formas de sair
No EKS, os destinos interessantes estão por perto: o serviço de metadata da instância, o agente do EKS Pod Identity, o kubelet, a API do Kubernetes, o próprio node. O 07_getting_out.sh tenta cada um e adiciona uma regra de policy onde ela ajudaria um atacante. A tabela depois da saída resume tudo.
Saída: 07_getting_out.sh
$ openshell sandbox create --name out --policy policies/echo-read-only.yaml
$ policy update --add-endpoint for link-local addresses
169.254.169.254:80 (instance metadata) refused: proposed rule endpoint host '169.254.169.254' is an always-blocked address
169.254.170.23:80 (Pod Identity agent) refused: proposed rule endpoint host '169.254.170.23' is an always-blocked address
allowed-ip=169.254.0.0/16 refused: proposed rule contains always-blocked `allowed_ips` entry '169.254.0.0/16'
$ the kubelet on the node, allowed by policy
add <node-ip>:10250 Policy version 2 loaded
curl https://<node-ip>:10250/pods 000
reason=port 10250 is a blocked control-plane port
$ direct IPs and other ports
curl https://1.1.1.1/ (not in policy) 000
add 1.1.1.1:443 Policy version 3 loaded
curl https://1.1.1.1/ 301
python3 -> <node-ip>:22 PermissionError: [Errno 13] Permission denied
$ UDP
sendto 8.8.8.8:53 OSError: [Errno 89] Destination address required
sendto <node-ip>:40001 OSError: [Errno 89] Destination address required
$ the Kubernetes API, allowed by policy
add kubernetes.default.svc.cluster.local:443 Policy version 4 loaded
curl /version (TLS terminated) 000
NET:FAIL [LOW] kubernetes.default.svc.cluster.local:443
with tls: skip, curl /version 401
curl /api/v1/namespaces/openshell/secrets 401
| Destino | A policy permite? | Resultado | O que impede |
|---|---|---|---|
Metadata da instância 169.254.169.254 | policy update recusa | inalcançável | OpenShell: link-local é sempre bloqueado |
Agente do Pod Identity 169.254.170.23 | policy update recusa | inalcançável | idem |
allowed_ips: 169.254.0.0/16 | policy update recusa | inalcançável | idem |
| Kubelet, IP do node, porta 10250 | sim | recusado | OpenShell: as portas 2379, 2380, 6443, 10250 e 10255 são bloqueadas para endpoints de host exato, IP e allowed_ips |
1.1.1.1:443 | não, depois sim | recusado, depois 301 | a policy |
| IP do node, porta 22 | não | EACCES | a policy |
UDP para 8.8.8.8:53 ou para o node | não existe tipo de regra para isso | Destination address required | o runtime: só consultas DNS saem por UDP, pelo DNS da policy |
| API do Kubernetes, TLS terminado | sim | falha na conexão | a verificação TLS upstream (a API usa a CA privada do cluster) |
API do Kubernetes, tls: skip | sim | HTTP 401 | nada no OpenShell; o sandbox não tem token |
As primeiras linhas tranquilizam: os endereços que um agente no EKS mais gostaria de alcançar, o metadata da instância e o agente do Pod Identity, são recusados pelo policy update. Em uma verificação separada, uma policy completa nomeando 169.254.169.254 chegou a carregar com sandbox create, mas a conexão ainda assim foi recusada (“resolves to always-blocked address”), então uma policy não consegue abri-los de nenhuma das duas formas.
Vale a pena conhecer a última linha. O EKS serve a API do Kubernetes dentro do cluster na porta 443 (kubernetes.default.svc), e a 443 não está na lista de bloqueio do OpenShell, então uma policy pode abri-la. Com o TLS terminado, a conexão falhou, porque o supervisor não confia na CA do cluster. Com tls: skip, ela passou direto e o API server respondeu 401, já que o sandbox não tem token de ServiceAccount. Uma regra tls: skip para o nome da API mais um token vindo de outro lugar seriam suficientes. (Um host wildcard não faria isso: wildcards não alcançam endereços privados sem allowed_ips.) O prover (Teste 9) pega uma regra dessas se a sua boundary não a permitir.
Teste 8: Rotação e revogação
O 08_rotation.sh usa o provider fictício do servidor de eco, para que o servidor de eco possa mostrar qual valor chega. Um processo em background inicia antes da rotação e chama o servidor de eco 25 segundos depois:
$ openshell provider create --name e-rot --type echo-demo --credential ECHO_TOKEN (ECHO_TOKEN=demo-token-1)
placeholder: openshell:resolve:env:v353228049909348659_ECHO_TOKEN
echo got: Bearer demo-token-1
$ openshell provider update e-rot --credential ECHO_TOKEN --wait (ECHO_TOKEN=demo-token-2)
applied after 8.0 s
new process, placeholder: openshell:resolve:env:v8076519015166486850_ECHO_TOKEN
new process, echo got: Bearer demo-token-2
old placeholder, echo got: Bearer demo-token-1
the process started before the rotation, 25 s later: Bearer demo-token-1
$ openshell provider delete e-rot (still attached)
Error: × failed to delete 1 provider: e-rot
$ openshell sandbox provider detach rot e-rot --wait
applied after 7.6 s
new process, ECHO_TOKEN: unset
old placeholder, echo got: credential_unavailable
$ openshell provider delete e-rot
✓ Deleted provider e-rot
old placeholder, echo got: credential_unavailable
A rotação só alcança processos novos. Depois do provider update --wait, um processo novo recebeu um novo placeholder (o número de revisão mudou) que resolve para o novo valor. O placeholder antigo continuou resolvendo para o valor antigo, tanto quando eu o enviei manualmente quanto a partir do processo que iniciou antes da rotação. Isso está documentado (“um processo existente mantém a sua referência com escopo de revisão; a readiness não faz essa referência antiga resolver o novo valor”), e é o que você iria querer em uma rotação planejada. Para uma credencial vazada, isso significa que processos de longa duração continuam enviando a antiga até reiniciarem, então revogue-a também na origem.
Revogação é detach. Um provider não pode ser deletado enquanto está anexado. Depois do sandbox provider detach --wait, os processos novos não têm variável nenhuma, e o placeholder antigo recebe credential_unavailable. Esse é o interruptor a usar quando um sandbox se comporta mal. Uma ressalva da parte 5: quando a própria policy do sandbox vincula endpoints ao provider (credential_binding, como faz o setup da AWS), o detach é recusado até que uma policy sem esses endpoints esteja em vigor.
Teste 9: O prover no CI
O openshell-prover responde a uma pergunta: esta policy candidata permite algo que a boundary não permite? Ele codifica as duas policies para o solver Z3 e procura um request (binário, host, porta, IP, método, path) que a candidata permite e a boundary não. Ele roda em qualquer lugar, sem cluster, o que o torna uma verificação de CI para mudanças de policy:
openshell-prover 0.1.6
$ openshell-prover check --boundary boundary.yaml candidate-ok.yaml
result: within_boundary
exit code: 0
$ openshell-prover check --boundary boundary.yaml candidate-wildcard.yaml
result: exceeds_boundary
counterexample: network binary=- ancestor_binary=- binary_identity_required=false host=a.org:443 destination_ip=8.8.8.8 trusted_gateway=false protocol=l4 method=- path=-
exit code: 1
$ openshell-prover check --boundary boundary.yaml candidate-post.yaml
result: exceeds_boundary
counterexample: network binary=- ancestor_binary=- binary_identity_required=false host=echo.echo.svc.cluster.local:80 destination_ip=8.8.8.8 trusted_gateway=false protocol=rest method=POST path=/public/a
exit code: 1
$ openshell-prover check --boundary boundary.yaml candidate-audit.yaml
result: unsupported
reason: candidate policy rule 'echo_read' uses REST without enforced inspection
exit code: 3
A boundary permite que o Python alcance o PyPI e que o curl leia do servidor de eco. A primeira candidata fica dentro dela. A segunda troca pypi.org por *.org, e o prover encontrou um contraexemplo (a.org:443). A terceira permite POST, e o contraexemplo é um POST para /public/a. A quarta usa uma regra REST somente leitura sem enforcement, e o prover retorna unsupported: ele não dá aval a uma regra que só audita. Cada resultado tem o próprio exit code (0, 1, 3), que é tudo de que um job de CI precisa.
Dois limites para ter em mente. O prover verifica a policy, não o enforcement: o request com %3B do Teste 3 foi permitido por uma regra que o prover aceitaria, e reescrito no caminho. E o gateway nunca roda a verificação de boundary por conta própria; policy set e policy update aceitam qualquer coisa válida. Se você quer uma boundary, o lugar dela é o CI.
Teste 10: Logs
O openshell logs mostra os eventos OCSF como resumos de uma linha. Para um pipeline de logs, você quer os próprios eventos: a configuração por sandbox ocsf_json_enabled faz o supervisor também escrever cada um deles como JSON no seu log (stderr), onde qualquer coletor de logs do cluster pode pegá-los.
$ openshell sandbox create --name logs --policy policies/echo-read-only.yaml
$ openshell settings set logs --key ocsf_json_enabled --value true
✓ Set sandbox setting ocsf_json_enabled=true for logs (revision 1)
$ three requests: allowed, denied at L7, denied at L4
GET echo server 200
POST echo server 403
GET pypi.org 000
$ kubectl logs <supervisor pod> | grep OCSF-JSON (event classes since the sandbox started)
4 4001 Network Activity
3 5019 Device Config State Change
2 4002 HTTP Activity
2 0 Base Event
1 4007 SSH Activity
$ the L7 denial as JSON (selected fields)
{
"class_name": "HTTP Activity",
"severity": "Medium",
"action": "Denied",
"disposition": "Blocked",
"method": "POST",
"url": "http://echo.echo.svc.cluster.local/items",
"firewall_rule": {
"name": "echo",
"type": "l7"
},
"message": "L7_REQUEST deny POST echo.echo.svc.cluster.local:80/items reason=POST /items not permitted by policy"
}
O JSON traz o que um SIEM precisa: a classe (HTTP Activity), a ação e a disposição, o método e a URL, a policy e a camada que decidiram, e um motivo. Duas lacunas vindas dos testes deste post: violações em modo audit são eventos com ação Allowed e severidade Informational, sinalizadas apenas no texto da mensagem (Teste 3), e nada registra a substituição de uma credencial, só o request em que ela foi substituída (Teste 6). A documentação do OpenShell lista eventos para renovação de credenciais como trabalho futuro.
Resumo dos Resultados
| Resultado | |
|---|---|
| DNS | Nomes fora da policy ainda recebem uma resposta sintética de 198.18.0.0/15 |
| Negação L4 | EACCES no connect() |
| Negação L7 | HTTP 403, header X-OpenShell-Policy, corpo JSON com policy, regra e camada |
openshell logs --level warn | 0 eventos OCSF; só os warnings L4 do proxy |
| Regras por binário | Path real obrigatório (/usr/bin/python3.12); uma cópia do curl é um binário diferente |
| Pinning de binário | Binário alterado recusado; o evento OCSF o nomeia como - (transparent_tcp_identity_unavailable) |
| Padrão L7 | audit: um POST para um endpoint somente leitura é encaminhado; o evento diz Allowed, a mensagem diz audit |
| Normalização de paths | Path traversal com .. e %2e%2e negado |
%3B em um path (#3902) | DELETE /objects/backup%3Bold chega como DELETE /objects/backup |
| Atualização ao vivo, poll (padrão) | 7,9 a 12,5 s |
| Atualização ao vivo, push | 1,3 s |
| Conexões abertas em qualquer mudança de policy | Fechadas (um stream de 30 segundos cortado após 9 linhas) |
| TLS | CA por sandbox; curl, Python, git e aws s3 ls confiam nela pelas variáveis que o OpenShell define; aws s3 cp (CRT) precisa de AWS_CA_BUNDLE |
| Credenciais | Placeholders no sandbox; valores reais no destino; um push para o GitHub e uma chamada à Anthropic funcionaram |
| Binding de credenciais | Por endpoint, não por binário |
| Placeholder para outro host, Host forjado | 403 credential_endpoint_mismatch, 403 request_authority_mismatch |
| Metadata da instância, agente do Pod Identity | Recusados pelo policy update; bloqueados no connect se uma policy completa os nomear |
| Porta 10250 do kubelet | Bloqueada mesmo quando permitida |
| API do Kubernetes | Alcançável com tls: skip (401 sem token) |
| UDP | Só DNS, pelo DNS da policy |
| Rotação | Processos novos recebem o novo valor; placeholders antigos mantêm o antigo |
| Revogação | Detach: credential_unavailable para todo placeholder |
| Prover | dentro (0), excede com um contraexemplo (1), não suportado para regras audit (3) |
| OCSF JSON | Por sandbox, no log do Pod do supervisor |
O Que o Policy Engine Não Resolve
- O que o agente faz com o acesso que tem. Uma regra que deixa o
gitfazer push para um repositório permite que ele faça push de qualquer coisa para esse repositório. O OpenShell decide para onde os requests vão e que formato eles têm, não se o conteúdo deles é uma boa ideia. Os hooks de middleware do supervisor na 0.1.x podem inspecionar requests, mas a documentação descreve essa API como ainda em evolução. - Qual binário usa uma credencial. O binding é por endpoint. Qualquer binário que alguma regra deixe alcançar
api.github.compode usar o placeholder do GitHub (Teste 6). - Erros na policy. O modo audit é o padrão para regras L7,
tls: skipdesliga a inspeção e a substituição, e a API do Kubernetes está a uma regra de distância (Teste 7). O prover pega o que uma boundary proíbe, se você o rodar; o gateway não. - Bugs no enforcement. O prover raciocina sobre a policy, então não consegue ver que
%3Breescreve um path (Teste 3). O #3902 está aberto na 0.1.6. - Revogar um valor que já está em circulação. A rotação só alcança processos novos (Teste 8). Revogue credenciais vazadas na origem e faça o detach do provider.
Limpeza
./99_cleanup.sh
cd ../openshell-eks
./09_scale.sh down # zero nodes between sessions
O 99_cleanup.sh deleta os sandboxes, providers e profiles que estes scripts criam, remove o override de entrega por push caso uma execução tenha sido interrompida e deleta o servidor de eco. O 06_credentials.sh deleta a própria branch no GitHub, inclusive quando é interrompido. As credenciais do GitHub e da Anthropic ficam no store criptografado do gateway apenas até os providers serem deletados.
Veredito
O modelo de egress do OpenShell é a parte mais interessante dele, e no EKS ele se sustentou. O ambiente do agente realmente não guarda nenhuma credencial: um push para o GitHub e uma chamada à Anthropic rodaram com placeholders, os placeholders se recusaram a funcionar em qualquer outro lugar, e os endereços que um atacante no EKS tentaria primeiro, o metadata da instância e o agente do Pod Identity, continuam bloqueados independentemente do que a policy diga. As negações L7 são específicas o suficiente para um agente agir com base nelas, e os eventos OCSF trazem o que um SIEM precisa.
Os padrões são onde você pode se machucar:
- As regras L7 auditam, a menos que você diga
enforce. Uma regraread-onlysem isso deixa escritas passarem e as registra como permitidas, com a violação só no texto da mensagem. Escrevaenforcement: enforceem todo endpoint REST e deixe o prover rejeitar os que não tiverem. %3Breescreve paths (#3902). Até isso ser corrigido, assuma que uma regra de path pode ser desviada para um recurso vizinho.- As credenciais seguem endpoints, não binários. Restrinja as regras para hosts com credenciais aos binários que precisam deles.
- Placeholders mantêm segredos fora do ambiente, não fora de alcance. Um endpoint que ecoa ou armazena o que recebe pode devolver o valor real ao agente. Vincule credenciais apenas a endpoints aos quais você confiaria esses valores.
- Mudanças de policy cortam todas as conexões abertas, e o polling faz com que levem cerca de 10 segundos. Agrupe as mudanças de policy e ligue a entrega por push se houver agentes esperando por elas.
- A rotação não alcança processos em execução. O detach é a revogação.
- Leia os logs com atenção: violações em modo audit são eventos com ação Allowed, a negação de um binário adulterado não nomeia o binário, e o uso de credenciais não é registrado.
Minhas regras de trabalho depois disso: uma policy por papel de agente, gerada em vez de editada à mão, verificada contra uma boundary com o openshell-prover no CI; enforce em todo endpoint REST; paths reais de binários; tls: skip só onde um protocolo precisar, e nunca para uma API dentro do cluster. Com isso, o OpenShell dá a um agente no Kubernetes um acesso à rede que eu me sentiria confortável em auditar.
A parte 5 leva a mesma ideia para a AWS: o gateway assume uma role, e o supervisor assina cada request com SigV4, então o sandbox recebe placeholders também para as chaves da AWS, e a parte 5 encontra onde isso quebra.