Package: urlscanio
urlscanioSummaryURLScan.iois a useful tool for scanning and obtaining information from potentially malicious websites. The creators of URLScan have very helpfully made anAPIwhich can be used to add some automation to your workflow.urlscaniois a simple Python CLI utility which makes use of the aforementioned APIs to automate my own personal workflow when it comes to using URLScan.Requirementsurlscaniorequires Python >= 3.8. You will also need aURLScan.ioaccount and/or API key.InstallationIf you have a compatible Python version installed, simply run (usingpip3if necessary):pipinstallurlscanioHow to useIn this section, the different functions of the CLI are outlined. You may also useurlscanio -horurlscanio --helpfor information within your terminal.API key and download directoryThis tool requires an environment variable namedURLSCAN_API_KEYcontaining your API key. Optionally, you may also set an environment variable calledURLSCAN_DATA_DIRto specify where the screenshots and DOM should be downloaded. If not set, they will be downloaded in the directory you runurlscaniofrom.It is recommended to use.bashrcor.zshrcfor this. If using PowerShell, addURLSCAN_API_KEYandURLSCAN_DATA_DIRto your user profile.Proxy settingsurlscaniowill use the proxy settings specified by theHTTP_PROXY,HTTPS_PROXY, andNO_PROXYenvironment variables if present.Investigate URLProvided 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.urlscanio-ihttps://www.some-dodgy.website
urlscanio--investigatehttp://some-dodgy.websiteSubmit scan requestProvided 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.urlscanio-shttps://www.some-dodgy.website
urlscanio--submithttp://some-dodgy.websiteRetrieve scan informationProvided 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-rc5be1459-0a64-4751-bf25-8dd6d3c5742d
urlscanio--retrievec5be1459-0a64-4751-bf25-8dd6d3c5742dBatch InvestigationsIf you have >1 URL you'd like to investigate, use the-b/--batch-investigateflag. You will need a file containing a URL per line, eg:https://www.example1.com
https://www.example2.com
https://www.example3.comThe filename containing the URLs can then be passed, triggering an "investigation" for each URL. It will trigger each investigation in 3 second intervals by default, as UrlScan.io requires a minimum of 2 seconds between scan requests.urlscaniowill produce an output CSV containing the results. The output CSV will be named[input_stem].csv; for example, passing intest.txtwill producetest.csv.urlscanio-btest.txt
urlscanio--batch-investigatetest.txtSearchPerform asearch query. Results are returned as JSON.urlscanio-q'domain:urlscan.io'Get Scan ResultsYou can get the scan result data for a given scan UUID.urlscanio-g0e38487e-6514-431d-a305-f2de2f6db348Verbose modeurlscanioincludes 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-ihttps://www.some-dodgy.website# verbosity is 0 (critical)urlscanio-v-ihttps://www.some-dodgy.website# verbosity is 1 (info)urlscanio-v0-ihttps://www.some-dodgy.website# verbosity is 0 (critical)urlscanio-v1-ihttps://www.some-dodgy.website# verbosity is 1 (info)urlscanio-v2-ihttps://www.some-dodgy.website# verbosity is 2 (debug)