Segurança do Codex na prática: permissões, sandbox e proteção contra vazamento de secrets

Na raiz do seu projeto existe um arquivo .env com a senha do banco de dados e chaves API de terceiros. Você abre o Codex para pedir ajuda na refatoração dos testes. No menu aparecem read-only, workspace-write e danger-full-access. Qual você escolhe?

Depois de escolher workspace-write, o Codex pede aprovação para executar npm install. Você aprova. Já parou para pensar se aquele script postinstall meio esquecido no package.json pode, nesse momento, ler suas variáveis de ambiente ou enviar uma requisição para um serviço que você nem conhece?

Você coloca o Codex no GitHub Actions para automatizar PR review. No workflow está escrito OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}. Parece seguro, afinal é secrets. Mas os scripts de teste, third-party actions e hooks de instalação de dependências no mesmo job também podem ler essa chave.

Três limites respondem diretamente a essas perguntas: instrução não é permissão, aprovação não é isolamento, sandbox não é auditoria. A seguir, uma checklist de permissões mínimas para local, Cloud e CI.

Permissão não se resolve com regra verbal: entenda as três camadas sandbox, approval e permission profile

Muita gente acha que escrever uma linha em AGENTS.md, como “não leia o arquivo .env”, impede o Codex de acessar informações sensíveis. Isso não é controle de permissão, é orientação de projeto. O limite de segurança real vem de três camadas: sandbox restringe o alcance dos spawned commands, approval policy decide quando parar e pedir confirmação, e permission profile aplica controle de acesso obrigatório.

Segurança no Codex não funciona com uma camada só. sandbox define o que git, gerenciadores de pacotes e test runners podem acessar como spawned commands. approval policy decide se o Codex precisa da sua aprovação antes de operações críticas. permission profile é a camada onde você realmente escreve "**/*.env" = "deny". As três camadas juntas formam a permissão efetiva.

Comparação dos modos sandbox: read-only, workspace-write, danger-full-access

sandbox limita spawned commands, não apenas operações internas de arquivo do Codex. git, gerenciadores de pacotes e test runners herdam o mesmo limite. A plataforma também influencia: Linux/WSL2 depende de bubblewrap ou user namespace, macOS usa a sandbox do sistema, e Windows depende dos recursos de sandbox disponíveis.

approval policy decide quando parar e perguntar:

Combinações de baixo risco: read-only + never para CI somente leitura e workspace-write + on-request para desenvolvimento local. Combinação de alto risco: danger-full-access + never, só em ambiente controlado.

Configuração de permission profile: filesystem deny, network rules

permission profile é controle de acesso obrigatório, não orientação verbal. Permissões filesystem aceitam read/write/deny; regras mais específicas substituem regras mais amplas, e deny tem prioridade.

Exemplo de deny glob para .env:

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

{
  "filesystem": {
    "rules": {
      "**/*.env": "deny",
      "**/.env.local": "deny",
      "**/secrets/**": "deny",
      "workspace/**": "write"
    }
  }
}

Com essa configuração, arquivos .env continuam ilegíveis em workspace-write, mesmo que o workspace seja gravável por padrão. deny ganha, e regras concretas substituem regras amplas.

network profile pode configurar enabled = true e regras allow/deny por domínio; deny também tem prioridade. local/private network tem proteção padrão. Permitir localhost ou Docker socket é uma exceção explícita. Docker socket é um escape hatch local: pode alcançar serviços locais, contêineres e redes. Abra com cuidado.

network proxy restringe o acesso de rede de comandos já habilitados; ele não concede rede por si só. Um allow global * é acesso amplo à rede e deve ser usado com cautela.

Checklist local de permissões mínimas: de revisão read-only a full access

No desenvolvimento local, permissão maior não significa menos problema. Approval consegue barrar algumas operações, mas o isolamento real vem de sandbox e permission profile. Comece pela permissão mais estreita e amplie conforme a tarefa exigir.

Tabela de decisão: quando usar read-only e quando usar workspace-write

Passos para proteger .env e arquivos de secrets:

1. Descubra o caminho do arquivo de configuração do permission profile usado, seguindo a documentação Codex Permissions.
2. Adicione "**/*.env" = "deny" às permissões filesystem.
3. Confirme que regras mais específicas substituem regras amplas e que deny tem prioridade.
4. Teste: em modo workspace-write, uma tentativa de ler .env deve ser negada.
5. Amplie se necessário com "**/.env.local" = "deny" e "**/secrets/**" = "deny".

Não dependa de regra verbal. AGENTS.md orienta, mas não aplica controle de acesso obrigatório. O Codex pode seguir a orientação, mas também pode ler por outros motivos. Só o deny do permission profile é uma barreira obrigatória.

Risco na instalação de dependências: npm postinstall, pip hooks, Docker socket

Instalar dependências não é só baixar arquivos. postinstall e prepare de npm/pnpm, além de hooks de pip install, rodam automaticamente durante a instalação. Esses scripts podem ler variáveis de ambiente, enviar requisições de rede ou modificar arquivos do sistema.

Checklist de risco:

• postinstall desconhecido pode ler variáveis de ambiente: mesmo com deny para .env, postinstall roda no ambiente dos spawned commands e pode ver environment variables.
• Pode enviar requisições de rede: baixar binários extras, enviar telemetria, conectar a repositórios privados.
• Pode modificar arquivos do sistema: escrever configuração global, alterar PATH.

Recomendações de auditoria:

1. Revise scripts e origem primeiro: campo scripts de package.json, setup.py de pacotes pip.
2. Use fontes confiáveis: fixe versões e evite upgrade automático para versões desconhecidas.
3. Aprove em ambiente controlado: localmente, use workspace-write + on-request e veja o que o Codex quer instalar antes de aprovar.

Docker socket é um escape hatch local. Permitir Docker socket pode dar acesso a serviços locais, contêineres e rede. Configure apenas quando houver necessidade clara, nunca por padrão.

Limites em Cloud: setup vs agent phase, ciclo de vida dos secrets

Uma Cloud task não roda localmente, mas em um contêiner isolado hospedado pela OpenAI. sandbox pode limitar spawned commands, mas a proteção real dos secrets vem do ciclo de vida do Cloud secrets: disponível na fase setup, removido antes da agent phase. sandbox não é auditoria; segurança vem de separação em camadas.

Ciclo de vida do Cloud container:

1. Criar container
2. Fazer checkout do repo
3. Executar setup script
4. Aplicar configurações de rede
5. agent executa o loop de comandos
6. Emitir answer/diff

Limite entre setup e agent phase: secrets só no setup

Na setup phase, rede, instalação de dependências e secrets estão disponíveis. Na agent phase, o ambiente fica offline por padrão, os secrets já foram removidos e só restam environment variables.

setup scripts rodam em uma sessão Bash separada; export não passa automaticamente para a agent phase. Se você fizer export MY_KEY=xxx no setup, a agent phase não herda essa variável. Entre fases, só Cloud secrets e environment variables seguem suas regras.

secrets vs environment variables: diferença essencial

secrets ficam disponíveis apenas em setup scripts. Servem para instalar dependências e acessar repositórios privados. A agent phase não deve conter secrets de produção. environment variables permanecem o tempo todo e servem para configuração não sensível.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Limites de instalação de dependências:

• setup phase pode instalar dependências com rede.
• agent phase fica offline por padrão.
• setup scripts podem acessar secrets; scripts desconhecidos podem vazar esses dados.
• Recomendação: revise scripts e origem, use fontes confiáveis e evite executar scripts desconhecidos no setup.

O container cache dura no máximo 12 horas. Mudanças em setup, maintenance, env ou secrets acionam cache invalidation.

CI e GitHub Action: codex exec, proibições com API key e estratégia segura da official Action

codex exec usa read-only sandbox por padrão, mas muita gente coloca OPENAI_API_KEY como job-level environment variable no workflow. Scripts de teste, third-party actions e dependency lifecycle scripts no mesmo job podem ler essa chave. sandbox não é auditoria; segurança vem de permissões mínimas e proteção da chave.

Proibição de API key: não use job-level env

Não defina OPENAI_API_KEY ou CODEX_API_KEY como job-level environment variable em workflow que faz checkout ou executa código do repositório. Código do repositório, testes, dependency lifecycle scripts e third-party actions podem acessar variáveis de ambiente no mesmo job.

Checklist de proibição:

• Não coloque OPENAI_API_KEY como job-level env.
• Não configure uma job-level key em workflows que fazem checkout ou executam código do repositório.
• auth.json / ChatGPT-managed auth não é adequado para workflows de repositórios public/open-source.
• Não execute código não confiável no mesmo process environment da chave.

Formas corretas:

1. Invocation inline única: defina CODEX_API_KEY apenas para uma invocation de codex exec.

- name: Run Codex
  run: CODEX_API_KEY=${{ secrets.CODEX_API_KEY }} codex exec "review PR #${{ github.event.number }}"

2. Proxy da official Action: use o proxy de openai/codex-action@v1.

- uses: openai/codex-action@v1
  with:
    prompt: "review PR #${{ github.event.number }}"
    sandbox: read-only
    safety-strategy: drop-sudo

danger-full-access em CI só faz sentido em isolated CI runner/container. Não deve ser padrão, porque permite acessar todos os recursos do runner.

Checklist de segurança no GitHub Action: limitar gatilhos, proteger chave, rotacionar chave

Parâmetros da official Action:

read-only não significa que todos os secrets do runner estejam protegidos. A Action ainda roda no runner; ela apenas restringe o filesystem a leitura. drop-sudo remove sudo. sandbox deve ser o modo mais estreito que conclui a tarefa.

Checklist de segurança do GitHub Action:

• Limitar gatilhos: allow-users apenas para usuários específicos, allow-bots com cautela.
• Limpar entradas de PR/issue/prompt: evitar prompt injection e não passar input não confiável diretamente ao Codex.
• Proteger API key: não usar job-level env; usar invocation inline única ou proxy.
• Executar Codex como último passo: reduzir o tempo de exposição da chave.
• Se suspeitar de vazamento, rotacionar a chave: não investigue primeiro; primeiro reduza o dano.

Entradas de PR/issue/prompt devem ser tratadas como não confiáveis. Não passe PR comment ou issue body diretamente para o prompt do Codex.

Como reagir a vazamento de secret: o primeiro passo após suspeita

Se houver suspeita de vazamento, o primeiro passo não é investigar, mas rotacionar a chave. Primeiro reduza o dano, depois audite. sandbox pode limitar spawned commands, mas não impede que o Codex escreva uma chave em logs, PR comments ou answer.

Passos diante de vazamento: rotação de chave, auditoria, revogação

Primeiro passo: rotacionar a chave. Não procure a origem antes; invalide a chave antiga.

Depois:

🔥 Não perca meses em produtos sem demanda! Valide as propostas do seu SaaS com a Adsterra e pouco orçamento →

Testar agora →Anúncio

1. Auditar logs: verificar o histórico de uso da chave e procurar chamadas anormais.
2. Revogar token: garantir que a chave antiga está completamente inválida e que nenhuma session ativa sobrou.
3. Buscar origem: revisar Codex log, saídas do GitHub Action, scripts de instalação de dependências e third-party actions.

Medidas preventivas:

• Não coloque API key em código frontend nem no repositório.
• Não coloque API key como job-level env (CI).
• Use permission profile deny para .env.
• Rotacione chaves regularmente, como recomenda o OWASP Secrets Management Cheat Sheet.

Limite do Codex Security: não substitui SAST nem aplica patch automaticamente

Codex Security é um LLM-driven security analysis toolkit que roda em um ephemeral isolated container e produz findings estruturados e sugestões de patch. Ele pode ajudar a encontrar e verificar vulnerabilidades, mas não substitui SAST nem revisão manual de segurança.

Checklist de limites:

• Não substitui SAST.
• Não substitui manual security review.
• proposed patch precisa de review do usuário e não é aplicado automaticamente.
• Uso: ajudar a descobrir, verificar e sugerir, não reparar automaticamente.

Não trate Codex Security como um scanner universal de segurança. AI-driven analysis consegue encontrar alguns problemas, mas segurança real vem de camadas: escopo legível, escopo gravável, rede, secrets, approval, review e revogação.

Conclusão

O limite de segurança do Codex vem de três camadas: sandbox restringe o alcance dos spawned commands, approval policy decide quando parar e perguntar, e permission profile aplica controle de acesso obrigatório. As três juntas formam a permissão real.

Três limites para lembrar:

• Instrução não é permissão: AGENTS.md é guia, não controle de acesso obrigatório. Não proteja .env e API key só com regra verbal.
• Aprovação não é isolamento: approval policy pode parar algumas operações, mas o isolamento real vem de sandbox e permission profile.
• sandbox não é auditoria: sandbox pode limitar spawned commands, mas não impede que o Codex escreva uma chave em logs, PR comments ou answer. Segurança vem de camadas.

Checklist rápida:

• Você configurou deny glob para .env?
• Evita job-level API key em CI?
• Limita quem pode disparar GitHub Action?
• Auditou scripts de instalação de dependências?
• Tem um plano de rotação de chaves?

Limites de segurança não bloqueiam bugs de lógica. O Codex pode respeitar todas as regras de permissão e ainda gerar código com bug, testes podem falhar e rollback pode ser necessário. Revisar diff, rodar testes e preparar rollback é a segunda linha de defesa fora da fronteira de segurança.

Próximos passos:

• Retrospectiva de falhas e fluxo de validação: entender como lidar com erros do Codex, validar diffs e preparar rollback.
• Automação com codex exec e CI: aprofundar modo não interativo, desenho de workflows e tratamento de erros em CI.
• Regras de projeto AGENTS.md: aprender a escrever regras de projeto, lembrando que são guia, não sistema de permissões.

Leituras relacionadas:

• Panorama de ferramentas de AI coding 2026: entender o ecossistema geral de ferramentas de AI coding.
• Fundamentos de GitHub Actions CI: revisar os conceitos básicos de CI workflow.
• Estratégia de deploy com GitHub Actions: entender os limites de uso de secrets em deploy.
• Risco de vazamento de API key no frontend: entender por que chaves não devem entrar no frontend nem no repositório.