VirusTotalAnalyzer 1.0.0

VirusTotalAnalyzer

VirusTotalAnalyzer is a typed .NET client for VirusTotal API v3. It covers reports, submissions, relationships, Intelligence endpoints, and the VirusTotal Monitor publisher workflow.

The package targets .NET Framework 4.7.2, .NET 8, and .NET 10.

dotnet add package VirusTotalAnalyzer

Create a client

using VirusTotalAnalyzer;

using var client = VirusTotalClient.Create(
    Environment.GetEnvironmentVariable("VIRUSTOTAL_API_KEY")
        ?? throw new InvalidOperationException("VIRUSTOTAL_API_KEY is not set."));

var report = await client.GetFileReportAsync(sha256, cancellationToken: cancellationToken);

Use the batch methods for public-key-friendly lookups. They preserve input order, suppress duplicate requests, cache successful reports, retry rate limits using Retry-After, and start requests 20 seconds apart by default:

var reports = await client.GetFileReportsBatchAsync(hashes, cancellationToken: cancellationToken);
foreach (var report in reports)
{
    var verdict = report.ToVerdict();
    Console.WriteLine($"{verdict.Id}: {verdict.Verdict} ({verdict.Malicious} malicious)");
}

Pass VirusTotalBatchOptions to tune the interval, cache duration, and retries for the account's quota. Direct singular and plural report methods remain unthrottled.

Typed network-object relationships include historical WHOIS, DNS resolutions, SSL certificate history, and communicating, referrer, or downloaded files:

var whois = await client.GetDomainHistoricalWhoisAsync("example.com", cancellationToken: cancellationToken);
var resolutions = await client.GetIpAddressResolutionsAsync("1.1.1.1", cancellationToken: cancellationToken);

VirusTotalClient.Create applies a bounded HTTP timeout. For custom proxies, client certificates, DNS behavior, or deterministic test transports, pass separate API and unauthenticated-download HttpMessageHandler instances. Automatic redirects must be disabled on both handler chains so the client can intercept signed download redirects and follow them without forwarding the API key.

using System.Net.Http;

using var apiHandler = new HttpClientHandler { AllowAutoRedirect = false };
using var downloadHandler = new HttpClientHandler { AllowAutoRedirect = false };
using var client = new VirusTotalClient(
    apiKey,
    apiHandler,
    downloadHandler,
    disposeHandlers: false);

The former single-HttpClient constructor is intentionally not public: an injected HttpClient does not expose whether its inner handler automatically follows redirects, so the library cannot guarantee that x-apikey stays on the authenticated VirusTotal API hop. Factory-created HttpClient instances are therefore not accepted; configure equivalent handlers directly for this client.

Register a publisher artifact with VirusTotal Monitor

Monitor uploads are different from ordinary public file submissions. They require a VirusTotal account with the Monitor publisher entitlement.

using VirusTotalAnalyzer.Models;

var receipt = await client.UploadMonitorFileAsync(
    artifactPath,
    new MonitorUploadOptions
    {
        Path = $"/TestimoX/{version}/win-x64/TestimoX.CLI.exe",
        Details = "Signed TestimoX release artifact",
        VerifySha256 = true,
        VerificationTimeout = TimeSpan.FromMinutes(2)
    },
    cancellationToken);

Console.WriteLine($"Verified {receipt.RemotePath}: {receipt.RemoteSha256}");

The upload streams file content, calculates the local SHA-256, selects the large-file upload endpoint above 32 MB, and fails if the remote hash disagrees or Monitor does not expose a hash before the verification timeout. Set VerifySha256 to false only when the caller intentionally accepts an unverified registration receipt; an upload receipt is not a clean antivirus verdict.

Use versioned destination paths instead of replacing earlier releases. To intentionally replace an existing item, set ExistingItemId instead of Path.

Query Monitor state

await foreach (var item in client.EnumerateMonitorItemsAsync(
    MonitorItemFilter.ByTags("new-detections"),
    cancellationToken: cancellationToken))
{
    Console.WriteLine($"{item.Attributes.Path}: {item.Attributes.LastDetectionsCount}");
}

await foreach (var monitorEvent in client.EnumerateMonitorEventsAsync(
    filter: "action:DETECTED",
    cancellationToken: cancellationToken))
{
    Console.WriteLine($"{monitorEvent.Timestamp:u} {monitorEvent.Subject}");
}

var statistics = await client.GetMonitorStatisticsAsync(cancellationToken: cancellationToken);

Monitor is asynchronous reputation tracking. Upload and hash verification prove that the intended artifact was registered; detections, resolved events, and statistics arrive as Monitor processes and periodically rescans the publisher collection.

PowerShell

The companion PowerShell module keeps the same behavior behind thin compiled cmdlets:

Send-VirusTotalMonitorFile `
    -ApiKey $env:VIRUSTOTAL_MONITOR_API_KEY `
    -File '.\TestimoX.CLI.exe' `
    -Path '/TestimoX/0.1.0/win-x64/TestimoX.CLI.exe' `
    -Details 'Signed TestimoX release artifact'

Get-VirusTotalMonitorItem -ApiKey $env:VIRUSTOTAL_MONITOR_API_KEY -List -Tag new-detections -All
Get-VirusTotalMonitorEvent -ApiKey $env:VIRUSTOTAL_MONITOR_API_KEY -Filter 'action:DETECTED' -All
Get-VirusTotalMonitorStatistics -ApiKey $env:VIRUSTOTAL_MONITOR_API_KEY

API keys are confined to authenticated VirusTotal API and upload requests. They are not sent to signed download URLs, included in upload results, or written to request diagnostics.

The Public API is intended for VirusTotal Community users and currently documents 500 requests per day and four requests per minute. It is not licensed for commercial products or services. Use an entitled service for commercial workflows and for relationships or account fields that the public key does not expose.