Skip to main content

urlscanio

Summary

URLScan.io is a useful tool for scanning and obtaining information from potentially malicious websites. The creators of URLScan have very helpfully made an API which can be used to add some automation to your workflow. urlscanio is a simple Python CLI utility which makes use of the aforementioned APIs to automate my own personal workflow when it comes to using URLScan.

Requirements

urlscanio was written in Python 3.7 and currently requires the user to have Python >= 3.5, mostly due to the fact that it makes use of the typing module.

Installation

If you have a compatible Python version installed, simply run (using pip3 if necessary):

pip install urlscanio

How to use

In this section, the different functions of the CLI are outlined. You may also use urlscanio -h|--help for information within your terminal.

API key and download directory

This tool requires an environment variable named URLSCAN_API_KEY to be set to your API key. Optionally, you may also set an environment variable called URLSCAN_DATA_DIR to specify where the screenshots and DOM should be downloaded. If not set, they will be downloaded in the directory you run the script from.

It is recommended to use the .bashrc or .zshrc file for this. If using PowerShell, add the environment variables to your user profile.

Investigate URL

Provided a URL (containing the protocol and domain at minimum), will request a scan and download the corresponding screenshot and DOM, as well as the report URL.

Examples:

urlscan -i https://www.amazon.co.uk
urlscan --investigate http://some-dodgy.website

Submit scan request

Provided a URL (containing the protocol and domain at minimum), will request a scan and return the UUID generated. This can then be used to determine eg the screenshot location.

Examples:

urlscan -s https://www.amazon.co.uk
urlscan --submit http://some-dodgy.website

Retrieve scan information

Provided the UUID linked to the scan in question, will query the API to download the screenshot and DOM from the report, as well as return the report URL.

urlscan -r c5be1459-0a64-4751-bf25-8dd6d3c5742d
urlscan --retrieve c5be1459-0a64-4751-bf25-8dd6d3c5742d

Metadata

Release files for urlscanio 0.0.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for urlscanio 0.0.4
File Size Uploaded Provenance Actions
urlscanio-0.0.4.tar.gz 2.8 kB Without provenance Details for urlscanio-0.0.4.tar.gz

Release files / urlscanio-0.0.4.tar.gz

Download URL urlscanio-0.0.4.tar.gz
Size 2.8 kB
Tags Source
SHA-256 checksum
How to use checksums
f5a8fed44a049b9759249aa6b291a0e3765bace2faf3894f55d8324e1c6c015d
BLAKE2b-256 checksum
How to use checksums
83686f051c754fcc0e4e33b2cdf1b980478584f9f42d21010f28d0916d26572f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.13.0 pkginfo/1.5.0.1 requests/2.21.0 setuptools/40.6.2 requests-toolbelt/0.9.1 tqdm/4.31.1 CPython/3.7.2

Security for urlscanio 0.0.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page