VTSharp 1.0.0

VTSharp

VTSharp is a .NET library for retrieving file scan reports from VirusTotal.

It uses Playwright to access VirusTotal's web interface and extract antivirus detection results, allowing .NET applications to retrieve and process file scan reports without having to implement browser automation themselves.

Requirements

VTSharp requires Playwright to be installed and configured in the environment where the application is running.

Disclaimer

VTSharp is an independent, unofficial, open-source project. It is not affiliated with, associated with, authorized by, endorsed by, or sponsored by VirusTotal or Google.

VirusTotal is a trademark of Google LLC. VTSharp is not intended to represent or impersonate VirusTotal, Google, or any of their products or services.

VTSharp is simply a technical tool that uses browser automation to interact with the publicly accessible VirusTotal web interface. It does not provide, resell, or redistribute VirusTotal's services.

The author does not claim ownership of VirusTotal, its trademarks, its services, or any data provided by VirusTotal.

This project is provided solely as a technical integration tool. You are solely responsible for how you use it and for ensuring that your use complies with VirusTotal's terms of service, policies, and applicable laws.

The author makes no guarantees regarding the availability, accuracy, reliability, or continued compatibility of VTSharp with VirusTotal.

Features

• Retrieve VirusTotal file reports using a SHA-256 hash.
• Extract antivirus detection results.
• Identify the number of positive detections and total scanning engines.
• Classify files as Safe, Suspicious, or Dangerous.
• Optional proxy support.
• Configurable navigation and detection timeouts.
• Dependency Injection support.
• Async API.

Installation

Install the VTSharp NuGet package:

dotnet add package VTSharp

Dependency Injection

Register VTSharp in your application's dependency injection container:

var serviceProvider = new ServiceCollection()
    .AddVTSharp()
    .BuildServiceProvider();

You can configure VTSharp using VTSharpOptions:

var serviceProvider = new ServiceCollection()
    .AddVTSharp(options =>
    {
        options.ProxyServer = "http://127.0.0.1:8080";
        options.ProxyUsername = "username";
        options.ProxyPassword = "password";

        options.NavigationTimeout = TimeSpan.FromSeconds(30);
        options.DetectionTimeout = TimeSpan.FromSeconds(15);
    })
    .BuildServiceProvider();

All options are optional.

public class VTSharpOptions
{
    public string? ProxyServer { get; set; }

    public string? ProxyUsername { get; set; }

    public string? ProxyPassword { get; set; }

    public TimeSpan NavigationTimeout { get; set; }
        = TimeSpan.FromSeconds(30);

    public TimeSpan DetectionTimeout { get; set; }
        = TimeSpan.FromSeconds(15);
}

If no proxy is configured, VTSharp connects directly.

Usage

Resolve IVTClient from the dependency injection container:

var client = serviceProvider.GetRequiredService<IVTClient>();

Then, retrieve the report using the file's SHA-256 hash:

string sha256 = "2546dcffc5ad854d4ddc64fbf056871cd5a00f2471cb7a5bfd4ac23b6e9eedad";
 
var report = await client.GetFileReportAsync(sha256);

The Sha256 property is used to locate the file report on VirusTotal.

File Report

GetFileReportAsync returns a FileReportResult containing the analysis information:

public sealed class FileReportResult
{
    public string FileName { get; init; }

    public string Sha256 { get; init; }

    public string FileSize { get; init; }

    public int PositiveDetections { get; init; }

    public int TotalEngines { get; init; }

    public bool IsSuccessful { get; init; }

    public string? ErrorMessage { get; init; }

    public List<Detection> Detections { get; init; }

    public FileStatus Status { get; }
}

File Status

VTSharp calculates a simple status based on the proportion of positive detections:

• Safe — less than 10% of engines detected the file.
• Suspicious — between 10% and 40% of engines detected the file.
• Dangerous — 40% or more of engines detected the file.

Error Handling

If the report cannot be retrieved, IsSuccessful will be false and ErrorMessage will contain the error information.

if (!report.IsSuccessful)
{
    Console.WriteLine($"Scan failed: {report.ErrorMessage}");
    return;
}