Kurallar

Codex'in korumalı alan dışında hangi komutları çalıştırabileceğini denetlemek için kuralları kullanın.

Kural dosyası oluşturma

1. Etkin bir yapılandırma katmanının yanında bulunan bir rules/ klasörünün altında (örneğin ~/.codex/rules/default.rules) bir .rules dosyası oluşturun.
2. Bir kural ekleyin. Bu örnek, gh pr view komutunun korumalı alan dışında çalışmasına izin vermeden önce onay ister.

   # 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. Codex'i yeniden başlatın.

Codex başlangıçta, Ekip Yapılandırması konumları ve ~/.codex/rules/ adresindeki kullanıcı katmanı dâhil olmak üzere her etkin yapılandırma katmanındaki rules/ öğesini tarar. <repo>/.codex/rules/ altındaki proje yerel kuralları yalnızca projenin .codex/ katmanına güvenildiğinde yüklenir.

TUI'de izin verilenler listesine bir komut eklediğinizde Codex, gelecekteki çalıştırmaların istemi atlayabilmesi için ~/.codex/rules/default.rules adresindeki kullanıcı katmanına yazar.

Akıllı onaylar etkinleştirildiğinde (varsayılan), Codex yetki yükseltme istekleri sırasında sizin için bir prefix_rule önerebilir. Önerilen ön eki kabul etmeden önce dikkatle inceleyin.

Yöneticiler ayrıca requirements.toml üzerinden kısıtlayıcı prefix_rule girdilerini zorunlu kılabilir.

Kural alanlarını anlama

prefix_rule() şu alanları destekler:

• pattern (gerekli): Eşleştirilecek komut ön ekini tanımlayan, boş olmayan bir liste. Her öğe şunlardan biridir:
  • Değişmez bir dize (örneğin "pr").
  • İlgili bağımsız değişken konumundaki alternatifleri eşleştirmek için değişmezlerin birleşimi (örneğin ["view", "list"]).
• decision (varsayılan: "allow"): Kural eşleştiğinde gerçekleştirilecek eylem. Birden fazla kural eşleştiğinde Codex en kısıtlayıcı kararı uygular (forbidden > prompt > allow).
  • allow: Komutu onay istemeden korumalı alan dışında çalıştırır.
  • prompt: Eşleşen her çağrıdan önce onay ister.
  • forbidden: İsteği onay istemeden engeller.
• justification (isteğe bağlı): Kural için boş olmayan ve insanların okuyabileceği bir gerekçe. Codex bunu onay istemlerinde veya ret iletilerinde gösterebilir. forbidden kullandığınızda, uygun durumlarda gerekçeye önerilen bir alternatif ekleyin (örneğin "Use \rg d instead of \grep d.").
• match ve not_match (varsayılan: []): Codex'in kurallarınızı yüklerken doğruladığı örnekler. Bir kural yürürlüğe girmeden önce hataları yakalamak için bunları kullanın.

Codex çalıştırılacak bir komutu değerlendirirken komutun bağımsız değişken listesini pattern ile karşılaştırır. Codex dahili olarak komutu bir bağımsız değişken listesi olarak değerlendirir (execvp(3) öğesinin aldığı gibi).

Kabuk sarmalayıcıları ve bileşik komutlar

Bazı araçlar birden fazla kabuk komutunu tek bir çağrı içinde sarmalar, örneğin:

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

Bu tür bir komut tek bir dize içinde birden fazla eylemi gizleyebildiğinden Codex, bash -lc, bash -c ve bunların zsh / sh eşdeğerlerini özel olarak ele alır.

Codex betiği güvenle bölebildiğinde

Kabuk betiği yalnızca şunlardan oluşan doğrusal bir komut zinciriyse:

• düz sözcükler (değişken genişletme, VAR=..., $FOO, * vb. yoktur)
• güvenli işleçlerle birleştirilmişse (&&, ||, ; veya |)

Codex bunu ayrıştırır (tree-sitter kullanarak) ve kurallarınızı uygulamadan önce tek tek komutlara böler.

Yukarıdaki betik iki ayrı komut olarak değerlendirilir:

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

Codex daha sonra her komutu kurallarınıza göre değerlendirir ve en kısıtlayıcı sonuç geçerli olur.

pattern=["git", "add"] öğesine izin verseniz bile Codex git add . && rm -rf / öğesine otomatik olarak izin vermez; çünkü rm -rf / bölümü ayrı değerlendirilir ve tüm çağrının otomatik olarak izin almasını engeller.

Bu, tehlikeli komutların güvenli komutların yanına gizlenmesini önler.

Codex betiği bölmediğinde

Betik aşağıdakiler gibi daha gelişmiş kabuk özellikleri kullanıyorsa:

• yönlendirme (>, >>, <)
• ikameler ($(...), ...)
• ortam değişkenleri (FOO=bar)
• joker karakter kalıpları (*, ?)
• denetim akışı (if, for, atamalarla && vb.)

Codex bunu yorumlamaya veya bölmeye çalışmaz.

Bu durumlarda çağrının tamamı şöyle değerlendirilir:

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

ve kurallarınız bu tek çağrıya uygulanır.

Bu işleyiş sayesinde güvenli olduğunda komut başına değerlendirmenin güvenliğini, güvenli olmadığında ise ihtiyatlı davranışı elde edersiniz.

Kural dosyasını test etme

Kurallarınızın bir komuta nasıl uygulandığını test etmek için codex execpolicy check kullanın:

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

Komut, eşleşen kurallardaki justification değerleri dâhil olmak üzere en katı kararı ve eşleşen kuralları gösteren JSON üretir. Dosyaları birleştirmek için birden fazla --rules bayrağı kullanın ve çıktıyı biçimlendirmek için --pretty ekleyin.

Kurallar dilini anlama

.rules dosya biçimi Starlark kullanır (dil belirtimine bakın). Söz dizimi Python'a benzer, ancak güvenle çalıştırılmak üzere tasarlanmıştır: Kurallar motoru bunu yan etki oluşturmadan (örneğin dosya sistemine dokunmadan) çalıştırabilir.