This tool collects file reports of suspicious files via VirusTotal APIv3. It queries the hash value of the specified file and all files contained in the specified directory. The VirusTotal API key is required to use this tool. If you don't have a VirusTotal API key, you can get one by creating a VirusTotal account.
 |
|---|
 |
 |
The main features are as follows:
- Save the file report in CSV format.
The CSV header fields are in the following order.
CSV_FIELD_NAMES = [
"seq_num",
# The following are properties retrieved from the file
"file_name",
"file_path",
"file_size",
"md5",
"sha1",
"sha256",
"access_time",
"change_time",
"modify_time",
# The following is the status of script processing
# If you uploaded the file, be sure to check the result of 'last_analysis_status'
# If the 'last_analysis_status' is 'queued', the scan may not have completed
"status_code",
"status_message",
"last_analysis_status",
# The following is information from the file report
"last_analysis_date",
"first_submission_date",
"times_submitted",
"type_description",
"trid",
"magic",
"meaningful_name",
"reputation",
"stats_malicious",
"stats_undetected",
"stats_harmless",
"stats_suspicious",
"stats_total",
"detected_malicious",
"detected_suspicious",
"sandbox",
"signature_product",
"signature_verified",
"signature_description",
"signature_signers",
"signature_copyright",
"votes_harmless",
"votes_malicious"
]- Save terminal output to a log file.
- Save response data in JSON format.
But it's not raw data. "temp_data" contained in JSON is extended data. It could also be dummy data generated by the script. - Save screenshots of VirusTotal detection page, etc. for documentation. (-s option)
You can save the following pages in PNG format.- hxxps://www[.]virustotal.com/gui/file/sha256/detection
- hxxps://www[.]virustotal.com/gui/file/sha256/summary
- hxxps://www[.]virustotal.com/gui/file/sha256/details
- hxxps://www[.]virustotal.com/gui/file/sha256/relations
- hxxps://www[.]virustotal.com/gui/file/sha256/behavior
- hxxps://www[.]virustotal.com/gui/file/sha256/community
- Open permalink (VirusTotal detection page) in default browser. (-z option)
- If "No matches found", You can upload suspicious files smaller than 650MB. (-u option)
If you need to upload files bigger than 32MB in size, you need additional privileges.
Make sure the all files does not contain 'sensitive data'.
Available since Python 3.6. Run Command Prompt or Terminal as administrator. To check the version, enter the following command:
python -V
or
python
Upgrade Python to the latest version if nessasary.
https://www.python.org/downloads/
Change the current directory to the location where you want to install and run the following command:
git clone https://github.com/1kmt/vtscan.git
cd vtscan
If "git clone" fails, you can download it as ZIP. Click "Download ZIP" from the "Code" dropdown.
Need packages for working. If the package is not installed, install it using the following command:
python -m pip install requests
python -m pip install selenium
python -m pip install webdriver_manager
If you get an error, update package to the latest version.
python -m pip install --upgrade [pip|requests|selenium|webdriver_manager]
See 'Command line examples'
usage: vtscan.py [-h] [-b] -i INPUT [INPUT ...] [-j] [-k APIKEY] [-o OUTPUT]
[-s {detection,summary,details,relations,behavior,community} [{detection,summary,details,relations,behavior,community} ...]]
[-u] [-v] [-w {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17}]
[-z]
Get a file report of suspicious files via VirusTotal API. It queries the hash
value of the specified file and all files contained in the specified
directory. It can also upload suspicious files.
optional arguments:
-h, --help show this help message and exit
-b, --batch disable interactive mode
-i INPUT [INPUT ...], --input INPUT [INPUT ...]
suspicious file or directory containing suspicious
files
-j, --json save response data in JSON format
-k APIKEY, --apikey APIKEY
specify your API key
-o OUTPUT, --output OUTPUT
change the output directory
-s {detection,summary,details,relations,behavior,community} [{detection,summary,details,relations,behavior,community} ...], --screenshot {detection,summary,details,relations,behavior,community} [{detection,summary,details,relations,behavior,community} ...]
take a screenshot of the VirusTotal detection page,
etc
-u, --upload upload and scan a file
-v, --version show program's version number and exit
-w {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17}, --wait {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17}
specify the waiting time for the next request
-z, --browser open permalink in browser
The -i option can be used to specify file or directory.
The -w option specifies the wait time for the next request.
If the key is a public key, specify 15; if the key is a private key, specify 0 (zero).
The Public API is limited to 500 requests per day and a rate of 4 requests per minute.
Public vs Premium API
python vtscan.py -i ./filename -k apiKey -w 0
python vtscan.py -i ./filename ./dirname -k apiKey -w 15
The API key and waiting time can also be embedded in the code.
# Public API key:15, Private API key(premium customers):0
WAITING_TIME = 0
# Used when hardcoding the API key
VT_API_KEY = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
The -u option uploads the file. If the -u option is specified, you will be prompted for user input.
>python vtscan.py -i ./filename -k apiKey -w 0 -u
2022-08-06 11:43:49[I] +------------------------- NOTICE -------------------------+
2022-08-06 11:43:49[I] | The -u option to upload and scan the file is specified. |
2022-08-06 11:43:49[I] | Make sure the all files does not contain sensitive data. |
2022-08-06 11:43:49[I] +-----------------------------------------------------------+
2022-08-06 11:43:49[I] Do you want to continue?(Y or N) >
The -s option takes a screenshot. You can select more than one from the options.
python vtscan.py -i ./filename -k apiKey -w 0 -s detection details
python vtscan.py -i ./filename -k apiKey -w 0 -s detection, details, relations, community
- Windows
Create a batch file and drag and drop onto it. The following is a simple example of a batch file.
@echo off
cd /d %~dp0
python ./vtscan.py -i %* -k apiKey -w 0
pause