3d35cb4619
## 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.
62 lines
2.3 KiB
Markdown
62 lines
2.3 KiB
Markdown
# Execpolicy quickstart
|
|
|
|
Codex can enforce your own rules-based execution policy before it runs shell commands. Policies live in Starlark `.codexpolicy` files under `~/.codex/policy`.
|
|
|
|
## Create a policy
|
|
|
|
1. Create a policy directory: `mkdir -p ~/.codex/policy`.
|
|
2. Add one or more `.codexpolicy` files in that folder. Codex automatically loads every `.codexpolicy` file in there on startup.
|
|
3. Write `prefix_rule` entries to describe the commands you want to allow, prompt, or block:
|
|
|
|
```starlark
|
|
prefix_rule(
|
|
pattern = ["git", ["push", "fetch"]],
|
|
decision = "prompt", # allow | prompt | forbidden
|
|
match = [["git", "push", "origin", "main"]], # examples that must match
|
|
not_match = [["git", "status"]], # examples that must not match
|
|
)
|
|
```
|
|
|
|
- `pattern` is a list of shell tokens, evaluated from left to right; wrap tokens in a nested list to express alternatives (for example, match both `push` and `fetch`).
|
|
- `decision` sets the severity; Codex picks the strictest decision when multiple rules match (forbidden > prompt > allow).
|
|
- `match` and `not_match` act as optional unit tests. Codex validates them when it loads your policy, so you get feedback if an example has unexpected behavior.
|
|
|
|
In this example rule, if Codex wants to run commands with the prefix `git push` or `git fetch`, it will first ask for user approval.
|
|
|
|
## Preview decisions
|
|
|
|
Use the `codex execpolicy check` subcommand to preview decisions before you save a rule (see the [`codex-execpolicy` README](../codex-rs/execpolicy/README.md) for syntax details):
|
|
|
|
```shell
|
|
codex execpolicy check --policy ~/.codex/policy/default.codexpolicy git push origin main
|
|
```
|
|
|
|
Pass multiple `--policy` flags to test how several files combine, and use `--pretty` for formatted JSON output. See the [`codex-rs/execpolicy` README](../codex-rs/execpolicy/README.md) for a more detailed walkthrough of the available syntax.
|
|
|
|
Example output when a rule matches:
|
|
|
|
```json
|
|
{
|
|
"matchedRules": [
|
|
{
|
|
"prefixRuleMatch": {
|
|
"matchedPrefix": ["git", "push"],
|
|
"decision": "prompt"
|
|
}
|
|
}
|
|
],
|
|
"decision": "prompt"
|
|
}
|
|
```
|
|
|
|
When no rules match, `matchedRules` is an empty array and `decision` is omitted.
|
|
|
|
```json
|
|
{
|
|
"matchedRules": []
|
|
}
|
|
```
|
|
|
|
## Status
|
|
|
|
`execpolicy` commands are still in preview. The API may have breaking changes in the future.
|