Go SDK for VirusTotal API v3

A community Go client library for the VirusTotal API v3.

Quick Start

Get started quickly with the SDK using the Quick Start Guide, which includes:

• Installation instructions
• Your first API call
• Common operations (files, URLs, domains, IPs)
• Error handling patterns
• Response metadata access
• Links to configuration guides for production use

Examples

The examples directory contains complete working examples for all SDK features:

Each example includes a complete main.go with comments explaining the code.

SDK Services

IOC Reputation and Enrichment

• Files: Upload, scan, download, and retrieve file reports
• URLs: Scan URLs and retrieve analysis results
• Domains: Domain reputation and DNS information
• IP Addresses: IP address reputation and WHOIS data
• Analyses: Retrieve analysis results and submissions
• Comments: Manage comments on IOCs
• Code Insights: Analyze code snippets
• File Behaviours: Retrieve file behavior reports
• Attack Techniques/Tactics: MITRE ATT&CK framework integration
• Saved Searches: Manage saved VirusTotal searches

VT Enterprise

• Collections: Manage collections of IOCs
• Search and Metadata: Search for IOCs and retrieve metadata

HTTP Client Configuration

The SDK includes a powerful HTTP client with production-ready configuration options:

• Authentication - Secure API key management
• Timeouts & Retries - Configurable timeouts and automatic retry logic
• TLS/SSL Configuration - Custom certificates, mutual TLS, and security settings
• Proxy Support - HTTP/HTTPS/SOCKS5 proxy configuration
• Custom Headers - Global and per-request header management
• Structured Logging - Integration with zap for production logging
• OpenTelemetry Tracing - Distributed tracing and observability
• Debug Mode - Detailed request/response inspection

Configuration Options

The SDK client supports extensive configuration through functional options. Below is the complete list of available configuration options grouped by category.

Basic Configuration

client.WithAPIVersion("v3")              // Set API version
client.WithBaseURL("https://...")        // Custom base URL
client.WithTimeout(30*time.Second)       // Request timeout
client.WithRetryCount(3)                 // Number of retry attempts

TLS/Security

client.WithMinTLSVersion(tls.VersionTLS12)                    // Minimum TLS version
client.WithTLSClientConfig(tlsConfig)                         // Custom TLS configuration
client.WithRootCertificates("/path/to/ca.pem")                // Custom CA certificates
client.WithRootCertificateFromString(caPEM)                   // CA certificate from string
client.WithClientCertificate("/path/cert.pem", "/path/key.pem") // Client certificate (mTLS)
client.WithClientCertificateFromString(certPEM, keyPEM)       // Client cert from string
client.WithInsecureSkipVerify()                               // Skip cert verification (dev only!)

Network

client.WithProxy("http://proxy:8080")    // HTTP/HTTPS/SOCKS5 proxy
client.WithTransport(customTransport)    // Custom HTTP transport

Headers

client.WithUserAgent("MyApp/1.0")                      // Set User-Agent header
client.WithCustomAgent("MyApp", "1.0")                 // Custom agent with version
client.WithGlobalHeader("X-Custom-Header", "value")    // Add single global header
client.WithGlobalHeaders(map[string]string{...})       // Add multiple global headers

Observability

client.WithLogger(zapLogger)            // Structured logging with zap
client.WithTracing(otelConfig)          // OpenTelemetry distributed tracing
client.WithDebug()                      // Enable debug mode (dev only!)

Example: Production Configuration

import (
    "crypto/tls"
    "time"
    "go.uber.org/zap"
)

logger, _ := zap.NewProduction()

apiClient, err := client.NewClient(
    "your-api-key",
    client.WithTimeout(30*time.Second),
    client.WithRetryCount(3),
    client.WithLogger(logger),
    client.WithMinTLSVersion(tls.VersionTLS12),
    client.WithGlobalHeader("X-Application-Name", "MySecurityApp"),
)

See the configuration guides for detailed documentation on each option.

Documentation

• VirusTotal API v3 Documentation
• GoDoc

Contributing

Contributions are welcome! Please read our Contributing Guidelines before submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Documentation: API Docs

Disclaimer

This is an unofficial SDK and is not affiliated with or endorsed by VirusTotal or Chronicle LLC.