Regras

Utilize regras para controlar os comandos que o Codex pode executar fora do sandbox.

Criar um ficheiro de regras

1. Crie um ficheiro .rules numa pasta rules/ junto a uma camada de configuração ativa (por exemplo, ~/.codex/rules/default.rules).
2. Adicione uma regra. Este exemplo solicita confirmação antes de permitir que gh pr view seja executado 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.

No arranque, o Codex procura rules/ em todas as camadas de configuração ativas, incluindo localizações de Configuração da equipa e a camada do utilizador em ~/.codex/rules/. As regras locais do projeto em <repo>/.codex/rules/ só são carregadas quando a camada .codex/ do projeto é considerada fidedigna.

Quando adiciona um comando à lista de permissões na TUI, o Codex escreve na camada do utilizador em ~/.codex/rules/default.rules, para que as execuções futuras possam ignorar o pedido de confirmação.

Quando as aprovações inteligentes estão ativadas (a predefinição), o Codex pode propor-lhe um prefix_rule durante pedidos de escalamento. Reveja cuidadosamente o prefixo sugerido antes de o aceitar.

Os administradores também podem impor entradas prefix_rule restritivas a partir de requirements.toml.

Compreender os campos das regras

prefix_rule() suporta os seguintes campos:

• pattern (obrigatório): Uma lista não vazia que define o prefixo de comando a corresponder. Cada elemento pode ser:
  • Uma cadeia literal (por exemplo, "pr").
  • Uma união de literais (por exemplo, ["view", "list"]) para corresponder a alternativas nessa posição do argumento.
• decision (a predefinição é "allow"): A ação a executar quando a regra corresponde. O Codex aplica a decisão mais restritiva quando existe correspondência com mais do que uma regra (forbidden > prompt > allow).
  • allow: Executar o comando fora do sandbox sem solicitar confirmação.
  • prompt: Solicitar confirmação antes de cada invocação correspondente.
  • forbidden: Bloquear o pedido sem solicitar confirmação.
• justification (opcional): Um motivo não vazio e legível para a regra. O Codex pode apresentá-lo em pedidos de aprovação ou mensagens de rejeição. Quando utilizar forbidden, inclua uma alternativa recomendada na justificação quando for adequado (por exemplo, "Use \rg` instead of `grep`."`).
• match e not_match (a predefinição é []): Exemplos que o Codex valida ao carregar as suas regras. Utilize-os para detetar erros antes de uma regra entrar em vigor.

Quando o Codex considera executar um comando, compara a lista de argumentos do comando com pattern. Internamente, o Codex trata o comando como uma lista de argumentos (tal como a que execvp(3) recebe).

Wrappers de shell e comandos compostos

Algumas ferramentas agrupam vários comandos de shell numa única invocação, por exemplo:

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

Como este tipo de comando pode ocultar várias ações numa única cadeia, o Codex trata bash -lc, bash -c e os respetivos equivalentes zsh / sh de forma especial.

Quando o Codex pode dividir o script em segurança

Se o script de shell for uma cadeia linear de comandos composta apenas por:

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

então, o Codex analisa-o (através do tree-sitter) e divide-o em comandos individuais antes de aplicar as suas regras.

O script acima é tratado como dois comandos separados:

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

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

Mesmo que permita pattern=["git", "add"], o Codex não permitirá automaticamente git add . && rm -rf /, porque a parte rm -rf / é avaliada separadamente e impede que toda a invocação seja permitida automaticamente.

Isto impede que comandos perigosos sejam introduzidos de forma dissimulada juntamente com comandos seguros.

Quando o Codex não divide o script

Se o script utilizar funcionalidades de shell mais avançadas, tais como:

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

então, o Codex não tenta interpretá-lo nem dividi-lo.

Nesses casos, toda a invocação é tratada como:

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

e as suas regras são aplicadas a essa única invocação.

Com este tratamento, obtém a segurança da avaliação por comando quando esta pode ser efetuada com segurança e um comportamento conservador quando não pode.

Testar um ficheiro de regras

Utilize codex execpolicy check para testar como as 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 emite JSON que mostra a decisão mais restritiva e quaisquer regras correspondentes, incluindo quaisquer valores justification das regras correspondentes. Utilize mais do que um sinalizador --rules para combinar ficheiros e adicione --pretty para formatar a saída.

Compreender a linguagem das regras

O formato de ficheiro .rules utiliza Starlark (consulte a especificação da linguagem). A sintaxe é semelhante à de Python, mas foi concebida para uma execução segura: o motor de regras pode executá-la sem efeitos secundários (por exemplo, sem alterar o sistema de ficheiros).