Skip to content

Check virustotal-scan-url

Overview

Submits a URL to VirusTotal for analysis and checks the scan results. Alerts when any antivirus engine flags the URL as malicious or suspicious. Useful for periodically scanning critical URLs against 90+ security vendors.

Important Notes:

  • Requires a VirusTotal account and API key
  • Takes at least 60 seconds to execute due to the built-in wait for analysis completion
  • See the VirusTotal documentation on any constraints and restrictions, especially for commercial use (Premium API may be required for business workflows)

Data Collection:

  • Submits the URL to the VirusTotal v3 API (POST /urls)
  • Waits 60 seconds for the analysis to complete
  • Retrieves the full analysis report via the VirusTotal Analysis endpoint (GET /analyses/{id})
  • Reports per-engine results for any detection that is not "harmless" or "undetected"

Fact Sheet

Fact Value
Check Plugin Download https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/virustotal-scan-url
Nagios/Icinga Check Name check_virustotal_scan_url
Check Interval Recommendation Every hour
Can be called without parameters No (--token and --url are required)
Runs on Cross-platform
Compiled for Windows No
Requirements VirusTotal account and API key; Premium API if used in commercial products/services

Help

usage: virustotal-scan-url [-h] [-V] [--always-ok] [--insecure] [--no-proxy]
                           [--severity {warn,crit}] [--test TEST]
                           [--timeout TIMEOUT] --token TOKEN --url URL

Submits a URL to VirusTotal for analysis and checks the scan results. Alerts
when any antivirus engine flags the URL as malicious or suspicious. Requires a
VirusTotal API key.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  --always-ok           Always returns OK.
  --insecure            This option explicitly allows insecure SSL
                        connections.
  --no-proxy            Do not use a proxy.
  --severity {warn,crit}
                        Severity for alerting. Default: warn
  --test TEST           For unit tests. Needs "path-to-stdout-file,path-to-
                        stderr-file,expected-retc".
  --timeout TIMEOUT     Network timeout in seconds. Default: 8 (seconds)
  --token TOKEN         VirusTotal API token.
  --url URL             URL to submit for scanning.

Usage Examples

./virustotal-scan-url --token=b480bd43 --url=https://secure.eicar.org/eicar.com

Output:

9/97 security vendors flagged https://secure.eicar.org/eicar.com as malicious.

Engine      ! Result     ! Method    ! Category           
------------+------------+-----------+--------------------
Antiy-AVL   ! malicious  ! blacklist ! malicious [WARNING]
AutoShun    ! malicious  ! blacklist ! malicious [WARNING]
BitDefender ! malware    ! blacklist ! malicious [WARNING]
CRDF        ! malicious  ! blacklist ! malicious [WARNING]
Fortinet    ! malware    ! blacklist ! malicious [WARNING]
G-Data      ! malware    ! blacklist ! malicious [WARNING]
Lionic      ! malware    ! blacklist ! malicious [WARNING]
Sophos      ! malware    ! blacklist ! malicious [WARNING]
URLQuery    ! suspicious ! blacklist ! suspicious         
VIPRE       ! malware    ! blacklist ! malicious [WARNING]

States

  • OK if no scan engine categorizes the URL as malicious.
  • WARN (or CRIT, depending on --severity) if any scan engine categorizes the URL as "malicious".
  • UNKNOWN if the analysis is still queued or in progress.
  • --always-ok suppresses all alerts and always returns OK.

Perfdata / Metrics

According to https://docs.virustotal.com/reference/analyses-object:

Name Type Description
harmless Number Number of reports saying the URL is harmless.
malicious Number Number of reports saying the URL is malicious.
suspicious Number Number of reports saying the URL is suspicious.
timeout Number Number of timeouts when analysing this URL.
undetected Number Number of reports saying the URL is undetected.
vendors Number Total number of scan vendors used.

Credits, License