VirusTotal Command

Buttons/Scripts
,
1

VT is a script add-in command for Directory Opus, that allows users to scan files using the VirusTotal API.

Key Features:

  • Automated process, including file upload if they do not exist in the database.
  • Comprehensive report presented in an easy-to-use and understand interface.
  • Ability to write reports to disk/clipboard as plain text or JSON formatted.

:warning: IMPORTANT: READ BEFORE PROCEED

This script is provided "as is" and without warranty of any kind or whatsoever.
It has been made during my spare time and has not been extensively tested, so it is presented as a testing version.
The user assumes full responsibility for its use and understands that the author is not responsible for possible failures or loss of data.
Kind remind that this is a work in progress, so expect bugs.
Any feedback on possible improvements or bugs is welcome.
The program acts solely as an interface for the VirusTotal API. It does not provide one, and how you use it is entirely your responsibility.

2025-04-12 09-53-39 Clipboard Image
2025-04-12 09-53-39 Clipboard Image699×912 55.1 KB

Before use

Obviously, first you're going to need an API key.

How to Install

:warning: IMPORTANT: Needs at least DOpus v13.14
Download the file below. Then go to Settings / Scripts (or run Prefs SCRIPTINSTALL) and select the downloaded file.

v1.5.0 : VTCommand.opusscriptinstall

Options

In the Script Management window, select VT and click in the Edit button.

  • log level : Logging level to be displayed.
    • OFF to show only errors.
    • DEBUG to show all messages.
    • STANDARD to show only the most relevant information.
    • WARNING to show messages that needs your attention.
  • max timeout : Maximum time in seconds to wait for a connection.
  • force file report after analysis : Set to True to retrieve a full file object after you get an analysis report. This will result in a extra request per file.
  • max threads : Maximum number of files to process simultaneously when using the NOGUI argument.
  • allow multiple instances : Allow run multiples instances (when NOGUI is not used).

Usage

The first time you attempt to use the command, if no API key is saved, you will be prompted to enter one. You can also set it using 'VT SETKEY'.

To scan a file, you can use: VT FILE={filepath$}.

To scan multiple files, you need to use the NOGUI argument. E.g. VT FILE={allfilepath$} NOGUI=notify,json.

When no file is specified, it will the first file loaded into the command (usually selected files from the source filedisplay).

VT supports the following arguments:

Command Arguments

ARGUMENT TYPE VALUE DESCRIPTION
FILE /M Full path of the file (or files) to scan. Note that multiple files are allowed only when used in conjunction with the NOGUI argument.
If not provided, the command will use the files passed to it (which usually are the selected files in the source file display).
AUTOUPLOAD /S If the file is not found in the VirusTotal database, the command will ask whether you want to upload the file for analysis. Use this argument to bypass the prompt and upload automatically if necessary.
URLTOCLIP /S Copy the VT URL of the scanned file to the clipboard. Note that this argument is ignored when used with NOGUI.
NOGUI /O Use the command without showing the main dialog. In this mode, multiple files can be processed simultaneously. A summary report will be saved in the same directory as each scanned file.
clip Copy the reports to the clipboard instead of saving them to separate files.
json Save the reports to disk using a JSON schema (the raw response obtained from VT).
jsonclip Copy the reports to the clipboard in JSON format instead of saving them to separate files.
notify Force the notify window dialog to display after the analysis—this dialog will include all files instead of just the flagged ones. (detailed explained in Notes)
SETKEY /S Open the dialog for set your API key
DELKEY /O Prompt for deleting current saved API key.
quiet Use it to quietly delete it.

You can also drop files onto the main window to start a new scan.

Notes / Technical Stuff

  • If a file is not found in the database, you will be asked if you want to upload it for analysis. If you choose to proceed, the command will handle the upload. Note that the analysis remains queued for a while. You can either wait with the command window open (which will try to fetch the report periodically) or open the provided link in your browser (doing so usually skips the waiting period), after which the command will finish. In NOGUI mode, if AUTOUPLOAD is also used, the command upload the file if needed and then provide the result url, before finish.
  • Typically, the free API version allows 4 requests per minute. This is especially important if you plan to use multiple threads with the NOGUI argument. For detailed information, please visit VirusTotal API Documentation.
  • The command uses one request per file, even when this implies uploading the file (this does not consume API requests) and waiting for a response.
  • When you upload a file, you receive a slightly less detailed response. To obtain the full report, force file report after analysis must be enabled, which will consume 2 credits per file if applicable.
  • Due to free API limitations, only files of 650MB or smaller can be uploaded.
  • In NOGUI mode, if a file is flagged (recognized as possibly malicious, suspicious, not founded in database or with an error), a dialog window will open containing all the flagged files along with a summary of the results, serving as an alert for possible threats.
    • If the NOGUI argument includes the notify value, this dialog will be shown regardless of the results (even if no files are flagged).

Acknowledgments

VirusTotal

OpusDevelopers for including so many of my requests, like the HTTPRequest one, which makes this command possible.

Changelog

v1.5.0 (Apr 25, 2025): VTCommand.opusscriptinstall (17.8 KB)

  • You can now use AUTOUPLOAD with NOGUI, which auto-uploads if needed. Note that the command ends after uploading and getting the result URL, and won’t wait for the full analysis like the dialog does.
  • You can now drop files onto the main window to start a new scan.
  • You can run multiple instances of the main window. Just set Allow multiple instances to True in the script settings.
  • The vendor results list now uses colors for better identification.
  • Added more scenarios for how the summary dialog displays when scanning multiple files.
  • Improved the TXT summary format for certain scenarios.
  • Other minor fixes.
Full changelog

v1.1.0 (Apr 14, 2025):

  • Now, if no FILE argument is provided, the script will use the files passed to it (usually the ones selected in the source file display, which is especially useful when piping with other commands).
  • Added a new window in NOGUI mode that serves as a notification when potential threats or errors are detected in the scanned files (detailed in the Notes section).
  • NOGUI now supports notify to force this notification to display upon command completion, regardless of the results.
  • Fixed an error related to the total count for vendors when processing multiple files.

v1.0.0 (Apr 12, 2025):

  • Added NOGUI argument: This allows you to run the command without displaying the main dialog and enables simultaneous multiple requests (see the main post for details).
  • Added URLTOCLIP argument: Copies the report URL to the clipboard.
  • Added AUTOUPLOAD argument: Uploads the file for analysis without prompting first.
  • Multiple files support (with NOGUI).
    Note: If you're updating from a previous version, modify your command to include the FILE argument (e.g., VT FILE={filepath$} or VT FILE={allfilepath$} NOGUI).
  • Substantial improvements in response speed, both for obtaining the report and overall usage.
  • After an upload, the command can now wait for the response and display it automatically.
  • Improved handling of request limits for the free API.
  • Dates now display in local format instead of UTM.
  • Cosmetic enhancements.
  • Other minor improvements/corrections.

v0.9.1a (Dec 25, 2024):

  • Fixed timestamps not converting to dates correctly
  • REPORT argument is removed; there's now a Save Report button in the dialog instead.
  • Added support for creating reports as JSON (the raw response) and plain text, both with options to save to a file and clipboard.
  • Removed reanalysis feature due to a potential "denial of service" risk.
  • Other small corrections.

v0.9a (Dec 22, 2024) : Initial release

11 Likes
2

v0.9.1a :

  • Fixed timestamps not converting to dates correctly
  • REPORT argument is removed; there's now a Save Report button in the dialog instead.
  • Added support for creating reports as JSON (the raw response) and plain text, both with options to save to a file and clipboard.
  • Removed reanalysis feature due to a potential "denial of service" risk.
  • Other small corrections.
1 Like
3

I've installed your script and assigned VT {filepath$} to a command. Could you explain why any file I scan gives me "Error 3: Unable to resolve host name" error?

1 Like
4

Maybe it's because you're using a firewall or similar tool that's preventing Opus from accessing the internet?

5

I've updated the script for faster responses. Plus there's a way to do parallel requests and a NOGUI mode. If anyone wants to help test it, just DM me.

1 Like
6

v1.0.0 (Apr 12, 2025):

  • Added NOGUI argument: This allows you to run the command without displaying the main dialog and enables simultaneous multiple requests (see the main post for details).
  • Added URLTOCLIP argument: Copies the report URL to the clipboard.
  • Added AUTOUPLOAD argument: Uploads the file for analysis without prompting first.
  • Multiple files support (with NOGUI).
    Note: If you're updating from a previous version, modify your command to include the FILE argument (e.g., VT FILE={filepath$} or VT FILE={allfilepath$} NOGUI).
  • Substantial improvements in response speed, both for obtaining the report and overall usage.
  • After an upload, the command can now wait for the response and display it automatically.
  • Improved handling of request limits for the free API.
  • Dates now display in local format instead of UTM.
  • Cosmetic enhancements.
  • Other minor improvements/corrections.

NOTE: The command uses a workaround to include its own icon so that DOpus doesn't treat it as a new script (which would force users who have already entered their API key to do it again). So, in theory, users updating to this new version won't need to re-enter their key—the key is automatically converted to the new format.
However, you'll have to modify your command instruction to include the FILE argument (sorry about that). Previously it was implicit.

2 Likes
7

v1.1.0 (Apr 14, 2025):

  • Now, if no FILE argument is provided, the script will use the files passed to it (usually the ones selected in the source file display, which is especially useful when piping with other commands).
  • Added a new window in NOGUI mode that serves as a notification when potential threats or errors are detected in the scanned files (detailed in the Notes section).
  • NOGUI now supports notify to force this notification to display upon command completion, regardless of the results.
  • Fixed an error related to the total count for vendors when processing multiple files.
1 Like
8

Great Tool!

9

v1.5.0 (Apr 25, 2025):

  • You can now use AUTOUPLOAD with NOGUI, which auto-uploads if needed. Note that the command ends after uploading and getting the result URL, and won’t wait for the full analysis like the dialog does.
  • Added 'Reputation' and 'Signed' values to results summary, when exists.
  • You can now drop files onto the main window to start a new scan.
  • You can run multiple instances of the main window. Just set Allow multiple instances to True in the script settings.
  • The vendor results list now uses colors for better identification.
  • Added more scenarios for how the summary dialog displays when scanning multiple files.
  • Improved the TXT summary format for certain scenarios.
  • Other minor fixes.
2 Likes