Skip to content

feat(radar): add new Radar and URL Scanner tools #273

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
andre-j3sus merged 4 commits into from
Jan 7, 2026
Merged

feat(radar): add new Radar and URL Scanner tools #273

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
54b22c4
feat(radar): add Cloud Observatory / Origins tools for hyperscaler pe…
TownLake Jan 6, 2026
d0ed573
feat(radar): add new Radar categories + refresh URL Scanner tools
andre-j3sus Jan 6, 2026
11cf027
fix(radar): use snake_case for bots dimension parameters
andre-j3sus Jan 7, 2026
7bc21e5
feat(radar): add new tools for robots.txt, crawlers, bots, AS112, geo…
andre-j3sus Jan 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
147 changes: 121 additions & 26 deletions apps/radar/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,40 +10,135 @@ Internet traffic insights, trends and other utilities.

Currently available tools:

| **Category** | **Tool** | **Description** |
| ---------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **AI** | `get_ai_data` | Retrieves AI-related data, including traffic from AI user agents, as well as popular models and model tasks |
| **Autonomous Systems** | `list_autonomous_systems` | Lists ASes; filter by location and sort by population size |
| | `get_as_details` | Retrieves detailed info for a specific ASN |
| **Domains** | `get_domains_ranking` | Gets top or trending domains |
| | `get_domain_rank_details` | Gets domain rank details |
| **DNS** | `get_dns_data` | Retrieves DNS query data to 1.1.1.1, including timeseries, summaries, and breakdowns by dimensions like `queryType` |
| **Email Routing** | `get_email_routing_data` | Retrieves Email Routing data, including timeseries, and breakdowns by dimensions like `encrypted` |
| **Email Security** | `get_email_security_data` | Retrieves Email Security data, including timeseries, and breakdowns by dimensions like `threatCategory` |
| **HTTP** | `get_http_data` | Retrieves HTTP request data, including timeseries, and breakdowns by dimensions like `deviceType` |
| **IP Addresses** | `get_ip_details` | Provides details about a specific IP address |
| **Internet Services** | `get_internet_services_ranking` | Gets top Internet services |
| **Internet Quality** | `get_internet_quality_data` | Retrieves a summary or time series of bandwidth, latency, or DNS response time from the Radar Internet Quality Index |
| **Internet Speed** | `get_internet_speed_data` | Retrieves summary of bandwidth, latency, jitter, and packet loss, from the previous 90 days of Cloudflare Speed Test |
| **Layer 3 Attacks** | `get_l3_attack_data` | Retrieves L3 attack data, including timeseries, top attacks, and breakdowns by dimensions like `protocol` |
| **Layer 7 Attacks** | `get_l7_attack_data` | Retrieves L7 attack data, including timeseries, top attacks, and breakdowns by dimensions like `mitigationProduct` |
| **Traffic Anomalies** | `get_traffic_anomalies` | Lists traffic anomalies and outages; filter by AS, location, start date, and end date |
| **URL Scanner** | `scan_url` | Scans a URL via [Cloudflare’s URL Scanner](https://developers.cloudflare.com/radar/investigate/url-scanner/) |

This MCP server is still a work in progress, and we plan to add more tools in the future.
| **Category** | **Tool** | **Description** |
| ---------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **AI** | `get_ai_data` | Retrieves AI-related data, including traffic from AI user agents, as well as popular models and model tasks |
| **Annotations & Outages** | `get_annotations` | Retrieves annotations including Internet events, outages, and anomalies from various Cloudflare data sources |
| | `get_outages` | Retrieves Internet outages and anomalies with detected connectivity issues |
| **AS112** | `get_as112_data` | Retrieves AS112 DNS sink hole data for reverse DNS lookups of private IP addresses (RFC 1918) |
| **Autonomous Systems** | `list_autonomous_systems` | Lists ASes; filter by location and sort by population size |
| | `get_as_details` | Retrieves detailed info for a specific ASN |
| | `get_as_set` | Gets IRR AS-SETs that an AS is a member of |
| | `get_as_relationships` | Gets AS-level relationships (peer, upstream, downstream) |
| **BGP** | `get_bgp_hijacks` | Retrieves BGP hijack events with filtering by hijacker/victim ASN, confidence score |
| | `get_bgp_leaks` | Retrieves BGP route leak events |
| | `get_bgp_route_stats` | Retrieves BGP routing table statistics |
| | `get_bgp_timeseries` | Retrieves BGP updates time series (announcements and withdrawals) |
| | `get_bgp_top_ases` | Gets top ASes by BGP update count |
| | `get_bgp_top_prefixes` | Gets top IP prefixes by BGP update count |
| | `get_bgp_moas` | Gets Multi-Origin AS (MOAS) prefixes |
| | `get_bgp_pfx2as` | Gets prefix-to-ASN mapping |
| **Bots** | `get_bots_data` | Retrieves bot traffic data by name, operator, category (AI crawlers, search engines, etc.) |
| | `list_bots` | Lists known bots with details (AI crawlers, search engines, monitoring bots) |
| | `get_bot_details` | Gets detailed information about a specific bot by slug |
| | `get_bots_crawlers_data` | Retrieves web crawler HTTP request data by client type, user agent, referrer, industry |
| **Certificate Transparency** | `get_certificate_transparency_data` | Retrieves CT log data for SSL/TLS certificate issuance trends |
| | `list_ct_authorities` | Lists Certificate Authorities tracked in CT logs |
| | `get_ct_authority_details` | Gets details for a specific CA by fingerprint |
| | `list_ct_logs` | Lists Certificate Transparency logs |
| | `get_ct_log_details` | Gets details for a specific CT log by slug |
| **Cloud Observatory** | `list_origins` | Lists cloud provider origins (AWS, GCP, Azure, OCI) |
| | `get_origin_details` | Gets details for a specific cloud provider |
| | `get_origins_data` | Retrieves cloud provider performance metrics (timeseries, summaries, grouped by region/percentile) |
| **Domains** | `get_domains_ranking` | Gets top or trending domains |
| | `get_domain_rank_details` | Gets domain rank details |
| **DNS** | `get_dns_queries_data` | Retrieves DNS query data to 1.1.1.1, including timeseries, summaries, and breakdowns by dimensions like `queryType` |
| **Email Routing** | `get_email_routing_data` | Retrieves Email Routing data, including timeseries, and breakdowns by dimensions like `encrypted` |
| **Email Security** | `get_email_security_data` | Retrieves Email Security data, including timeseries, and breakdowns by dimensions like `threatCategory` |
| **Geolocations** | `list_geolocations` | Lists available geolocations (ADM1 - states/provinces) with GeoNames IDs |
| | `get_geolocation_details` | Gets details for a specific geolocation by GeoNames ID |
| **HTTP** | `get_http_data` | Retrieves HTTP request data with geoId filtering for ADM1 (states/provinces) |
| **IP Addresses** | `get_ip_details` | Provides details about a specific IP address |
| **Internet Services** | `get_internet_services_ranking` | Gets top Internet services |
| **Internet Quality** | `get_internet_quality_data` | Retrieves a summary or time series of bandwidth, latency, or DNS response time from the Radar Internet Quality Index |
| **Internet Speed** | `get_internet_speed_data` | Retrieves summary of bandwidth, latency, jitter, and packet loss, from the previous 90 days of Cloudflare Speed Test |
| **Layer 3 Attacks** | `get_l3_attack_data` | Retrieves L3 attack data, including timeseries, top attacks, and breakdowns by dimensions like `protocol` |
| **Layer 7 Attacks** | `get_l7_attack_data` | Retrieves L7 attack data, including timeseries, top attacks, and breakdowns by dimensions like `mitigationProduct` |
| **Leaked Credentials** | `get_leaked_credentials_data` | Retrieves trends in HTTP auth requests and compromised credential detection |
| **NetFlows** | `get_netflows_data` | Retrieves network traffic patterns with geoId filtering for ADM1 (states/provinces) |
| **Robots.txt** | `get_robots_txt_data` | Retrieves robots.txt analysis data showing crawler access rules across domains |
| **TCP Quality** | `get_tcp_resets_timeouts_data` | Retrieves TCP connection quality metrics (resets and timeouts) |
| **Traffic Anomalies** | `get_traffic_anomalies` | Lists traffic anomalies and outages; filter by AS, location, start date, and end date |
| **URL Scanner** | `search_url_scans` | Search URL scans using ElasticSearch-like query syntax |
| | `create_url_scan` | Submit a URL to scan, returns scan UUID |
| | `get_url_scan` | Get scan results by UUID (verdicts, page info, stats) |
| | `get_url_scan_screenshot` | Get screenshot URL for a completed scan |
| | `get_url_scan_har` | Get HAR (HTTP Archive) data for a completed scan |

### Prompt Examples

**Traffic & Network Analysis**

- `What are the most used operating systems?`
- `Show me HTTP traffic trends from Lisbon, Portugal (use geoId).`
- `What is the TCP reset and timeout rate globally?`
- `Show me network traffic patterns for California.`

**Autonomous Systems & BGP**

- `What are the top 5 ASes in Portugal?`
- `Get information about ASN 13335.`
- `What are the details of IP address 1.1.1.1?`
- `List me traffic anomalies in Syria over the last year.`
- `What are the relationships (peers, upstreams) for Cloudflare's AS?`
- `Show me recent BGP hijack events.`
- `Which prefixes have the most BGP updates?`
- `What AS announces the prefix 1.1.1.0/24?`

**Security & Attacks**

- `Show me application layer attack trends from the last 7 days.`
- `What are the top L3 attack vectors?`
- `Show me leaked credential detection trends.`
- `Scan https://example.com for security analysis.`

**Bots & Crawlers**

- `What AI crawlers are most active?`
- `List all known AI crawler bots.`
- `How are websites configuring robots.txt for AI crawlers?`
- `What percentage of sites block vs allow AI crawlers?`
- `Show me crawler traffic by industry vertical.`

**DNS & Email**

- `What are the most common DNS query types to 1.1.1.1?`
- `Show me AS112 DNS sink hole data by protocol.`
- `What are the email security threat trends?`

**Certificates & TLS**

- `What are the most active Certificate Authorities?`
- `List Certificate Transparency logs.`
- `Show me certificate issuance trends by validation level.`

**Rankings & Services**

- `What are the top trending domains?`
- `Compare domain rankings in the US and UK.`
- `Give me rank details for google.com in March 2025.`
- `Scan https://example.com.`
- `Show me HTTP traffic trends from Portugal.`
- `Show me application layer attack trends from the last 7 days.`
- `What are the top Internet services in the E-commerce category?`

**Outages & Events**

- `List me traffic anomalies in Syria over the last year.`
- `Show me recent Internet outages.`
- `What outages affected Portugal in the last 30 days?`

**Cloud & Infrastructure**

- `What are the top 5 AWS regions in terms of traffic?`
- `Compare latency between Azure and GCP regions.`
- `What is the connection success rate for cloud providers?`

**Geolocations**

- `List available geolocations for Portugal.`
- `What is the GeoNames ID for Lisbon?`
- `Show me HTTP traffic specifically for the Lisbon area.`

**IP Information**

- `What are the details of IP address 1.1.1.1?`
- `What ASN owns this IP address?`

## Access the remote MCP server from any MCP Client

Expand Down
50 changes: 37 additions & 13 deletions apps/radar/src/radar.context.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,24 +19,48 @@ export interface Env {
export const BASE_INSTRUCTIONS = /* markdown */ `
# Cloudflare Radar MCP Server

This server integrates tools powered by the Cloudflare Radar API to provide insights into global Internet traffic,
trends, and other related utilities.
This server provides tools powered by the Cloudflare Radar API for global Internet insights.

An active account is **only required** for URL Scanner-related tools (e.g., \`scan_url\`).
## Authentication

For tools related to Internet trends and insights, analyze the results and, when appropriate, generate visualizations
such as line charts, pie charts, bar charts, stacked area charts, choropleth maps, treemaps, or other relevant chart types.
- **URL Scanner** requires an active account (use \`set_active_account\`)
- All other Radar data tools work without account selection

### Making comparisons
## Tool Categories

Many tools support **array-based filters** to enable comparisons across multiple criteria.
In such cases, the array index corresponds to a distinct data series.
For each data series, provide a corresponding \`dateRange\`, or alternatively a \`dateStart\` and \`dateEnd\` pair.
Example: To compare HTTP traffic between Portugal and Spain over the last 7 days:
- **Entities**: Look up ASN, IP, and location details (\`list_autonomous_systems\`, \`get_as_details\`, \`get_ip_details\`)
- **Traffic**: HTTP and DNS trends (\`get_http_data\`, \`get_dns_queries_data\`)
- **Attacks**: Layer 3/7 DDoS attack trends (\`get_l3_attack_data\`, \`get_l7_attack_data\`)
- **Email**: Routing and security trends (\`get_email_routing_data\`, \`get_email_security_data\`)
- **Quality**: Internet speed and quality metrics (\`get_internet_quality_data\`, \`get_internet_speed_data\`)
- **Rankings**: Top domains and services (\`get_domains_ranking\`, \`get_internet_services_ranking\`)
- **AI**: AI bot traffic and Workers AI usage (\`get_ai_data\`)
- **BGP**: Route hijacks, leaks, and stats (\`get_bgp_hijacks\`, \`get_bgp_leaks\`, \`get_bgp_route_stats\`)
- **Bots**: Bot traffic by category, operator, kind (\`get_bots_data\`)
- **Certificate Transparency**: SSL/TLS certificate issuance trends (\`get_certificate_transparency_data\`)
- **NetFlows**: Network traffic patterns with ADM1 filtering (\`get_netflows_data\`)
- **Cloud Observatory**: Cloud provider performance - AWS, GCP, Azure, OCI (\`list_origins\`, \`get_origin_details\`, \`get_origins_data\`)
- **URL Scanner**: Scan and analyze URLs for security threats (\`search_url_scans\`, \`create_url_scan\`, \`get_url_scan\`, \`get_url_scan_screenshot\`, \`get_url_scan_har\`)

## Making Comparisons

Many tools support **array-based filters** for comparisons. Each array index corresponds to a distinct data series.
Example: Compare HTTP traffic between Portugal and Spain over the last 7 days:
- \`dateRange: ["7d", "7d"]\`
- \`location: ["PT", "ES"]\`

This applies to date filters and other filters that support comparison across multiple values.
If a tool does **not** support array-based filters, you can achieve the same comparison by making multiple separate
calls to the tool.
## Geographic Filtering

- **location**: Filter by country (alpha-2 codes like "US", "PT")
- **continent**: Filter by continent (alpha-2 codes like "EU", "NA")
- **geoId**: Filter by ADM1 region (GeoNames IDs for states/provinces) - available for HTTP and NetFlows

## Visualizations

Generate charts when appropriate:
- **Line charts**: Timeseries data
- **Bar charts**: Rankings, summaries
- **Pie charts**: Distributions
- **Choropleth maps**: Geographic data
- **Stacked area charts**: Grouped timeseries
`
Loading