scan

Creates, updates, deletes, gets or lists a scan resource.

Overview

Name	scan
Type	Resource
Id	cloudflare.url_scanner.scan

Fields

The following fields are returned by SELECT queries:

get

Scan has finished. It may or may not have been successful.

Name	Datatype	Description
scan	object

list

Search results

Name	Datatype	Description
country	string	Alpha-2 country code
success	boolean	Whether scan was successful or not
time	string (date-time)	When scan was submitted (UTC)
url	string	Scan url (after redirects)
uuid	string (uuid)	Scan id
visibility	string	Submitted visibility status. (public, unlisted)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	scan_id, account_id	full	Get URL scan by uuid
list	select	account_id	scan_id, limit, next_cursor, date_start, date_end, url, hostname, path, ip, hash, page_url, page_hostname, page_path, page_asn, page_ip, account_scans, is_malicious	Search scans by date and webpages' requests, including full URL (after redirects), hostname, and path. A successful scan will appear in search results a few minutes after finishing but may take much longer if the system in under load. By default, only successfully completed scans will appear in search results, unless searching by scanId. Please take into account that older scans may be removed from the search index at an unspecified time.
urlscanner_create_scan	insert	account_id, url		Submit a URL to scan. You can also set some options, like the visibility level and custom headers. Check limits at https://developers.cloudflare.com/security-center/investigate/scan-limits/.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
account_id	string	The Cloudflare account ID.
scan_id	string (uuid)	Scan UUID.
account_scans	boolean	Return only scans created by account.
date_end	string (date-time)	Filter scans requested before date (inclusive).
date_start	string (date-time)	Filter scans requested after date (inclusive).
full	boolean	Whether to return full report (scan summary and network log).
hash	string	Filter scans by hash of any html/js/css request made by the webpage.
hostname	string	Filter scans by hostname of any request made by the webpage.
ip	string	Filter scans by IP address (IPv4 or IPv6) of any request made by the webpage.
is_malicious	boolean	Filter scans by malicious verdict.
limit	integer	Limit the number of objects in the response.
next_cursor	string	Pagination cursor to get the next set of results.
page_asn	string	Filter scans by main page Autonomous System Number (ASN).
page_hostname	string	Filter scans by main page hostname (domain of effective URL).
page_ip	string	Filter scans by main page IP address (IPv4 or IPv6).
page_path	string	Filter scans by exact match of effective URL path (also supports suffix search).
page_url	string	Filter scans by submitted or scanned URL
path	string	Filter scans by url path of any request made by the webpage.
scan_id	string (uuid)	Scan UUID.
url	string	Filter scans by URL of any request made by the webpage

SELECT examples

get

Get URL scan by uuid

SELECT
scan
FROM cloudflare.url_scanner.scan
WHERE scan_id = '{{ scan_id }}' -- required
AND account_id = '{{ account_id }}' -- required
AND full = '{{ full }}'
;

list

Search scans by date and webpages' requests, including full URL (after redirects), hostname, and path.
A successful scan will appear in search results a few minutes after finishing but may take much longer if the system in under load. By default, only successfully completed scans will appear in search results, unless searching by scanId. Please take into account that older scans may be removed from the search index at an unspecified time.

SELECT
country,
success,
time,
url,
uuid,
visibility
FROM cloudflare.url_scanner.scan
WHERE account_id = '{{ account_id }}' -- required
AND scan_id = '{{ scan_id }}'
AND limit = '{{ limit }}'
AND next_cursor = '{{ next_cursor }}'
AND date_start = '{{ date_start }}'
AND date_end = '{{ date_end }}'
AND url = '{{ url }}'
AND hostname = '{{ hostname }}'
AND path = '{{ path }}'
AND ip = '{{ ip }}'
AND hash = '{{ hash }}'
AND page_url = '{{ page_url }}'
AND page_hostname = '{{ page_hostname }}'
AND page_path = '{{ page_path }}'
AND page_asn = '{{ page_asn }}'
AND page_ip = '{{ page_ip }}'
AND account_scans = '{{ account_scans }}'
AND is_malicious = '{{ is_malicious }}'
;

INSERT examples

urlscanner_create_scan

Submit a URL to scan. You can also set some options, like the visibility level and custom headers. Check limits at https://developers.cloudflare.com/security-center/investigate/scan-limits/.

INSERT INTO cloudflare.url_scanner.scan (
country,
customHeaders,
screenshotsResolutions,
url,
visibility,
account_id
)
SELECT 
'{{ country }}',
'{{ customHeaders }}',
'{{ screenshotsResolutions }}',
'{{ url }}' /* required */,
'{{ visibility }}',
'{{ account_id }}'
RETURNING
errors,
messages,
result,
success
;

Manifest

# Description fields are for documentation purposes
- name: scan
props:
  - name: account_id
    value: "{{ account_id }}"
    description: Required parameter for the scan resource.
  - name: country
    value: "{{ country }}"
    description: |
      Country to geo egress from
    valid_values: ['AF', 'AL', 'DZ', 'AD', 'AO', 'AG', 'AR', 'AM', 'AU', 'AT', 'AZ', 'BH', 'BD', 'BB', 'BY', 'BE', 'BZ', 'BJ', 'BM', 'BT', 'BO', 'BA', 'BW', 'BR', 'BN', 'BG', 'BF', 'BI', 'KH', 'CM', 'CA', 'CV', 'KY', 'CF', 'TD', 'CL', 'CN', 'CO', 'KM', 'CG', 'CR', 'CI', 'HR', 'CU', 'CY', 'CZ', 'CD', 'DK', 'DJ', 'DM', 'DO', 'EC', 'EG', 'SV', 'GQ', 'ER', 'EE', 'SZ', 'ET', 'FJ', 'FI', 'FR', 'GA', 'GE', 'DE', 'GH', 'GR', 'GL', 'GD', 'GT', 'GN', 'GW', 'GY', 'HT', 'HN', 'HU', 'IS', 'IN', 'ID', 'IR', 'IQ', 'IE', 'IL', 'IT', 'JM', 'JP', 'JO', 'KZ', 'KE', 'KI', 'KW', 'KG', 'LA', 'LV', 'LB', 'LS', 'LR', 'LY', 'LI', 'LT', 'LU', 'MO', 'MG', 'MW', 'MY', 'MV', 'ML', 'MR', 'MU', 'MX', 'FM', 'MD', 'MC', 'MN', 'MS', 'MA', 'MZ', 'MM', 'NA', 'NR', 'NP', 'NL', 'NZ', 'NI', 'NE', 'NG', 'KP', 'MK', 'NO', 'OM', 'PK', 'PS', 'PA', 'PG', 'PY', 'PE', 'PH', 'PL', 'PT', 'QA', 'RO', 'RU', 'RW', 'SH', 'KN', 'LC', 'VC', 'WS', 'SM', 'ST', 'SA', 'SN', 'RS', 'SC', 'SL', 'SK', 'SI', 'SB', 'SO', 'ZA', 'KR', 'SS', 'ES', 'LK', 'SD', 'SR', 'SE', 'CH', 'SY', 'TW', 'TJ', 'TZ', 'TH', 'BS', 'GM', 'TL', 'TG', 'TO', 'TT', 'TN', 'TR', 'TM', 'UG', 'UA', 'AE', 'GB', 'US', 'UY', 'UZ', 'VU', 'VE', 'VN', 'YE', 'ZM', 'ZW']
  - name: customHeaders
    value: "{{ customHeaders }}"
    description: |
      Set custom headers.
  - name: screenshotsResolutions
    value:
      - "{{ screenshotsResolutions }}"
    description: |
      Take multiple screenshots targeting different device types.
    default: desktop
  - name: url
    value: "{{ url }}"
  - name: visibility
    value: "{{ visibility }}"
    description: |
      The option `Public` means it will be included in listings like recent scans and search results. `Unlisted` means it will not be included in the aforementioned listings, users will need to have the scan's ID to access it. A a scan will be automatically marked as unlisted if it fails, if it contains potential PII or other sensitive material.
    valid_values: ['Public', 'Unlisted']
    default: Public