Evotec Services sp. z o.o., ul. Drozdów 6, Mikołów, 43-190, Poland

Working with VirusTotal from PowerShell

Virus Total Analyzer - PowerShell Module

Virus Total is an excellent service. It's a single place where hundreds of antivirus engines can verify if the file, URL, domain name, or IP Address is trusted or not. Of course, it's not a silver bullet, but it brings tremendous value, and I often verify files I download before executing. Since I release a lot of new or updated PowerShell modules on a weekly/monthly basis, I thought it would be great to send newly released versions straight to Virus Total so I can have them checked before anyone executes them. I also hope to prevent false positives from some antivirus vendors that may tag my modules as malware because they haven't seen the DLL or PowerShell module in this form before. I've seen it happen to DBATools, so why not try and push my modules before users even use them?

I've created a small PowerShell module, VirusTotalAnalyzer, which provides two simple commands that connect Virus Total using their Rest API v3. This is the newest API that is available. The module should work fine on PowerShell 5.1 and PowerShell 7+ and should work cross-platform, but I've not checked that yet.

Querying Virus Total for existing data with PowerShell

VirusTotalAnalyzer provides the Get-VirusReport function, which has five ways of requesting data from Virus Total. Those are by Hash, File, DomainName, IPAddress, or Search string. An important parameter of Get-VirusReport is the ApiKey parameter. You will need to have APIKey before you can use this module. Fortunately, ApiKey is available for free once you register to Virus Total. Once you have it the usage is as shown below

$VTApi = "APIKey"

$T1 = Get-VirusReport -ApiKey $VTApi -Hash 'BFF77EECBB2F7DA25ECBC9D9673E5DC1DB68DCC68FD76D006E836F9AC61C547E'
$T2 = Get-VirusReport -ApiKey $VTApi -File "$PSScriptRoot\Submisions\TestFile.txt"
$T3 = Get-VirusReport -ApiKey $VTApi -DomainName 'evotec.xyz'
$T4 = Get-VirusReport -ApiKey $VTApi -IPAddress '1.1.1.1'
$T5 = Get-VirusReport -ApiKey $VTApi -Search "https://evotec.xyz"

Each query returns similar data. It returns it the way Rest API returns it, and I'm not making any changes to the output. Data has multiple levels with different attributes available to you.

The reports are very detailed and deep. You are given many details depending on what has been scanned. For example, when scanning the PSM1 file, the object returns powershell_info attributes.

While the module is small, it provides enough functionality to help automate some of the processes I want my modules to go through. While other PowerShell modules deal with Virus Total, they don't use v3 API (AFYIK), and I always like to reinvent the wheel – why not?

Sending file / url to Virus Total using PowerShell

Using the New-VirusScan function, you can send files or URLs to be verified by Virus Total. Keep in mind that this is not an immediate process, and it takes 60 seconds to get information back from Virus Total. So you can either submit and verify your scan by using a hash or analysis ID provided as part of the New-VirusScan function.

Import-Module VirusTotalAnalyzer -Force

$VTApi = "APIKey"

# Submit file to scan
$Output = New-VirusScan -ApiKey $VTApi -File "$PSScriptRoot\Submisions\TestFile.txt"
$Output | Format-List

Start-Sleep -Seconds 120

# Since the output will return scan ID we can use it to get the report
$OutputScan = Get-VirusReport -ApiKey $VTApi -AnalysisId $Output.data.id
$OutputScan | Format-List
$OutputScan.Meta | Format-List
$OutputScan.Data | Format-List

New-VirusScan also provides an option to rescan file/hash. I didn't want to create a separate function for this functionality. You can rescan content that is already existing in Virus Total, forcing Virus Total to reassess whatever it has one more time with current definitions.

Import-Module VirusTotalAnalyzer -Force

$VTApi = "APIKey"

# Submit file hash to rescan from existing file (doesn't sends the file)
$Output = New-VirusScan -ApiKey $VTApi -FileHash "$PSScriptRoot\Submisions\TestFile.txt"
$Output | Format-List

# Submit hash to rescan
$Output = New-VirusScan -ApiKey $VTApi -Hash "ThisHashHasToExistsOnVirusTotal"
$Output | Format-List

Installing VirusTotalAnalyzer

Those functions are part of the VirusTotalAnalyzer module and all you need to do to install it is:

Install-Module VirusTotalAnalyzer -Force -Verbose

The module can also be installed without administrative privileges on the workstation using the Scope parameter.

Install-Module VirusTotalAnalyzer -Scope CurrentUser

For sources, reporting issues, or feature requests, as always, visit GitHub. All my projects are hosted on it, and it's the preferred method of providing support.

Related Posts