Cloudflare URL Scanner POC

URL scanning API using Cloudflare URL Scanner. It allows you to submit URLs to be scanned and retrieve results (verdicts, metadata, contacted domains, etc.).

TL;DR:

The repository is available here. You only need to create a .env file with your Cloudflare API token and account ID.

CLOUDFLARE_API_TOKEN=your_api_token
CLOUDFLARE_ACCOUNT_ID=your_account_id

And then run the following command:

docker compose up --build

Technical details

The repository is built with the following technologies: Node.js + Express.

Folder structure

The repository is organized as follows:

poc-cloudflare-url-scanner/
|-- src/
|   |-- index.js
|   |-- cloudflare.js
|   |-- routes/
|       |-- scan.js
|-- .env.example
|-- .env
|-- package.json
|-- README.md

How to create a Cloudflare API token

You can create a Cloudflare API token in the Cloudflare dashboard. You need to create a token with the following permissions:

• Account > URL Scanner > Edit
• Account > URL Scanner > Read

How to up and running the API

You can up and running the API by cloning this repository and running the following command:

docker compose up --build

How to use the API

You can use the API by sending a POST request to the /scan endpoint with the URL you want to scan.

curl -X POST -H "Content-Type: application/json" -d '{"url":"https://example.com"}' http://localhost:3000/scan

Useful attributes

The response will be a JSON object with the scan result.

{
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  "url": "https://example.com",
  "message": "Submission successful",
  "resultUrl": "https://api.cloudflare.com/.../result/095be615-..."
}

The uuid is the UUID of the scan. You can use it to get the scan result.

curl -s "http://localhost:3000/scan/095be615-a8ad-4c33-8e9c-c7612fbf6c9f" | jq .

Useful attributes of the scan result are:

{
  ...,
  "verdicts": {
    "overall": {
      "malicious": false,
      "hasVerdicts": false,
      "categories": [],
      "tags": []
    }
  },
  ...
}

Now you can know the verdict of the scan.

• malicious: true if the URL is malicious
• hasVerdicts: true if the URL has verdicts
• categories: the categories of the URL
• tags: the tags of the URL