Posh-VirusTotal

Posh-VirusTotal is a PowerShell module providing direct integration with VirusTotal API v3. It enables file submission, URL scanning, hash lookups, domain reputation analysis, and comprehensive threat intelligence queries from Windows environments.

Installation

# Install from PowerShell Gallery
Install-Module -Name Posh-VirusTotal -Scope CurrentUser

# Or download from GitHub
git clone https://github.com/darkoperator/Posh-VirusTotal
Import-Module .\Posh-VirusTotal\Posh-VirusTotal.psd1

# Import module
Import-Module Posh-VirusTotal

# Verify installation
Get-Module Posh-VirusTotal

# Set API key (obtain from https://www.virustotal.com/gui/settings/api)
$VirusTotalAPIKey = "your_api_key_here"

Basic Commands

Command	Description
Get-VTFileReport	Lookup file by hash
Get-VTURLReport	Lookup URL reputation
Get-VTDomainReport	Get domain info
Get-VTIPReport	Get IP reputation
Submit-VTFile	Upload file for scanning

File Analysis by Hash

# Get file report by MD5 hash
Get-VTFileReport -Hash "d41d8cd98f00b204e9800998ecf8427e" -APIKey $VirusTotalAPIKey

# SHA1 hash lookup
Get-VTFileReport -Hash "da39a3ee5e6b4b0d3255bfef95601890afd80709" -APIKey $VirusTotalAPIKey

# SHA256 hash lookup
Get-VTFileReport -Hash "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" -APIKey $VirusTotalAPIKey

# Get detection results from multiple AV engines
Get-VTFileReport -Hash "d41d8cd98f00b204e9800998ecf8427e" -APIKey $VirusTotalAPIKey | Select-Object -ExpandProperty names

# Get detailed vendor detections
Get-VTFileReport -Hash "d41d8cd98f00b204e9800998ecf8427e" -APIKey $VirusTotalAPIKey | `
    Select-Object -ExpandProperty last_analysis_results | Format-Table

# Get malware families
Get-VTFileReport -Hash "d41d8cd98f00b204e9800998ecf8427e" -APIKey $VirusTotalAPIKey | `
    Select-Object -ExpandProperty last_analysis_stats

# Get submission history
Get-VTFileReport -Hash "d41d8cd98f00b204e9800998ecf8427e" -APIKey $VirusTotalAPIKey | `
    Select-Object -ExpandProperty submission_names

File Upload and Submission

# Submit single file for scanning
Submit-VTFile -Path "C:\suspicious.exe" -APIKey $VirusTotalAPIKey

# Submit with additional metadata
Submit-VTFile -Path "C:\suspicious.exe" -APIKey $VirusTotalAPIKey | Select-Object -ExpandProperty data

# Get scan ID
$ScanResult = Submit-VTFile -Path "C:\malware.bin" -APIKey $VirusTotalAPIKey
$ScanResult.data.id

# Check scan status
Get-VTFileScan -ScanID $ScanResult.data.id -APIKey $VirusTotalAPIKey

# Poll until scan completes
do {
    Start-Sleep -Seconds 5
    $Status = Get-VTFileScan -ScanID $ScanID -APIKey $VirusTotalAPIKey
} while ($Status.data.attributes.status -eq "queued")

URL Analysis

# Scan URL
Submit-VTURL -URL "http://malicious.com" -APIKey $VirusTotalAPIKey

# Get URL report
Get-VTURLReport -URL "http://example.com" -APIKey $VirusTotalAPIKey

# Get URL scan results
Get-VTURLScan -URL "http://target.com" -APIKey $VirusTotalAPIKey

# Get last analysis results
Get-VTURLReport -URL "http://example.com" -APIKey $VirusTotalAPIKey | `
    Select-Object -ExpandProperty last_analysis_results

# Get detection count
Get-VTURLReport -URL "http://example.com" -APIKey $VirusTotalAPIKey | `
    Select-Object -ExpandProperty last_analysis_stats

# Get URL categories
Get-VTURLReport -URL "http://example.com" -APIKey $VirusTotalAPIKey | `
    Select-Object -ExpandProperty categories

# Check for phishing
Get-VTURLReport -URL "http://phishing-site.com" -APIKey $VirusTotalAPIKey | `
    Select-Object -ExpandProperty last_http_response_code

Domain Intelligence

# Get domain report
Get-VTDomainReport -Domain "example.com" -APIKey $VirusTotalAPIKey

# Get DNS records
Get-VTDomainReport -Domain "example.com" -APIKey $VirusTotalAPIKey | `
    Select-Object -ExpandProperty dns_records

# Get category information
Get-VTDomainReport -Domain "example.com" -APIKey $VirusTotalAPIKey | `
    Select-Object -ExpandProperty categories

# Get domain whois
Get-VTDomainReport -Domain "example.com" -APIKey $VirusTotalAPIKey | `
    Select-Object -ExpandProperty whois

# Get resolutions (IP addresses)
Get-VTDomainReport -Domain "example.com" -APIKey $VirusTotalAPIKey | `
    Select-Object -ExpandProperty resolutions

# Get subdomains
Get-VTDomainReport -Domain "example.com" -APIKey $VirusTotalAPIKey | `
    Select-Object -ExpandProperty subdomains

# Get HTTPS certificate info
Get-VTDomainReport -Domain "example.com" -APIKey $VirusTotalAPIKey | `
    Select-Object -ExpandProperty last_certificate

IP Address Reputation

# Get IP reputation
Get-VTIPReport -IP "1.2.3.4" -APIKey $VirusTotalAPIKey

# Get ASN information
Get-VTIPReport -IP "1.2.3.4" -APIKey $VirusTotalAPIKey | Select-Object -ExpandProperty asn

# Get country
Get-VTIPReport -IP "1.2.3.4" -APIKey $VirusTotalAPIKey | Select-Object -ExpandProperty country

# Get reverse DNS
Get-VTIPReport -IP "1.2.3.4" -APIKey $VirusTotalAPIKey | Select-Object -ExpandProperty last_dns_records

# Check if whitelisted
Get-VTIPReport -IP "1.2.3.4" -APIKey $VirusTotalAPIKey | Select-Object -ExpandProperty last_analysis_stats

# Get malware samples hosted on IP
Get-VTIPReport -IP "1.2.3.4" -APIKey $VirusTotalAPIKey | `
    Select-Object -ExpandProperty last_analysis_results

# Get WHOIS information
Get-VTIPReport -IP "1.2.3.4" -APIKey $VirusTotalAPIKey | Select-Object -ExpandProperty whois

Comments and Community Intelligence

# Get comments on file
Get-VTFileComment -Hash "hash_value" -APIKey $VirusTotalAPIKey

# Add comment to file
Add-VTFileComment -Hash "hash_value" -Comment "Trojan detected in environment" -APIKey $VirusTotalAPIKey

# Get URL comments
Get-VTURLComment -URL "http://example.com" -APIKey $VirusTotalAPIKey

# Add comment to URL
Add-VTURLComment -URL "http://example.com" -Comment "Phishing attempt" -APIKey $VirusTotalAPIKey

# Get domain comments
Get-VTDomainComment -Domain "example.com" -APIKey $VirusTotalAPIKey

# Get IP comments
Get-VTIPComment -IP "1.2.3.4" -APIKey $VirusTotalAPIKey

Batch Operations and Automation

# Scan multiple files from directory
Get-ChildItem "C:\suspicious" -Filter "*.exe" | ForEach-Object {
    Submit-VTFile -Path $_.FullName -APIKey $VirusTotalAPIKey
    Start-Sleep -Seconds 15  # Rate limiting
}

# Lookup hashes from file
Get-Content "hashes.txt" | ForEach-Object {
    Get-VTFileReport -Hash $_ -APIKey $VirusTotalAPIKey | `
        Select-Object @{N="Hash";E={$_}}, @{N="Detections";E={$_.last_analysis_stats.malicious}}
}

# Scan URLs from list
$URLs = @("http://site1.com", "http://site2.com", "http://site3.com")
$URLs | ForEach-Object {
    $Report = Get-VTURLReport -URL $_ -APIKey $VirusTotalAPIKey
    [PSCustomObject]@{
        URL = $_
        Detections = $Report.last_analysis_stats.malicious
        Harmless = $Report.last_analysis_stats.harmless
    }
}

# Bulk domain analysis
Get-Content "domains.txt" | ForEach-Object {
    $Domain = $_
    $Report = Get-VTDomainReport -Domain $Domain -APIKey $VirusTotalAPIKey
    [PSCustomObject]@{
        Domain = $Domain
        Category = $Report.categories.values
        Malicious = $Report.last_analysis_stats.malicious
        IPs = ($Report.resolutions.ip_address | Measure-Object).Count
    }
}

Advanced Analysis Workflows

# Complete file analysis
function Analyze-File {
    param(
        [string]$FilePath,
        [string]$APIKey
    )

    $FileHash = (Get-FileHash -Path $FilePath -Algorithm SHA256).Hash
    $Report = Get-VTFileReport -Hash $FileHash -APIKey $APIKey

    $Analysis = [PSCustomObject]@{
        File = (Split-Path -Leaf $FilePath)
        Hash = $FileHash
        Detections = $Report.last_analysis_stats.malicious
        TotalAnalyzers = ($Report.last_analysis_results | Measure-Object).Count
        MalwareFamilies = @()
    }

    # Extract malware families
    $Report.last_analysis_results | Where-Object { $_.category -eq "malicious" } | ForEach-Object {
        $Analysis.MalwareFamilies += $_.result
    }

    return $Analysis
}

# Recursive directory scanning
function Scan-Directory {
    param(
        [string]$Path,
        [string]$APIKey
    )

    $Results = @()
    Get-ChildItem -Path $Path -Recurse -File | ForEach-Object {
        $Analysis = Analyze-File -FilePath $_.FullName -APIKey $APIKey
        $Results += $Analysis
        Start-Sleep -Seconds 4  # Rate limit
    }

    return $Results
}

# Export results
$Results = Scan-Directory -Path "C:\suspicious" -APIKey $VirusTotalAPIKey
$Results | Export-Csv -Path "malware_analysis.csv" -NoTypeInformation

Threat Intelligence Reporting

# Generate threat summary
function Get-ThreatSummary {
    param(
        [string[]]$Indicators,
        [string]$APIKey
    )

    $Summary = @{
        MaliciousFiles = 0
        MaliciousURLs = 0
        MaliciousDomains = 0
        MaliciousIPs = 0
        UndetectedItems = 0
    }

    foreach ($Indicator in $Indicators) {
        # Detect type and analyze
        if ($Indicator -match "^[a-f0-9]{32}$|^[a-f0-9]{40}$|^[a-f0-9]{64}$") {
            # Hash
            $Report = Get-VTFileReport -Hash $Indicator -APIKey $APIKey
            if ($Report.last_analysis_stats.malicious -gt 0) { $Summary.MaliciousFiles++ }
        }
        elseif ($Indicator -match "^https?://") {
            # URL
            $Report = Get-VTURLReport -URL $Indicator -APIKey $APIKey
            if ($Report.last_analysis_stats.malicious -gt 0) { $Summary.MaliciousURLs++ }
        }
        elseif ($Indicator -match "^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$") {
            # IP
            $Report = Get-VTIPReport -IP $Indicator -APIKey $APIKey
            if ($Report.last_analysis_stats.malicious -gt 0) { $Summary.MaliciousIPs++ }
        }
        else {
            # Domain
            $Report = Get-VTDomainReport -Domain $Indicator -APIKey $APIKey
            if ($Report.last_analysis_stats.malicious -gt 0) { $Summary.MaliciousDomains++ }
        }
    }

    return $Summary
}

# Get summary
$Summary = Get-ThreatSummary -Indicators @("file_hash", "example.com", "1.2.3.4") -APIKey $VirusTotalAPIKey
$Summary | Format-Table

Error Handling and Logging

# Implement error handling
try {
    $Report = Get-VTFileReport -Hash "invalid_hash" -APIKey $VirusTotalAPIKey
}
catch {
    Write-Error "Failed to get report: $($_.Exception.Message)"
}

# Logging function
function Log-VTQuery {
    param(
        [string]$Indicator,
        [string]$Type,
        [int]$Detections,
        [string]$LogPath = "C:\logs\vt_queries.log"
    )

    $Timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
    $LogEntry = "$Timestamp | $Type | $Indicator | Detections: $Detections"
    Add-Content -Path $LogPath -Value $LogEntry
}

# Rate limiting
function Invoke-VTQuery {
    param(
        [scriptblock]$Query,
        [int]$DelaySeconds = 4
    )

    & $Query
    Start-Sleep -Seconds $DelaySeconds
}

Best Practices

• Store API key securely using Windows Credential Manager or Azure Key Vault
• Implement rate limiting (4+ seconds between requests)
• Use hash lookups for file analysis (faster, no upload)
• Cache results to reduce API calls
• Implement error handling for network issues
• Log all queries for audit trail
• Use batch operations for multiple indicators
• Verify positive results with secondary sources
• Document malware families and indicators
• Archive analysis reports regularly

Troubleshooting

# Verify API key
Test-VTConnection -APIKey $VirusTotalAPIKey

# Check API rate limits
Get-VTAPIStatus -APIKey $VirusTotalAPIKey

# Enable verbose output
$VerbosePreference = "Continue"
Get-VTFileReport -Hash "hash" -APIKey $VirusTotalAPIKey -Verbose

# Test connectivity
Test-NetConnection -ComputerName www.virustotal.com -Port 443

References

• VirusTotal API v3 Documentation
• Posh-VirusTotal GitHub
• VirusTotal Intelligence
• MITRE ATT&CK Framework

---

Last updated: 2026-03-30