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

# Policies

> Policies combine expressions, action requirements, entity bindings, mitigations, and windows into runtime rules.

A policy can bind together:

* A shared traffic expression that acts as the policy's broad traffic scope.
* One or more policy clauses.
* Deployment status.

Each clause then carries its own match condition, action requirements, optional
entity definition, mitigation, and optional rolling window.

<Info>
  **Policy scope and clause matches are evaluated in order.** The policy traffic
  scope decides whether a request is eligible for the policy at all. Each clause
  then evaluates its own match condition before applying its mitigation, action
  requirements, entity binding, and window. If you choose **Apply to all
  traffic**, every request enters the policy, but clause match conditions can
  still narrow behavior. For example: policy scope `Always`, clause match
  `query param foo Eq bar`, clause mitigation `Turnstile`.
</Info>

## Built-in default policies

Esper includes built-in policy presets so operators can start from common
evaluation patterns instead of composing every policy from scratch. This list
will expand as more defaults are added.

### Monitor

* Purpose: Observe matched traffic over a bounded analysis window before you
  decide on active mitigation.
* Behavior: Esper records the traffic as monitored traffic and returns an
  observe-style outcome instead of deploying a mitigation.
* Configuration model: This preset does not require action bindings, entity
  bindings, or a mitigation definition.
* When to use it: Start here when you want to understand the traffic pattern,
  validate the expression, and size the analysis window before moving to
  `Challenge` or `Block` style responses.

If you are building policies through the CLI, `esper policy create --template
default` generates a starter custom policy definition you can adapt for your
tenant. That template is not the same thing as a built-in preset.

## What you configure in a policy

When creating a policy, you define:

* `name`: The label operators use to recognize the policy.
* `description`: A short explanation of what the policy is meant to catch.
* `expression`: The shared traffic condition that starts policy evaluation.
* `clauses`: One or more policy clauses with their own match conditions,
  actions, entities, mitigations, and optional windows.

For each clause, you choose the supporting configuration Esper should apply:

* the clause match condition, such as a query parameter, path, header, cookie,
  or request field
* actions that must also match
* an optional entity definition for grouping and state
* the mitigation to apply when the clause wins
* an optional rolling window for repeated behavior

## Windows

Windows are how you tell Esper to look for repeated traffic over a short period
of time.

In plain language, a policy clause window lets you say:

* "Challenge this traffic if the same entity sends 5 or more events in 1 minute."
* "Block this traffic if the same session sends 20 or more events in 5 minutes."
* "Challenge this traffic if one entity accounts for more than 20% of tenant traffic in 1 hour."

Today, windows are configured on policy clauses in the **Policies** screen.
They are not set up on the **Actions** screen or the **Entities** screen.

### What you can choose

Esper currently supports these policy windows:

* 1 minute
* 3 minutes
* 5 minutes
* 60 minutes

Each policy clause window asks Esper to:

1. group traffic by the selected entity, session, or tenant scope
2. look back over the selected time period
3. either count matching events or compare one scope's traffic share against another
4. compare that result to the threshold you chose

### Count vs traffic-share windows

Esper supports two clause window modes:

* Absolute count: compare a scope's raw event count in the rolling window.
* Traffic share: compare a numerator scope against a denominator scope over the
  same rolling window.

Traffic-share windows are how you express policies like:

* "For `ip + user_agent`, challenge once one actor exceeds 20% of tenant traffic in 1 hour."

The most common ratio shape is:

* numerator scope: `Entity`
* denominator scope: `Tenant`
* counter: `EventCount`
* operator: `Gt` or `Ge`
* threshold: a percentage from greater than 0 to 100

### When to use a window

Use a policy clause window when one request by itself is not enough to act on, but a
short burst of repeated traffic is meaningful.

Good examples:

* repeated login attempts from the same account
* repeated checkout calls from the same session
* repeated API traffic from the same actor in a short burst

If you only care about a single request, you do not need a window.

<Info>
  **Window Setup For Non-Technical Users**

  Think of a policy window as a "look back" setting.

  You are telling Esper:

  * who to watch: the same entity or the same session
  * or, for traffic-share windows, which scope to compare against tenant traffic
  * how far to look back: 1, 3, 5, or 60 minutes
  * how much repeated traffic is too much: your threshold value or percentage

  Example:

  * Policy expression: request looks like a login attempt
  * Window: same entity, last 3 minutes
  * Threshold: 5 or more events
  * Result: Esper can challenge or block traffic only after that repeated pattern appears
</Info>