Skip to main content

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.

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.
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.

​
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.
Window Setup For Non-Technical UsersThink 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