3. Get your VirusTotal API key:
   • Go to https://www.virustotal.com/gui/my-apikey
   • Register or log in (it's free)
   • Copy your API key

Usage

Option 1: Using .env file (Recommended)

1. Copy the .env.example file to .env:

   root@kitploit:~

   cp .env.example .env
   

2. Edit the .env file and add your configuration:

   root@kitploit:~

   VIRUSTOTAL_API_KEY=your_actual_api_key_here
   SCAN_FOLDER=C:\Users\username\Desktop\my_files
   

3. Run the script:

   root@kitploit:~

   python virustotal_scanner.py
   

The script will automatically load your configuration from the .env file.

Option 2: Interactive mode (without .env)

If you prefer not to use the .env file, the script will ask for the information:

The script will ask for:

1. Your VirusTotal API key
2. The path of the folder you want to scan

Usage example:

Valid path examples on Windows:

• C:\Users\username\Documents\my_files
• C:\Users\username\Desktop\folder
• . (dot = current folder)
• You can drag and drop the folder into the terminal

Generated files

After running the script, the following files will be generated automatically:

virustotal_scan.log

Log file with all events:

• Start and end of scan
• Each processed file
• Errors and warnings
• Final statistics

virustotal_results.csv

CSV file with results (semicolon-separated):

• Analysis date and time
• Filename
• Full path
• Size in bytes
• SHA256 hash
• Positive detections
• Total antivirus engines
• Detection percentage
• Status (CLEAN/DETECTED)
• VirusTotal URL

The CSV can be opened with Excel, Google Sheets, or any spreadsheet program.

Output example

Limitations and considerations

Free API limits:

• 4 files per minute (the script waits automatically)
• Maximum size: 32 MB per file
• Larger files will be skipped automatically

Files that are skipped:

• Files larger than 32 MB
• Empty files (0 bytes)
• Files without read permissions
• Files locked by the system

Important security notes

• Keep your API key private - Do not share it
• Files are analyzed publicly - Do not upload confidential files
• Files are shared with the security community - Once uploaded, they are public
• VirusTotal is for security analysis - Use it responsibly
• Do not upload personal or sensitive corporate data

What does the script do?

1. Finds ALL files in the folder and subfolders
2. Verifies that each file is valid for analysis
3. Checks if the file hash already exists in VirusTotal (saves time and bandwidth)
4. Uploads each file to VirusTotal if not found (respecting the 4 per minute limit)
5. Waits for analysis results
6. Shows the URL and detections (e.g., 0/70, 5/70)
7. Generates a complete summary at the end

Troubleshooting

Error: "Invalid API key"

• Verify that you copied your API key correctly
• Get a new one at https://www.virustotal.com/gui/my-apikey

Error: "Access denied to file"

• Some system files are protected
• Run as administrator if you need to analyze system files

The script is very slow

• This is normal: the free API is limited to 4 files per minute
• If you have 100 files, it will take approximately 25 minutes

Skipped files

• Check the final summary to see why they were skipped
• Files >32 MB cannot be analyzed with the free API

License

MIT License - Copyright (c) 2025 neorai

This project is free and open source. You can use, modify, and distribute it freely. See the LICENSE file for details.