> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rafter.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Policy File

> Configure project-level security policies with .rafter.yml

# Policy File (.rafter.yml)

The `.rafter.yml` file defines project-level security policies that override your global `~/.rafter/config.json` settings. Place it in your project root and Rafter picks it up automatically.

## How It Works

When any `rafter agent` command runs, the CLI walks from your current directory up to the git root looking for `.rafter.yml` or `.rafter.yaml`. If found, its values merge into the loaded config with **policy file winning** on conflicts.

Arrays like `blocked_patterns` **replace** the corresponding `~/.rafter/config.json` values entirely rather than appending. Note that hardcoded defaults (e.g. the built-in exclusion list and 21+ secret patterns) always apply regardless of what the policy file sets.

## Full Schema

```yaml theme={null}
version: "1"

# Override global risk level for this project
risk_level: moderate  # minimal | moderate | aggressive

# Policy enforcement rules
command_policy:
  mode: approve-dangerous  # allow-all | approve-dangerous | deny-list
  blocked_patterns:
    - "rm -rf /"
    - "curl.*|.*sh"
  require_approval:
    - "npm publish"
    - "git push --force"

# Secret scanning configuration
scan:
  exclude_paths:
    - "vendor/"
    - "third_party/"
    - "fixtures/"
  custom_patterns:
    - name: "Internal API Key"
      regex: "INTERNAL_[A-Z0-9]{32}"
      severity: critical
    - name: "Staging Token"
      regex: "stg_[a-zA-Z0-9]{24}"
      severity: high

# Audit log settings
audit:
  retention_days: 90
  log_level: info  # debug | info | warn | error
```

All fields are optional. Only specify what you need to override.

## Custom Scan Patterns

Add organization-specific secret patterns that the default 21 patterns don't cover:

```yaml theme={null}
scan:
  custom_patterns:
    - name: "Internal API Key"
      regex: "INTERNAL_[A-Z0-9]{32}"
      severity: critical
    - name: "Deploy Token"
      regex: "deploy_[a-f0-9]{40}"
      severity: high
```

Each pattern requires:

* **name**: Human-readable identifier shown in scan output
* **regex**: JavaScript-compatible regular expression
* **severity**: `critical`, `high`, `medium`, or `low`

Custom patterns are added alongside the default patterns, not replacing them.

## Exclude Paths

Skip directories during secret scanning:

```yaml theme={null}
scan:
  exclude_paths:
    - "vendor/"
    - "third_party/"
    - "test/fixtures/"
```

These are directory names matched against path segments. The default exclusions (`node_modules`, `.git`, `dist`, `build`, `.next`, `coverage`, `.vscode`, `.idea`) always apply. Your `exclude_paths` add to that list.

## Command Policy Overrides

Lock down command execution rules per project:

```yaml theme={null}
command_policy:
  mode: deny-list
  blocked_patterns:
    - "rm -rf /"
    - "docker system prune"
  require_approval:
    - "npm publish"
    - "terraform apply"
```

This is useful for monorepos or shared projects where different teams need different security boundaries.

## Precedence Rules

When both `~/.rafter/config.json` (global) and `.rafter.yml` (project) define the same setting, the project policy file wins. How the merge works depends on the setting type:

| Setting                           | Merge behavior                                                             |
| --------------------------------- | -------------------------------------------------------------------------- |
| `risk_level`                      | Project policy overrides global config                                     |
| `command_policy.mode`             | Project policy overrides global config                                     |
| `command_policy.blocked_patterns` | Project policy **replaces** global config (not merged)                     |
| `command_policy.require_approval` | Project policy **replaces** global config (not merged)                     |
| `scan.custom_patterns`            | **Added** alongside the built-in 21+ patterns                              |
| `scan.exclude_paths`              | **Added** alongside the built-in exclusions (`node_modules`, `.git`, etc.) |

In short: scalar values are overridden, `command_policy` arrays are replaced wholesale, and `scan` arrays are additive.

## Best Practices

<Card title="Recommendations" icon="list-check">
  1. Commit `.rafter.yml` to version control so the whole team gets the same policies
  2. Start with `risk_level: moderate` and tighten as needed
  3. Add custom patterns for any organization-specific secret formats
  4. Use `exclude_paths` for vendored code or generated files
</Card>

## Next Steps

<CardGroup cols={2}>
  <Card title="Secret Scanning" icon="magnifying-glass" href="/guides/agent-security/secret-scanning">
    Learn about scan options and output
  </Card>

  <Card title="Command Execution" icon="terminal" href="/guides/agent-security/command-execution">
    Configure policy enforcement
  </Card>
</CardGroup>