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

# Client IP

> Using IP addresses for traffic analysis in Esper.

## What is a Client IP?

The client IP address identifies where a request comes from on the internet. It's like a return address that allows servers to send responses back to the right place.

<Info>
  **MDN Web Docs**

  Read more on [IP addresses](https://developer.mozilla.org/en-US/docs/Glossary/IP_Address).
</Info>

## Understanding IP Addresses

### IPv4 vs IPv6

* **IPv4**: Traditional format like `192.168.1.1` (4 billion addresses)
* **IPv6**: Newer format like `2001:0db8:85a3::8a2e:0370:7334` (340 undecillion addresses)

### Public vs Private IPs

* **Public**: Routable on internet (`8.8.8.8`)
* **Private**: Internal networks (`10.x.x.x`, `192.168.x.x`, `172.16-31.x.x`)

### Special IP Ranges

* **Localhost**: `127.0.0.1` (the computer itself)
* **Documentation**: `192.0.2.0/24` (example IPs)
* **Cloudflare**: `1.1.1.1` (DNS)
* **Google DNS**: `8.8.8.8` (DNS)

## How IPs Work with Web Traffic

Real client IPs can be tricky to identify:

1. **Direct Connection**: Client IP is straightforward
2. **Behind NAT**: Multiple users share one public IP
3. **Through Proxy**: Proxy IP appears as client
4. **Via CDN**: CDN forwards real IP in headers
5. **Using VPN**: VPN server IP masks real location

<Warning>
  **IP Address Challenges**

  * Same IP might be many users (office, cafe WiFi)
  * User's IP can change (mobile networks)
  * VPNs/proxies hide real IPs
  * IPv6 privacy extensions rotate addresses
</Warning>

## Using Client IP in Policies

### Basic Examples

**Block specific IP:**

```yaml theme={null}
Field Type: Client IP
Operator: equals
Value: 203.0.113.5
Action: Block
```

**Allow office network only:**

```yaml theme={null}
Field Type: Client IP
Operator: not in range
Value: 10.0.0.0/8
AND
Field Type: Request Path
Operator: starts with
Value: /internal
Action: Block
```

### Advanced Patterns

**Geographic restrictions:**

```yaml theme={null}
Field Type: Client IP
Operator: in country
Value: CN, RU, KP
Action: Challenge
```

**Rate limiting by IP:**

```yaml theme={null}
Field Type: Client IP
Operator: any
Window: 1 minute
Threshold: 100
Action: Challenge
```

## Common IP Patterns

### Suspicious Patterns

* **Rapid location changes**: Same session, different countries
* **Impossible travel**: Login from NYC, then Tokyo 1 hour later
* **Data center IPs**: For consumer services
* **Known bad IPs**: Threat intelligence lists

### Legitimate Patterns

* **Mobile networks**: IPs change frequently
* **Corporate VPNs**: Shared IPs for employees
* **Public WiFi**: Many users, one IP
* **CDN/Proxy**: Headers show real IP

## Best Practices

### DO:

* **Use IP ranges** instead of individual IPs when possible
* **Consider proxy headers** like X-Forwarded-For
* **Combine with other signals** for better accuracy
* **Allow for IP changes** in mobile scenarios
* **Maintain IP allowlists** for trusted sources
* **Monitor before blocking** to understand patterns

### DON'T:

* **Rely on IP alone** for user identification
* **Block entire countries** without business reason
* **Ignore IPv6** - increasingly common
* **Trust client-provided IPs** in headers
* **Forget about shared IPs** - NAT, public WiFi

## Working with Proxies and CDNs

### Real IP Headers

```yaml theme={null}
# Check various headers for real IP
X-Forwarded-For: client, proxy1, proxy2
X-Real-IP: client
CF-Connecting-IP: client # Cloudflare
True-Client-IP: client # Akamai
```

### Policy for Real IP

```yaml theme={null}
Field Type: Header
Field Reference: X-Forwarded-For
Operator: starts with
Value: 10.0.0
Action: Allow # Internal network through proxy
```

## Geographic Considerations

### Country-Based Policies

```yaml theme={null}
# Block high-risk countries for payment
Field Type: Request Path
Operator: equals
Value: /checkout
AND
Field Type: Client IP Country
Operator: in
Value: [high_risk_countries]
Action: Challenge
```

### Compliance Requirements

```yaml theme={null}
# GDPR compliance - EU traffic only
Field Type: Client IP Region
Operator: not equals
Value: EU
AND
Field Type: Request Path
Operator: starts with
Value: /eu-services
Action: Block
```

## IP Forensics

<Info>
  **Investigation Techniques**

  1. **Reverse DNS lookup**: Find hostname
  2. **WHOIS query**: Identify owner
  3. **Geolocation**: Approximate location
  4. **ASN lookup**: Network operator
  5. **Reputation check**: Known issues
</Info>

## Troubleshooting

**"Wrong IP in logs"**

* Check proxy/CDN configuration
* Verify header extraction order
* Confirm load balancer settings
* Test with known IP sources

**"Blocking legitimate users"**

* Shared IPs (offices, cafes)
* VPN users (privacy-conscious)
* Mobile network IP changes
* Proxy/CDN misconfiguration

## Advanced Patterns

## Related Fields

* [Headers](./headers) - Real IP often in headers
* [User Agent](./user-agent) - Combine for device fingerprinting
* [Cookies](./cookies) - Track users across IP changes
* [Timestamp](./timestamp) - Detect impossible travel