segunda-feira, 16 de novembro de 2026 Edição nº 240
Buscar
Avaliação · Infraestrutura · 37 min de leitura

Policy e Egress do OpenShell: Hands-On no Amazon EKS

Por Fabio Douek

Ir para seção
Explica (TLDR) como se eu fosse...
O que é isso?

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.

GitHub Veja o código-fonte aqui: openshell-egress

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

POD DE WORKLOAD processo do agente curl, git, gh, python3 … GITHUB_TOKEN= openshell:resolve:env:… runtime OpenShell (PID 1) intercepta connect() e DNS, identifica o binário chamador, não decide nada → o Sandbox Protocol: a única saída do agente; a NetworkPolicy não permite egress POD DO SUPERVISOR 1DNS da policyum endereço sintético 198.18.0.0/15 2L4: binário, host, portamais o SHA-256 fixado do binário 3TLS terminadocert. leaf da CA própria do sandbox 4L7: método e pathregras REST; enforce ou audit 5placeholder → valor realsó se vinculado a este endpoint 6conexão upstreamIP fixado, TLS real EACCESno connect() 403 JSONpolicy_denied 403 JSONcredential_endpoint_mismatch decisões de permitir e negar: eventos OCSF no log deste Pod DESTINOS api.github.com api.anthropic.com pypi.org echo.echo.svc (servidor de eco no cluster)
Um request de saída no driver do Kubernetes. O workload nunca abre uma conexão de rede por conta própria; o supervisor toma todas as decisões e abre todas as conexões.

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:

  1. 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.
  2. 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 como EACCES no connect().
  3. 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.
  4. L7. Para endpoints com protocol: rest, o método e o path precisam corresponder. Uma negação é um HTTP 403 com um corpo JSON.
  5. 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.
  6. 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_BUNDLE ou SSL_CERT_FILE,
  • o módulo ssl do Python lê SSL_CERT_FILE,
  • o git lê GIT_SSL_CAINFO,
  • a AWS CLI 2.39 lê REQUESTS_CA_BUNDLE para aws s3 ls e 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
DestinoA policy permite?ResultadoO que impede
Metadata da instância 169.254.169.254policy update recusainalcançávelOpenShell: link-local é sempre bloqueado
Agente do Pod Identity 169.254.170.23policy update recusainalcançávelidem
allowed_ips: 169.254.0.0/16policy update recusainalcançávelidem
Kubelet, IP do node, porta 10250simrecusadoOpenShell: as portas 2379, 2380, 6443, 10250 e 10255 são bloqueadas para endpoints de host exato, IP e allowed_ips
1.1.1.1:443não, depois simrecusado, depois 301a policy
IP do node, porta 22nãoEACCESa policy
UDP para 8.8.8.8:53 ou para o nodenão existe tipo de regra para issoDestination address requiredo runtime: só consultas DNS saem por UDP, pelo DNS da policy
API do Kubernetes, TLS terminadosimfalha na conexãoa verificação TLS upstream (a API usa a CA privada do cluster)
API do Kubernetes, tls: skipsimHTTP 401nada 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
DNSNomes fora da policy ainda recebem uma resposta sintética de 198.18.0.0/15
Negação L4EACCES no connect()
Negação L7HTTP 403, header X-OpenShell-Policy, corpo JSON com policy, regra e camada
openshell logs --level warn0 eventos OCSF; só os warnings L4 do proxy
Regras por binárioPath real obrigatório (/usr/bin/python3.12); uma cópia do curl é um binário diferente
Pinning de binárioBinário alterado recusado; o evento OCSF o nomeia como - (transparent_tcp_identity_unavailable)
Padrão L7audit: um POST para um endpoint somente leitura é encaminhado; o evento diz Allowed, a mensagem diz audit
Normalização de pathsPath 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, push1,3 s
Conexões abertas em qualquer mudança de policyFechadas (um stream de 30 segundos cortado após 9 linhas)
TLSCA 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
CredenciaisPlaceholders no sandbox; valores reais no destino; um push para o GitHub e uma chamada à Anthropic funcionaram
Binding de credenciaisPor endpoint, não por binário
Placeholder para outro host, Host forjado403 credential_endpoint_mismatch, 403 request_authority_mismatch
Metadata da instância, agente do Pod IdentityRecusados pelo policy update; bloqueados no connect se uma policy completa os nomear
Porta 10250 do kubeletBloqueada mesmo quando permitida
API do KubernetesAlcançável com tls: skip (401 sem token)
UDPSó DNS, pelo DNS da policy
RotaçãoProcessos novos recebem o novo valor; placeholders antigos mantêm o antigo
RevogaçãoDetach: credential_unavailable para todo placeholder
Proverdentro (0), excede com um contraexemplo (1), não suportado para regras audit (3)
OCSF JSONPor 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 git fazer 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.com pode usar o placeholder do GitHub (Teste 6).
  • Erros na policy. O modo audit é o padrão para regras L7, tls: skip desliga 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 %3B reescreve 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 regra read-only sem isso deixa escritas passarem e as registra como permitidas, com a violação só no texto da mensagem. Escreva enforcement: enforce em todo endpoint REST e deixe o prover rejeitar os que não tiverem.
  • %3B reescreve 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.

Comments