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

# Configure Custom Detection Policies

> Create YAML policy files to tune InferenceWall thresholds, enforcement mode, and per-signature overrides without any code changes or package modifications.

Policies separate detection configuration from detection logic. Instead of changing code to raise a block threshold or demote a noisy signature to monitor-only, you edit a YAML file. InferenceWall auto-discovers policy files at startup, so changes take effect on the next restart without any package modification.

<Steps>
  <Step title="Copy the default policy">
    ```bash theme={null}
    mkdir -p ~/.inferwall/policies
    cp $(python -c "import inferwall; print(inferwall.__path__[0])")/policies/default.yaml \
       ~/.inferwall/policies/my-policy.yaml
    ```

    This gives you the exact policy that ships with InferenceWall as a starting point, with all five thresholds and an empty `signatures` map.
  </Step>

  <Step title="Edit thresholds, mode, and per-signature overrides">
    Open `~/.inferwall/policies/my-policy.yaml` and modify the values you want to change:

    ```yaml theme={null}
    name: my-policy
    version: "1.0.0"
    mode: monitor                   # Start in monitor mode

    thresholds:
      inbound_flag: 6.0             # Raise flag threshold to reduce noise
      inbound_block: 12.0           # Raise block threshold
      outbound_flag: 4.0
      outbound_block: 8.0
      early_exit: 15.0

    signatures:
      INJ-D-001:
        action: enforce             # Force-enforce this signature even in monitor mode
        anomaly_points: 12          # Increase weight
      CS-T-003:
        action: monitor             # Demote to monitor-only
    ```
  </Step>

  <Step title="Point InferenceWall at your policy">
    Drop the file into `~/.inferwall/policies/` and InferenceWall will auto-discover it on the next startup. To explicitly select a specific file, set `IW_POLICY_PATH`:

    ```bash theme={null}
    export IW_POLICY_PATH=~/.inferwall/policies/my-policy.yaml
    ```

    `IW_POLICY_PATH` is useful in CI/CD pipelines or container deployments where you want deterministic policy selection rather than auto-discovery.
  </Step>
</Steps>

## Policy YAML fields

### Top-level fields

| Field        | Type                   | Description                                             |
| ------------ | ---------------------- | ------------------------------------------------------- |
| `name`       | string                 | Human-readable policy name for logging and audit events |
| `version`    | string                 | SemVer string; increment when you make changes          |
| `mode`       | `monitor` \| `enforce` | Global enforcement mode (see below)                     |
| `thresholds` | object                 | Five scoring thresholds (see below)                     |
| `signatures` | map                    | Per-signature overrides keyed by signature ID           |

### Thresholds

| Threshold        | Description                                   | Default | Strict |
| ---------------- | --------------------------------------------- | ------- | ------ |
| `inbound_flag`   | Score to flag an incoming request             | `4.0`   | `2.5`  |
| `inbound_block`  | Score to block an incoming request            | `10.0`  | `7.0`  |
| `outbound_flag`  | Score to flag an outgoing response            | `3.0`   | `2.0`  |
| `outbound_block` | Score to block an outgoing response           | `7.0`   | `5.0`  |
| `early_exit`     | Score at which downstream engines are skipped | `13.0`  | `10.0` |

### Enforcement modes

| Mode      | Behavior                                                                                      |
| --------- | --------------------------------------------------------------------------------------------- |
| `monitor` | All signatures run and log matches, but no blocking or flagging actions are taken             |
| `enforce` | Signatures contribute scores to threshold comparisons and trigger `flag` or `block` decisions |

### Per-signature overrides

Override individual signatures within the `signatures` map:

```yaml theme={null}
signatures:
  INJ-D-001:
    action: monitor        # Override to monitor even in global enforce mode
    anomaly_points: 3      # Lower scoring weight for this signature
  INJ-D-008:
    action: enforce        # Force enforce even in global monitor mode
```

| Field            | Values               | Description                                           |
| ---------------- | -------------------- | ----------------------------------------------------- |
| `action`         | `enforce`, `monitor` | Overrides the global mode for this specific signature |
| `anomaly_points` | `1`–`15`             | Overrides the signature's default scoring weight      |

## Override precedence

When multiple sources could set a signature's action, InferenceWall resolves them in this order (highest wins):

1. **Per-signature override** — `signatures.<ID>.action` in the policy file
2. **Global policy mode** — the top-level `mode` field
3. **Signature default action** — `tuning.default_action` in the signature YAML

## Environment variable

```bash theme={null}
export IW_POLICY_PATH=~/.inferwall/policies/my-policy.yaml
```

When set, InferenceWall loads exactly this file and skips auto-discovery. When unset, it discovers all `.yaml` files in `~/.inferwall/policies/`.

## Auto-discovery

Drop any `.yaml` file into `~/.inferwall/policies/` and InferenceWall will pick it up on the next startup. Use this when managing multiple policy profiles (e.g., `strict.yaml`, `permissive.yaml`) and switching between them by setting `IW_POLICY_PATH`.

<Tip>
  **Recommended rollout workflow**

  Roll out new policies gradually to avoid unexpected blocking in production:

  <Steps>
    <Step title="Deploy in monitor mode">
      Set `mode: monitor`. All signatures run and log matches, but no requests are blocked.
    </Step>

    <Step title="Observe logged matches">
      Watch the scan logs for 1–2 weeks. Identify which signatures fire most often and which generate false positives.
    </Step>

    <Step title="Allowlist false positives">
      For signatures that fire on known-benign traffic, set `action: monitor` in the per-signature overrides.
    </Step>

    <Step title="Enforce high-confidence signatures individually">
      Flip signatures you trust to `action: enforce` one at a time, monitoring the effect of each change.
    </Step>

    <Step title="Switch global mode to enforce">
      Once you're confident in the policy, set `mode: enforce` to activate blocking globally.
    </Step>
  </Steps>
</Tip>

## Further reading

<CardGroup cols={2}>
  <Card title="Policy concepts" href="/concepts/policies">
    How InferenceWall resolves policies, applies overrides, and manages the policy lifecycle.
  </Card>

  <Card title="Scoring concepts" href="/concepts/scoring">
    The anomaly scoring model: confidence weighting, diminishing corroboration, and threshold math.
  </Card>
</CardGroup>