Regras

Use regras para controlar quais comandos o Codex pode executar fora do sandbox.

Crie um arquivo de regras

Para o acesso ao computador local com a nuvem do Work, use o campo TOML rules nas configurações de segurança do agente para configurar as regras gerenciadas de comando compatíveis. Essas regras se aplicam aos executores locais. Os contêineres da nuvem do Work usam as políticas já existentes dessa nuvem.

As instruções a seguir sobre arquivos .rules locais se aplicam ao Codex. Não presuma que o recurso de acesso ao computador local com a nuvem do Work leia arquivos de regras locais. Consulte a configuração gerenciada e a referência de configuração para conhecer os requisitos gerenciados do Work.

1. Crie um arquivo .rules em uma pasta rules/ junto a uma camada de configuração ativa (por exemplo, ~/.codex/rules/default.rules).

2. Adicione uma regra. Neste exemplo, o Codex pede aprovação antes de executar gh pr view fora do sandbox.

   # Prompt before running commands with the prefix `gh pr view` outside the sandbox.
   prefix_rule(
       # The prefix to match.
       pattern = ["gh", "pr", "view"],
   
       # The action to take when Codex requests to run a matching command.
       decision = "prompt",
   
       # Optional rationale for why this rule exists.
       justification = "Viewing PRs is allowed with approval",
   
       # `match` and `not_match` are optional "inline unit tests" where you can
       # provide examples of commands that should (or should not) match this rule.
       match = [
           "gh pr view 7888",
           "gh pr view --repo openai/codex",
           "gh pr view 7888 --json title,body,comments",
       ],
       not_match = [
           # Does not match because the `pattern` must be an exact prefix.
           "gh pr --repo openai/codex view 7888",
       ],
   )

3. Reinicie o Codex.

Ao iniciar, o Codex procura regras na pasta rules/ de cada camada de configuração ativa, incluindo os locais da configuração da equipe e a camada do usuário em ~/.codex/rules/. O Codex só carrega as regras locais do projeto em <repo>/.codex/rules/ quando a camada .codex/ do projeto é confiável.

Quando você adiciona um comando à lista de comandos permitidos na interface de terminal (TUI), o Codex grava a regra na camada do usuário em ~/.codex/rules/default.rules. Assim, nas próximas execuções, o Codex pode dispensar o pedido de aprovação.

Quando as aprovações inteligentes estão ativadas (configuração padrão), o Codex pode sugerir uma prefix_rule ao solicitar elevação de privilégios. Examine o prefixo sugerido com atenção antes de aceitá-lo.

Os administradores também podem impor regras prefix_rule restritivas por meio de requirements.toml.

Entenda os campos de uma regra

prefix_rule() aceita os seguintes campos:

• pattern (obrigatório): lista não vazia que define o prefixo ao qual o comando deve corresponder. Cada elemento pode ser:
  • Uma string literal (por exemplo, "pr").
  • Uma união de literais (por exemplo, ["view", "list"]) que aceita qualquer uma das alternativas naquela posição da lista de argumentos.
• decision (padrão: "allow"): ação a executar quando o comando corresponde à regra. Se o comando corresponder a mais de uma regra, o Codex aplica a decisão mais restritiva (forbidden > prompt > allow).
  • allow: executa o comando fora do sandbox sem pedir aprovação.
  • prompt: pede aprovação antes de cada execução que corresponda à regra.
  • forbidden: bloqueia a solicitação sem pedir aprovação.
• justification (opcional): texto não vazio que explica o motivo da regra. O Codex pode exibi-lo em pedidos de aprovação ou mensagens de rejeição. Ao usar forbidden, inclua na justificativa uma alternativa recomendada, se for o caso (por exemplo, "Use \rg` instead of `grep`.“`).
• match e not_match (padrão: []): exemplos que o Codex valida ao carregar suas regras. Use esses campos para identificar erros antes que uma regra entre em vigor.

Ao avaliar se pode executar um comando, o Codex compara a lista de argumentos do comando com pattern. Internamente, o Codex trata o comando como uma lista de argumentos, semelhante à que execvp(3) recebe.

Wrappers de shell e comandos compostos

Algumas ferramentas agrupam vários comandos de shell em uma única chamada, como neste exemplo:

["bash", "-lc", "git add . && rm -rf /"]

Como esse tipo de comando pode ocultar várias ações em uma única string, o Codex trata de forma especial bash -lc, bash -c e seus equivalentes em zsh e sh.

Quando o Codex pode dividir o script com segurança

O Codex pode dividir o script de shell quando ele contém apenas uma sequência linear de comandos com estas características:

• Os comandos contêm apenas palavras simples (sem expansão de variáveis, VAR=..., $FOO, * etc.).
• Os comandos são unidos por operadores seguros (&&, ||, ; ou |).

Nesse caso, o Codex usa o tree-sitter para analisar o script e separa os comandos antes de aplicar suas regras.

O Codex trata o script acima como dois comandos distintos:

• ["git", "add", "."]
• ["rm", "-rf", "/"]

Em seguida, o Codex avalia cada comando de acordo com suas regras e aplica o resultado mais restritivo.

Mesmo que você permita pattern=["git", "add"], o Codex não permitirá automaticamente git add . && rm -rf /, pois avalia rm -rf / separadamente.

Isso impede que comandos perigosos passem despercebidos em meio a comandos seguros.

Quando o Codex não divide o script

Entre os recursos mais avançados do shell estão:

• redirecionamento (>, >>, <)
• substituições ($(...), ...)
• variáveis de ambiente (FOO=bar)
• padrões com curingas (*, ?)
• controle de fluxo (if, for, && com atribuições etc.)

Quando o script usa recursos desse tipo, o Codex não tenta interpretá-lo nem dividi-lo.

Nesses casos, o Codex trata a chamada inteira da seguinte forma:

["bash", "-lc", "<full script>"]

Suas regras se aplicam a essa única chamada.

Assim, o Codex avalia cada comando separadamente quando pode fazer isso com segurança e adota uma abordagem conservadora nos demais casos.

Teste um arquivo de regras

Use codex execpolicy check para testar como suas regras se aplicam a um comando:

codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- gh pr view 7888 --json title,body,comments

O comando retorna um JSON com a decisão mais restritiva e todas as regras às quais o comando corresponde, incluindo os valores de justification que elas definirem. Use a opção --rules mais de uma vez para combinar arquivos e adicione --pretty para formatar a saída.

Entenda a linguagem das regras

O formato de arquivo .rules usa Starlark (consulte a especificação da linguagem). A sintaxe é parecida com a de Python, mas a linguagem foi projetada para execução segura. O mecanismo de regras pode executar código nessa linguagem sem efeitos colaterais, como acessar o sistema de arquivos.