Placeholders

Tokens wrapped in <...> are placeholders — special tokens that match dynamically rather than by exact string comparison.

Placeholder	Description
`<cmd>`	Captures the wrapped command for further rule evaluation
`<opts>`	Absorbs zero or more flag-like tokens
`<vars>`	Absorbs zero or more `KEY=VALUE` tokens
`<path:name>`	Matches against a named list of paths
`<var:name>`	Matches against a typed variable definition

Command (`<cmd>`)

The <cmd> placeholder captures the remaining tokens as the wrapped command. The wrapped command is then evaluated against the other rules in the configuration. See Wrapped Command Recursion for details.

# sudo echo hello -> wrapped command is "echo hello"
- allow: 'sudo <cmd>'

Defining Wrappers

Wrapper patterns are defined in the definitions.wrappers block and referenced by rules:

definitions:
  wrappers:
    - 'sudo <cmd>'
    - 'xargs <opts> <cmd>'

rules:
  - allow: 'echo *'
  # With the wrapper definition, this also allows:
  #   sudo echo hello
  #   xargs -I{} echo hello

Options (`<opts>`)

The <opts> placeholder absorbs zero or more flag-like tokens (tokens starting with -):

# Matches: env FOO=bar command
# Matches: env -i FOO=bar command
# Matches: env -u HOME -i FOO=bar command
- allow: 'env <opts> <vars> <cmd>'

<opts> stops consuming tokens when it encounters:

A token that does not start with -
The -- end-of-options marker

For short flags consisting of exactly - plus one ASCII letter (e.g., -n, -S), if the next token does not start with -, it is consumed as the flag’s argument:

# env -S "FOO=bar" command -> <opts> consumes "-S" and "FOO=bar"
- allow: 'env <opts> <cmd>'

Variables (`<vars>`)

The <vars> placeholder absorbs zero or more KEY=VALUE tokens — tokens that contain =:

# Matches: env command
# Matches: env FOO=bar command
# Matches: env FOO=bar BAZ=qux command
- allow: 'env <vars> <cmd>'

<vars> stops consuming tokens when it encounters a token without =.

Path References (`<path:name>`)

The <path:name> placeholder matches a command argument against a named list of paths defined in the definitions.paths block.

Defining Paths

definitions:
  paths:
    sensitive:
      - /etc/passwd
      - /etc/shadow
      - /etc/sudoers
    config:
      - /etc/nginx/nginx.conf
      - /etc/hosts

Using Path References

Reference a path list with <path:name>:

rules:
  - deny: 'cat <path:sensitive>'
  - deny: 'rm <path:sensitive>'
  - allow: 'cat <path:config>'

Command	Rule	Result
`cat /etc/passwd`	`deny: "cat <path:sensitive>"`	Denied
`cat /etc/hosts`	`allow: "cat <path:config>"`	Allowed
`rm /etc/shadow`	`deny: "rm <path:sensitive>"`	Denied

Path Normalization

Paths are normalized before comparison. The following path components are resolved:

. (current directory) is removed
.. (parent directory) is resolved

definitions:
  paths:
    sensitive:
      - /etc/passwd

Command	Matches `<path:sensitive>`
`cat /etc/passwd`	Yes
`cat /etc/./passwd`	Yes (`.` removed)
`cat /tmp/../etc/passwd`	Yes (`..` resolved)

This prevents bypassing path rules through path manipulation.

Undefined Path Names

If a pattern references a path name that is not defined in definitions.paths, the pattern never matches:

# If "sensitive" is not defined, this rule has no effect
- deny: 'cat <path:sensitive>'

Variable References (`<var:name>`)

The <var:name> placeholder matches a command argument against a typed variable definition in the definitions.vars block.

Defining Variables

Each variable has an optional type (default: literal) and a list of values:

definitions:
  vars:
    instance-ids:
      values:
        - i-abc123
        - i-def456
        - i-ghi789
    test-script:
      type: path
      values:
        - ./tests/run

Variable Types

Type	Matching behavior
`literal`	Exact string match (default)
`path`	Canonicalize both sides before comparison, fallback to path normalization

Using Variable References

rules:
  - allow: aws ec2 terminate-instances --instance-ids <var:instance-ids>
  - allow: bash <var:test-script>

Command	Rule	Result
`aws ec2 terminate-instances --instance-ids i-abc123`	`allow: "... --instance-ids <var:instance-ids>"`	Allowed
`aws ec2 terminate-instances --instance-ids i-UNKNOWN`	`allow: "... --instance-ids <var:instance-ids>"`	No match
`bash ./tests/run`	`allow: "bash <var:test-script>"`	Allowed
`bash tests/run`	`allow: "bash <var:test-script>"`	Allowed (path normalization)

Path Type Normalization

When type: path is set, both the command argument and the defined values are canonicalized (resolved to absolute paths via the filesystem). If the path does not exist on disk, logical normalization is used as a fallback (. removal and .. resolution).

This handles cases where the same file is referenced with different path forms:

definitions:
  vars:
    test-script:
      type: path
      values:
        - ./tests/run

Command	Matches `<var:test-script>`
`bash tests/run`	Yes
`bash ./tests/run`	Yes
`bash ./tests/../tests/run`	Yes
`bash ./scripts/deploy`	No

Undefined Variable Names

If a pattern references a variable name that is not defined in definitions.vars, the pattern never matches.

Combining Placeholders

Placeholders can be combined to handle complex wrapper patterns:

definitions:
  wrappers:
    # Handles: env [-i] [-u NAME] [KEY=VALUE...] command [args...]
    - 'env <opts> <vars> <cmd>'

    # Handles: sudo [-u user] command [args...]
    - 'sudo <opts> <cmd>'

    # Handles: xargs [flags...] command [args...]
    - 'xargs <opts> <cmd>'

    # Handles: find [args...] -exec|-execdir|-ok|-okdir command [args...] \;|+
    - "find * -exec|-execdir|-ok|-okdir <cmd> \\;|+"

Restrictions

<cmd> captures one or more tokens; it tries all possible split points to find a valid wrapped command
Optional groups, path references, and variable references are not supported inside wrapper patterns

Wrapped Command Recursion — How wrapper commands are recursively evaluated.
Configuration Schema — Wrapper and path definition reference.