History

zhao-oai 3d35cb4619 Refactor execpolicy fallback evaluation (#7544 ) ## Refactor of the `execpolicy` crate To illustrate why we need this refactor, consider an agent attempting to run `apple \| rm -rf ./`. Suppose `apple` is allowed by `execpolicy`. Before this PR, `execpolicy` would consider `apple` and `pear` and only render one rule match: `Allow`. We would skip any heuristics checks on `rm -rf ./` and immediately approve `apple \| rm -rf ./` to run. To fix this, we now thread a `fallback` evaluation function into `execpolicy` that runs when no `execpolicy` rules match a given command. In our example, we would run `fallback` on `rm -rf ./` and prevent `apple \| rm -rf ./` from being run without approval.		2025-12-03 23:39:48 -08:00
..
examples	migrating execpolicy -> execpolicy-legacy and execpolicy2 -> execpolicy (#6956 )	2025-11-19 19:14:10 -08:00
src	Refactor execpolicy fallback evaluation (#7544 )	2025-12-03 23:39:48 -08:00
tests	Refactor execpolicy fallback evaluation (#7544 )	2025-12-03 23:39:48 -08:00
Cargo.toml	execpolicy helpers (#7032 )	2025-12-02 15:05:27 -05:00
README.md	Refactor execpolicy fallback evaluation (#7544 )	2025-12-03 23:39:48 -08:00

README.md

codex-execpolicy

Overview

Policy engine and CLI built around prefix_rule(pattern=[...], decision?, match?, not_match?).
This release covers the prefix-rule subset of the execpolicy language; a richer language will follow.
Tokens are matched in order; any pattern element may be a list to denote alternatives. decision defaults to allow; valid values: allow, prompt, forbidden.
match / not_match supply example invocations that are validated at load time (think of them as unit tests); examples can be token arrays or strings (strings are tokenized with shlex).
The CLI always prints the JSON serialization of the evaluation result.
The legacy rule matcher lives in codex-execpolicy-legacy.

Policy shapes

Prefix rules use Starlark syntax:

prefix_rule(
    pattern = ["cmd", ["alt1", "alt2"]], # ordered tokens; list entries denote alternatives
    decision = "prompt",                 # allow | prompt | forbidden; defaults to allow
    match = [["cmd", "alt1"], "cmd alt2"],           # examples that must match this rule
    not_match = [["cmd", "oops"], "cmd alt3"],       # examples that must not match this rule
)

CLI

From the Codex CLI, run codex execpolicy check subcommand with one or more policy files (for example src/default.codexpolicy) to check a command:

codex execpolicy check --policy path/to/policy.codexpolicy git status

Pass multiple --policy flags to merge rules, evaluated in the order provided, and use --pretty for formatted JSON.
You can also run the standalone dev binary directly during development:

cargo run -p codex-execpolicy -- check --policy path/to/policy.codexpolicy git status

Example outcomes:
- Match: {"matchedRules":[{...}],"decision":"allow"}
- No match: {"matchedRules":[]}

Response shape

{
  "matchedRules": [
    {
      "prefixRuleMatch": {
        "matchedPrefix": ["<token>", "..."],
        "decision": "allow|prompt|forbidden"
      }
    }
  ],
  "decision": "allow|prompt|forbidden"
}

When no rules match, matchedRules is an empty array and decision is omitted.
matchedRules lists every rule whose prefix matched the command; matchedPrefix is the exact prefix that matched.
The effective decision is the strictest severity across all matches (forbidden > prompt > allow).

Note: execpolicy commands are still in preview. The API may have breaking changes in the future.