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

# Timestamp

> Working with time-based fields in Esper policies.

## What is a Timestamp?

A timestamp records exactly when Esper observed a request. It's essential for understanding patterns, detecting attacks, and analyzing behavior over time.

<Info>
  **MDN Web Docs**

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

## Timestamp Formats

### ISO 8601 (Recommended)

```
2024-03-19T10:15:30.000Z
2024-03-19T10:15:30+00:00
```

### Unix Timestamp

```
1710842130  (seconds since 1970)
1710842130000  (milliseconds)
```

### Components

* **Date**: 2024-03-19
* **Time**: 10:15:30
* **Milliseconds**: .000
* **Timezone**: Z or +00:00 (UTC)

## Using Timestamps in Policies

### Basic Examples

**Business hours only:**

```yaml theme={null}
Field Type: Timestamp
Operator: hour not between
Value: 09:00-17:00
AND
Field Type: Request Path
Operator: starts with
Value: /admin
Action: Block
```

**Weekend restrictions:**

```yaml theme={null}
Field Type: Timestamp
Operator: day of week in
Value: Saturday, Sunday
AND
Field Type: Request Path
Operator: starts with
Value: /business
Action: Challenge
```

### Advanced Time Windows

**Rate limiting with time windows:**

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

**Burst detection:**

```yaml theme={null}
Field Type: Client IP
Window: 10 seconds
Threshold: 50 requests
Action: Block
```

## Time-Based Attack Patterns

### Timing Attacks

| Pattern             | What to Look For          | Detection Strategy             |
| ------------------- | ------------------------- | ------------------------------ |
| Brute Force         | Rapid sequential attempts | High frequency, short window   |
| Slow Brute Force    | Spread out attempts       | Lower frequency, longer window |
| Time-of-Day Attacks | Off-hours activity        | Business hours check           |
| Coordinated Attacks | Synchronized timing       | Multiple IPs, same second      |

### Impossible Travel

```yaml theme={null}
# Login from NYC then Tokyo in 1 hour
Previous login: New York @ 10:00
Current login: Tokyo @ 11:00
Physical possibility: No
Action: Challenge
```

## Working with Time Windows

### Window Types

**Fixed Windows:**

```yaml theme={null}
Every minute: 10:00:00-10:00:59
Every hour: 10:00:00-10:59:59
Every day: 00:00:00-23:59:59
```

**Sliding Windows:**

```yaml theme={null}
Last 60 seconds from now
Last 5 minutes from now
Last 24 hours from now
```

## Best Practices

### DO:

* **Use UTC** for consistency across timezones
* **Include milliseconds** for precise ordering
* **Set appropriate windows** for your use case
* **Consider timezone** of legitimate users
* **Account for clock skew** between systems
* **Log timestamp mismatches** for investigation

### DON'T:

* **Rely on client timestamps** - Use server time
* **Ignore timezone differences** - Can cause false positives
* **Use overly tight windows** - Network delays happen
* **Forget about DST** - Daylight saving time changes
* **Block based on time alone** - Combine with other signals

## Time Zone Considerations

### Global Operations

```yaml theme={null}
# Different rules for different regions
If Client IP in Asia:
  Business hours: 09:00-17:00 JST
If Client IP in Europe:
  Business hours: 09:00-17:00 CET
If Client IP in Americas:
  Business hours: 09:00-17:00 EST
```

### UTC Best Practice

```yaml theme={null}
# Always store and compare in UTC
Timestamp: 2024-03-19T15:00:00Z
NOT
Timestamp: 2024-03-19T10:00:00-05:00
```

## Behavioral Analysis

### Session Duration

```yaml theme={null}
# Unusually long sessions
Session start: 09:00:00
Current time: 21:00:00
Duration: 12 hours
Action: Re-authenticate
```

### Activity Patterns

```yaml theme={null}
# Detect automated behavior
Requests every: 60.000 seconds (exactly)
Pattern: Automated/Bot
Action: Challenge
```

### Velocity Checks

```yaml theme={null}
# Too many actions too fast
Actions in last minute: 50
Normal user maximum: 10
Action: Rate limit
```

## Common Issues

### Clock Synchronization

**Problem:** Servers have different times
**Solution:** Use NTP for time sync

### Timezone Confusion

**Problem:** Mixing local and UTC times
**Solution:** Standardize on UTC

### Millisecond Precision

**Problem:** Losing order of rapid events
**Solution:** Include milliseconds/microseconds

## Advanced Patterns

### Business Logic Enforcement

```yaml theme={null}
# Stock market hours only
Field Type: Request Path
Operator: starts with
Value: /trading
AND
Field Type: Timestamp
Operator: not between
Value: 09:30-16:00 EST weekdays
Action: Block
```

### Scheduled Maintenance

```yaml theme={null}
# Block during maintenance windows
Field Type: Timestamp
Operator: between
Value: Sunday 02:00-04:00 UTC
Action: Show maintenance page
```

### Correlation Windows

```yaml theme={null}
# Correlate events within time window
If Event A occurs:
  Watch for Event B within 5 minutes
  If found: Trigger alert
```

## Forensics and Investigation

### Timeline Analysis

```
10:00:00 - First reconnaissance
10:05:30 - Vulnerability scanning
10:15:45 - Exploit attempt
10:16:00 - Successful breach
10:16:30 - Data exfiltration
```

### Pattern Identification

```yaml theme={null}
# Regular pattern = automated
Every 300 seconds: GET /api/data
Variance: < 1 second
Conclusion: Automated scraping
```

## Integration with Other Fields

### Time + IP Analysis

```yaml theme={null}
Field Type: Timestamp
Window: 1 hour
AND
Field Type: Client IP
Unique count > 1000
Action: DDoS protection
```

### Time + User Behavior

```yaml theme={null}
Field Type: Timestamp
Hour: 03:00-04:00 local
AND
Field Type: Request Path
Operator: equals
Value: /admin
AND
Field Type: User Role
Operator: not equals
Value: admin
Action: Block
```

## Troubleshooting

**"False positives at midnight"**

* Check timezone handling
* Verify date rollover logic
* Account for UTC vs local time

**"Window not capturing events"**

* Confirm window boundaries
* Check inclusive/exclusive logic
* Verify timestamp precision

**"Rate limits too strict/loose"**

* Analyze actual traffic patterns
* Adjust windows and thresholds
* Consider business patterns

## Related Fields

* [Client IP](./client-ip) - Track per-IP time patterns
* [Cookies](./cookies) - Session duration tracking
* [Request Path](./request-path) - Time-based access control
* [User Agent](./user-agent) - Traffic protection with timing