Skip to main content

Command line utility to get information about a website using URLScan.io's APIs.

Project description

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 requires Python >= 3.8. You will also need a URLScan.io account and/or API key.

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 or urlscanio --help for information within your terminal.

API key and download directory

This tool requires an environment variable named URLSCAN_API_KEY containing 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 urlscanio from.

It is recommended to use .bashrc or .zshrc for this. If using PowerShell, add URLSCAN_API_KEY and URLSCAN_DATA_DIR to your user profile.

Proxy settings

urlscanio will use the proxy settings specified by the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables if present.

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:

urlscanio -i https://www.some-dodgy.website
urlscanio --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:

urlscanio -s https://www.some-dodgy.website
urlscanio --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.

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

Verbose mode

urlscanio includes a verbosity flag which takes 3 possible values: 0 (critical), 1 (info), and 2 (debug). This can be used with of the above commands to produce varying amounts of logs to give context to the commands run. If the flag is not passed, the verbosity is set to 0. If the flag is passed without a value, the verbosity level is set to one.

urlscanio -i https://www.some-dodgy.website         # verbosity is 0 (critical)
urlscanio -v -i https://www.some-dodgy.website      # verbosity is 1 (info)
urlscanio -v 0 -i https://www.some-dodgy.website    # verbosity is 0 (critical)
urlscanio -v 1 -i https://www.some-dodgy.website    # verbosity is 1 (info)
urlscanio -v 2 -i https://www.some-dodgy.website    # verbosity is 2 (debug)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

urlscanio-0.1.3.tar.gz (7.3 kB view hashes)

Uploaded Source

Built Distribution

urlscanio-0.1.3-py2.py3-none-any.whl (7.6 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page