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

# Headers

> Using HTTP headers in Esper policies.

## What are HTTP Headers?

Headers are key-value pairs sent with every HTTP request and response. They carry important metadata about the request, like authentication tokens, content types, and client information.

<Info>
  **MDN Web Docs**

  Read more on [HTTP headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers).
</Info>

## Common Headers You'll Encounter

### Authentication & Security

* **Authorization**: Bearer tokens, API keys
* **Cookie**: Session identifiers
* **X-API-Key**: Custom API authentication
* **X-CSRF-Token**: Cross-site request forgery protection

### Content & Format

* **Content-Type**: Format of request body (application/json, text/html)
* **Accept**: What formats the client can handle
* **Content-Length**: Size of the request body

### Client Information

* **User-Agent**: Browser or application identifier
* **Referer**: Previous page URL
* **X-Forwarded-For**: Original IP behind proxies
* **Host**: Target domain

### Custom Headers

* **X-Request-ID**: Request tracking
* **X-Customer-ID**: Business identifiers
* **X-Feature-Flag**: Feature toggles

## How Headers Work on the Web

Headers flow through every web interaction:

1. **Browser adds headers** automatically (User-Agent, Accept, etc.)
2. **JavaScript adds headers** for API calls (Authorization, Custom headers)
3. **Proxies add headers** (X-Forwarded-For, X-Real-IP)
4. **Your app reads headers** for authentication and routing

## Using Headers in Policies

### Basic Examples

**Block requests missing authentication:**

```yaml theme={null}
Field Type: Header
Field Reference: Authorization
Operator: is not present
AND
Field Type: Request Path
Operator: starts with
Value: /api
Action: Block
```

**Detect suspicious User-Agents:**

```yaml theme={null}
Field Type: Header
Field Reference: User-Agent
Operator: contains
Value: bot
Action: Challenge
```

### Advanced Patterns

**Rate limit by API key:**

```yaml theme={null}
Field Type: Header
Field Reference: X-API-Key
Operator: equals
Value: xyz123
Window: 1 minute
Threshold: 100
Action: Challenge
```

**Verify content type for uploads:**

```yaml theme={null}
Field Type: Request Path
Operator: equals
Value: /upload
AND
Field Type: Header
Field Reference: Content-Type
Operator: not equals
Value: multipart/form-data
Action: Block
```

<Info>
  **Example**

  Unusual header combinations can identify requests that should be monitored or
  blocked by policy.
</Info>

## Header Operators

| Operator       | Use Case       | Example                            |
| -------------- | -------------- | ---------------------------------- |
| equals         | Exact match    | `Authorization: Bearer abc123`     |
| contains       | Partial match  | User-Agent contains "Python"       |
| starts with    | Prefix match   | Authorization starts with "Bearer" |
| is present     | Header exists  | X-Custom-Header is present         |
| is not present | Header missing | Authorization is not present       |

## Security-Critical Headers

### Headers to Monitor Closely

| Header          | Why It's Important   | What to Look For               |
| --------------- | -------------------- | ------------------------------ |
| Authorization   | Contains credentials | Missing, malformed tokens      |
| X-Forwarded-For | Real client IP       | IP spoofing attempts           |
| Origin          | Request source       | Cross-origin attacks           |
| Content-Type    | Data format          | Unexpected types for endpoints |
| Host            | Target domain        | Host header injection          |

### Headers That Reveal Attacks

```yaml theme={null}
# Detect command injection attempts
Field Type: Header
Field Reference: User-Agent
Operator: contains
Value: curl
OR
Value: wget
OR
Value: python
Action: Monitor
```

## Best Practices

### DO:

* **Validate authentication headers** - Ensure they're present and properly formatted
* **Check Content-Type** - Match expected formats for each endpoint
* **Monitor custom headers** - Track your application-specific headers
* **Look for header anomalies** - Unusual combinations can reveal attacks
* **Use header presence checks** - Sometimes missing headers are suspicious

### DON'T:

* **Trust client headers blindly** - They can be spoofed
* **Block common User-Agents carelessly** - You might block legitimate users
* **Forget about case sensitivity** - HTTP headers are case-insensitive
* **Expose sensitive data** - Never put passwords or secrets in headers
* **Ignore header injection** - Validate header values for malicious content

## Common Attack Patterns

### Header Injection

```yaml theme={null}
Field Type: Header
Field Reference: Host
Operator: contains
Value: evil.com
Action: Block
```

### Authentication Bypass Attempts

```yaml theme={null}
Field Type: Header
Field Reference: X-Admin
Operator: is present
Action: Block # If your app doesn't use this header
```

### Traffic Protection

```yaml theme={null}
Field Type: Header
Field Reference: User-Agent
Operator: matches regex
Value: (bot|crawl|spider|scrape)
Action: Challenge
```

## Working with Multiple Headers

Sometimes you need to check multiple headers together:

```yaml theme={null}
# Suspicious: Claims to be Chrome but wrong header combination
Field Type: Header
Field Reference: User-Agent
Operator: contains
Value: Chrome
AND
Field Type: Header
Field Reference: Accept-Language
Operator: is not present
Action: Challenge
```

<Tip>
  **Header Fingerprinting**

  Legitimate browsers send consistent header sets. Missing expected headers or unusual combinations often indicate bots or attack tools.
</Tip>

## Custom Headers for Your Application

Many applications use custom headers:

```yaml theme={null}
# Your app's feature flag header
Field Type: Header
Field Reference: X-Feature-Beta
Operator: equals
Value: enabled

# Tenant identification
Field Type: Header
Field Reference: X-Tenant-ID
Operator: is present
```

## Troubleshooting

**"My header policy isn't matching"**

* Headers are case-insensitive but values might not be
* Check for spaces and special characters
* Verify the exact header name in browser DevTools
* Some proxies modify headers

**"I'm seeing unexpected header values"**

* Proxies and load balancers add headers
* Browsers send different headers than mobile apps
* Some security tools modify User-Agent

## Related Fields

* [Request Method](./request-method) - Headers vary by method
* [Cookies](./cookies) - Special header for session data
* [Client IP](./client-ip) - Often in X-Forwarded-For header
* [User Agent](./user-agent) - Specific header for client identification