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

# Query Parameters

> Working with URL query parameters in Esper policies.

## What are Query Parameters?

Query parameters are key-value pairs that appear after the `?` in a URL. They send additional data to the server without being part of the main path.

<Info>
  **MDN Web Docs**

  Read more on [URL query parameters](https://developer.mozilla.org/en-US/docs/Web/API/URL/searchParams).
</Info>

## Understanding Query Parameter Structure

```
https://shop.com/products?category=shoes&size=10&color=black
                          └─────────query parameters─────────┘
```

Breaking this down:

* `category` = shoes
* `size` = 10
* `color` = black

## Common Query Parameter Uses

### Search & Filtering

* `?q=search+term` - Search queries
* `?sort=price` - Sorting options
* `?filter=available` - Filtering results
* `?page=2` - Pagination

### Tracking & Analytics

* `?utm_source=email` - Marketing attribution
* `?ref=homepage` - Referral tracking
* `?session=abc123` - Session tracking

### API Parameters

* `?api_key=xxx` - Authentication (not recommended!)
* `?format=json` - Response format
* `?limit=100` - Result limits
* `?fields=id,name` - Field selection

### Application Control

* `?debug=true` - Debug mode (dangerous in production!)
* `?redirect=/dashboard` - Post-login redirects
* `?action=delete` - Action specification

## Using Query Parameters in Policies

### Basic Examples

**Block debug parameters in production:**

```yaml theme={null}
Field Type: Query Parameter
Field Reference: debug
Operator: is present
Action: Block
```

**Monitor high-value searches:**

```yaml theme={null}
Field Type: Query Parameter
Field Reference: price_min
Operator: greater than
Value: 1000
Action: Monitor
```

### Advanced Patterns

**Detect SQL injection attempts:**

```yaml theme={null}
Field Type: Query Parameter
Field Reference: q
Operator: contains
Value: SELECT
OR
Value: DROP
OR
Value: UNION
Action: Block
```

**Rate limit search API:**

```yaml theme={null}
Field Type: Request Path
Operator: equals
Value: /api/search
AND
Field Type: Query Parameter
Field Reference: q
Operator: is present
Window: 1 minute
Threshold: 30
Action: Challenge
```

<Warning>
  **Security Alert**

  Never put sensitive data like passwords or API keys in query parameters - they appear in logs, browser history, and can be leaked through referrer headers!
</Warning>

## Query Parameter Operators

| Operator       | Use Case           | Example                     |
| -------------- | ------------------ | --------------------------- |
| equals         | Exact value match  | `action=delete`             |
| contains       | Substring match    | search contains "script"    |
| starts with    | Prefix match       | ref starts with "partner\_" |
| is present     | Parameter exists   | debug is present            |
| is not present | Parameter missing  | api\_key is not present     |
| greater than   | Numeric comparison | limit > 1000                |
| matches regex  | Pattern matching   | matches `^[0-9]+$`          |

## Security Considerations

### Dangerous Query Parameters

| Parameter    | Risk                   | What to Do              |
| ------------ | ---------------------- | ----------------------- |
| `debug=true` | Exposes sensitive info | Block in production     |
| `admin=1`    | Privilege escalation   | Block unless authorized |
| `redirect=`  | Open redirect attacks  | Validate destinations   |
| `file=`      | Path traversal         | Sanitize file paths     |
| `sql=`       | Direct SQL execution   | Block immediately       |

### Common Attack Patterns

**Open Redirect Detection:**

```yaml theme={null}
Field Type: Query Parameter
Field Reference: redirect
Operator: starts with
Value: http
Action: Block # Only allow relative redirects
```

**Path Traversal Prevention:**

```yaml theme={null}
Field Type: Query Parameter
Field Reference: file
Operator: contains
Value: ../
Action: Block
```

## Best Practices

### DO:

* **Validate parameter values** - Check for expected formats and ranges
* **Monitor unusual parameters** - Unknown parameters might indicate probing
* **Limit parameter sizes** - Extremely long values can cause issues
* **Encode special characters** - Prevent injection attacks
* **Track parameter combinations** - Certain combos might indicate attacks

### DON'T:

* **Trust user input** - Always validate query parameters
* **Expose internal parameters** - Hide debug/admin params in production
* **Use for sensitive data** - Passwords, tokens shouldn't be in URLs
* **Ignore encoding** - URL encoding can hide malicious content
* **Allow unlimited values** - Set reasonable limits

## Working with Multiple Parameters

Often you need to check multiple parameters together:

```yaml theme={null}
# Detect unexpected privilege parameters
Field Type: Query Parameter
Field Reference: user_id
Operator: is present
AND
Field Type: Query Parameter
Field Reference: admin
Operator: equals
Value: true
Action: Block
```

## URL Encoding Gotchas

<Info>
  **Encoding Awareness**

  Query parameters are URL encoded:

  * Space becomes `+` or `%20`
  * `&` becomes `%26`
  * `=` becomes `%3D`

  Your policies should account for both encoded and decoded values.
</Info>

## Real-World Scenarios

### E-commerce Protection

```yaml theme={null}
# Prevent price manipulation
Field Type: Query Parameter
Field Reference: price
Operator: is present
AND
Field Type: Request Path
Operator: equals
Value: /checkout
Action: Block  # Price should come from server
```

### API Rate Limiting

```yaml theme={null}
# Different limits for different operations
Field Type: Query Parameter
Field Reference: operation
Operator: equals
Value: bulk_export
Window: 1 hour
Threshold: 5
Action: Block
```

### Search Protection

```yaml theme={null}
# Prevent search spam
Field Type: Query Parameter
Field Reference: q
Operator: length greater than
Value: 100
Action: Challenge
```

## Troubleshooting

**"My query parameter policy isn't matching"**

* Check URL encoding (spaces, special chars)
* Verify parameter name exactly
* Multiple values might use arrays (`tag[]=a&tag[]=b`)
* Some frameworks modify parameter names

**"False positives with legitimate traffic"**

* Your pattern might be too broad
* Consider parameter context (same param, different endpoints)
* URL encoding might cause unexpected matches
* Use monitoring before blocking

## Integration Examples

### With Other Fields

```yaml theme={null}
# Only allow debug from internal IPs
Field Type: Query Parameter
Field Reference: debug
Operator: is present
AND
Field Type: Client IP
Operator: not in range
Value: 10.0.0.0/8
Action: Block
```

## Related Fields

* [Request Path](./request-path) - Parameters extend path functionality
* [Headers](./headers) - Some apps send params in headers too
* [Body Data](./body-data) - POST requests might use body instead
* [Cookies](./cookies) - Session data alternative to URL params