# Cloudflare Firewall Events

Ingests Cloudflare firewall and WAF events using the GraphQL Analytics API. This input collects security events from the `firewallEventsAdaptive` dataset, including blocked requests, challenges, and other firewall actions taken on traffic to your zones.

**Sync Type: Incremental**

## Requirements

- A Cloudflare account with access to the Analytics API
- An API Token with the `Account Analytics:Read` permission
- Your Cloudflare Zone ID

### Data Retention by Plan

Cloudflare retains firewall event data based on your plan:

| Plan | Data Retention |
|------|----------------|
| Free | 24 hours |
| Pro | 3 days |
| Business | 3-30 days |
| Enterprise | 30-90 days |

The input automatically detects your plan's retention limits and adjusts queries accordingly.

### Creating an API Token

1. Log in to your Cloudflare dashboard
2. Navigate to **My Profile** > **API Tokens**
3. Click **Create Token**
4. Use the **Create Custom Token** option
5. Configure the token:
   - **Token name**: Give it a descriptive name (e.g., "Monad Firewall Events")
   - **Permissions**: Add `Account` > `Account Analytics` > `Read`
   - **Zone Resources**: Select the specific zone(s) or "All zones"
6. Click **Continue to summary** and then **Create Token**
7. Copy the token value (you won't be able to see it again)

### Finding Your Zone ID

1. Log in to your Cloudflare dashboard
2. Select the domain/zone you want to monitor
3. The Zone ID is displayed in the right sidebar on the overview page
4. It's a 32-character alphanumeric string

## Details

- **State Management**: Uses timestamp-based incremental sync with rayName as secondary sort key. Monad stores the last processed event timestamp to fetch only new events on subsequent runs.
- **API Endpoint**: GraphQL Analytics API (`/graphql`)
- **Dataset**: `firewallEventsAdaptive`
- **Pagination**: Filter-based pagination using `datetime_geq` and `rayName_gt` (the API does not support cursor pagination)
- **Rate Limits**: 300 requests per 5 minutes (1 request per second). The input automatically enforces this limit.
- **Adaptive Sampling**: During high-traffic periods, Cloudflare may apply sampling to this dataset. Not all events may be returned during very high volume periods.

## Configuration

### Settings

| Setting | Type | Required | Description |
|---------|------|----------|-------------|
| `zone_id` | string | Yes | Cloudflare Zone ID (32-character alphanumeric string) |
| `include_bot_fields` | boolean | No | Include `botScore` and `botScoreSrcName` fields. **Requires Enterprise plan with Bot Management add-on.** Leave disabled unless you have Bot Management enabled. Default: `false` |
| `lookback_duration` | string | No | Initial lookback duration for first sync (e.g., `24h`, `7d`). Must not exceed your plan's data retention limit. Default: Uses plan's maximum retention |
| API Rate Limit | object | No | Optional limit on the connector's outbound request rate to the source API. Leave blank to use the connector's default behavior. See [API Rate Limiting](../../../guides/rate-limiting) for the field format, limits, and how to choose a value. |

### Secrets

| Secret | Type | Required | Description |
|--------|------|----------|-------------|
| `api_token` | string | Yes | API Token with Account Analytics:Read permission |

### Rate Limits

| Limit | Value | Notes |
|-------|-------|-------|
| Requests per 5 minutes | 300 | GraphQL Analytics API limit |
| Max records per query | Plan-dependent | Discovered automatically via Settings API |

**Source**: [Cloudflare GraphQL Analytics API Limits](https://developers.cloudflare.com/analytics/graphql-api/limits/)

## Troubleshooting

### Common Issues

**Issue**: `GraphQL error` with authentication message
**Cause**: The API token is invalid, expired, or lacks the required permissions.
**Solution**: Verify your API token is correct and has the `Account Analytics:Read` permission. Create a new token if needed.

**Issue**: `Zone ID is required` validation error
**Cause**: The Zone ID field was left empty.
**Solution**: Enter your Cloudflare Zone ID in the settings. You can find this in your Cloudflare dashboard under the zone's overview page.

**Issue**: `invalid settings response` error
**Cause**: The Zone ID is incorrect or the API token doesn't have access to that zone.
**Solution**: Verify the Zone ID is correct and that your API token has permissions for that specific zone.

**Issue**: No data returned despite having firewall events
**Cause**: The lookback duration may exceed your plan's data retention, or there may be no events in the time range.
**Solution**: Check your plan's data retention limits. Free plans only retain 24 hours of data.

**Issue**: `botScore` or `botScoreSrcName` fields missing
**Cause**: Bot Management fields require Enterprise plan with Bot Management add-on.
**Solution**: Disable the `include_bot_fields` setting unless you have Bot Management enabled on your account.

**Issue**: Events appear to be missing during high traffic
**Cause**: Cloudflare applies adaptive sampling to this dataset during high-volume periods.
**Solution**: This is expected behavior. The dataset is designed for monitoring and analysis, not exact event counting.

## Related Articles

- [Cloudflare GraphQL Analytics API](https://developers.cloudflare.com/analytics/graphql-api/)
- [Querying Firewall Events with GraphQL](https://developers.cloudflare.com/analytics/graphql-api/tutorials/querying-firewall-events/)
- [Cloudflare API Tokens](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/)
- [GraphQL Analytics API Limits](https://developers.cloudflare.com/analytics/graphql-api/limits/)
- [Bot Management](https://developers.cloudflare.com/bots/plans/bm-subscription/)

## Sample Record

```json
{
  "action": "block",
  "datetime": "2024-01-15T10:30:45Z",
  "clientIP": "203.0.113.42",
  "clientAsn": "7922",
  "clientASNDescription": "Comcast Cable Communications",
  "clientCountryName": "United States",
  "clientRequestHTTPHost": "api.example.com",
  "clientRequestPath": "/api/v1/users",
  "clientRequestHTTPMethodName": "POST",
  "edgeColoName": "SFO",
  "edgeResponseStatus": 403,
  "ruleId": "waf",
  "rulesetId": "",
  "source": "waf",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  "rayName": "8f7e6d5c4b3a2190",
  "description": ""
}
```