# Cloudflare URL Scanner

Ingests Cloudflare URL Scanner scan results for security monitoring. This input collects security scan data from URLs submitted to Cloudflare's URL Scanner, providing insights into page safety, SSL status, and security threats detected during scanning.

**Sync Type: Incremental**

## Requirements

- A Cloudflare account with access to the URL Scanner API
- An API Token with the `Account` > `URL Scanner` > `Edit` permission
- Your Cloudflare Account ID

### 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 URL Scanner")
   - **Permissions**: Add `Account` > `URL Scanner` > `Edit`
   - **Account Resources**: Select the specific account(s) or "All accounts"
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 Account ID

1. Log in to your Cloudflare dashboard
2. Select the account you want to monitor
3. The Account ID is displayed in the right sidebar on the overview page
4. Alternatively, find it in the URL: `https://dash.cloudflare.com/{account_id}/...`

## Details

- **State Management**: Uses ascending cursor-based pagination with timestamp tracking. Monad stores the last processed timestamp to fetch only new scans on subsequent runs.
- **API Endpoint**: `GET /accounts/{account_id}/urlscanner/v2/search`
- **Query Syntax**: Uses Elasticsearch query syntax for filtering scan results. Supports filters like `date:[start TO end]` and `apikey:me`.
- **Date Range Limitation**: The API enforces a maximum date range of 1 month per query. The input automatically chunks requests into 30-day intervals for incremental syncing.
- **Rate Limits**: 4 requests per second (1,200 requests per 5 minutes). The input automatically enforces this limit.

## Configuration

### Settings

| Setting | Type | Required | Description |
|---------|------|----------|-------------|
| `account_id` | string | Yes | Cloudflare Account ID |
| `filter_my_scans` | boolean | No | Filter to only show scans created by the current API token |
| `backfill_start_time` | string | No | The date to start fetching data from. If not specified, no past records will be fetched. |
| 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 URL Scanner Edit permission |

### Rate Limits

| Limit | Value | Notes |
|-------|-------|-------|
| Requests per second | 4 | 1,200 requests per 5 minutes |
| Max date range | 30 days | Query window must not exceed 1 month |
| Records per page | 100 | Maximum records returned per API request |

**Headers**: `Authorization: Bearer {api_token}`, `Content-Type: application/json`
**Source**: [Cloudflare URL Scanner API Documentation](https://developers.cloudflare.com/api/resources/url_scanner/)

## Troubleshooting

### Common Issues

**Issue**: `API Token is required` validation error
**Cause**: The API token field was left empty.
**Solution**: Enter your Cloudflare API token in the secrets configuration. The token must have the `URL Scanner Edit` permission.

**Issue**: `Account ID is required` validation error
**Cause**: The Account ID field was left empty.
**Solution**: Enter your Cloudflare Account ID in the settings. You can find this in your Cloudflare dashboard.

**Issue**: `API error` with authentication failure
**Cause**: The API token is invalid, expired, or lacks the required `URL Scanner Edit` permission.
**Solution**: Verify your API token is correct and has the necessary permissions. Create a new token if needed.

**Issue**: No scan results returned
**Cause**: The backfill start time may be set to a future date, or no scans exist in the specified time range.
**Solution**: Verify the backfill start time is set correctly or leave it empty to fetch available scans.

**Issue**: `Date range exceeded` error
**Cause**: The internal query window exceeds the 1-month API limit.
**Solution**: This is handled automatically by the input. If you see this error, try setting a more recent backfill start time.

**Issue**: Rate limit errors
**Cause**: Multiple integrations or manual API calls are consuming the rate limit quota.
**Solution**: The input automatically handles rate limiting at 4 requests per second. If you see persistent errors, reduce the frequency of other API calls to your Cloudflare account.

## Related Articles

- [Cloudflare URL Scanner API Documentation](https://developers.cloudflare.com/api/resources/url_scanner/)
- [Cloudflare URL Scanner Limits](https://developers.cloudflare.com/security-center/investigate/scan-limits/)
- [Cloudflare API Tokens](https://developers.cloudflare.com/fundamentals/api/get-started/create-token/)
- [Cloudflare API Rate Limits](https://developers.cloudflare.com/fundamentals/api/reference/limits/)

## Sample Record

```json
{
  "_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "task": {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "visibility": "public",
    "time": "2024-01-15T10:30:00Z",
    "url": "https://example.com/",
    "success": true
  },
  "page": {
    "url": "https://example.com/",
    "country": "US",
    "asn": "AS15169",
    "ip": "93.184.216.34"
  },
  "stats": {
    "uniqIPs": 5,
    "uniqCountries": 2,
    "requests": 47,
    "dataLength": 2048576
  },
  "verdicts": {
    "malicious": false
  },
  "result": "https://radar.cloudflare.com/scan/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```