vtutil

package
v0.0.0-...-fd57926 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 28, 2025 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package vtutil provides utilities for interacting with the VirusTotal API to scan files, URLs, domains, and IP addresses for security threats.

Index

Constants

View Source 
const (
	DefaultRateLimitPerMinute = 4    // Default API request limit per minute (free tier)
	DefaultRetryCount         = 3    // Default number of retries for failed requests
	DefaultRetryDelay         = 5    // Default delay between retries in seconds
	DefaultResultCacheTTL     = 3600 // Default cache TTL in seconds (1 hour)
)

Default settings

View Source 
const (
	HashTypeMD5    = "md5"
	HashTypeSHA1   = "sha1"
	HashTypeSHA256 = "sha256"
)

File hash types

Variables

This section is empty.

Functions

func Configure 

func Configure(config Config) error

Initialize sets up the vtutil package with the provided configuration

func ConfigureFromEnv 

func ConfigureFromEnv() error

ConfigureFromEnv loads configuration from environment variables

func ConfigureFromFile 

func ConfigureFromFile(filePath string) error

ConfigureFromFile loads configuration from a JSON file

func GetSubdomains 

func GetSubdomains(domain string) ([]string, error)

GetSubdomains retrieves all known subdomains for a domain

func InitCache 

func InitCache(storage CacheStorage, defaultTTL time.Duration)

InitCache initializes the cache with the specified storage

func InitFileCache 

func InitFileCache(cachePath string, ttl time.Duration) error

InitFileCache initializes a file-based cache

func InitMemoryCache 

func InitMemoryCache(ttl time.Duration) error

InitMemoryCache initializes a memory-based cache

func IsInitialized 

func IsInitialized() bool

IsInitialized returns whether the package has been initialized

func SaveConfig 

func SaveConfig(filePath string) error

SaveConfig saves the current configuration to a file

func ThreatLevelToString 

func ThreatLevelToString(level ThreatLevel) string

ThreatLevelToString converts a threat level to its string representation

func WithAdditionalParams 

func WithAdditionalParams(params map[string]string) func(*FileScanOptions)

WithAdditionalParams sets additional API parameters

func WithCacheTTL 

func WithCacheTTL(ttlSeconds int) func(*ClientConfig)

WithCacheTTL sets the cache time-to-live

func WithCustomHost 

func WithCustomHost(host string) func(*ClientConfig)

WithCustomHost sets a custom API host

func WithCustomName 

func WithCustomName(name string) func(*FileScanOptions)

WithCustomName sets a custom name for the file

func WithCustomTags 

func WithCustomTags(tags []string) func(*FileScanOptions)

WithCustomTags sets custom tags for the file

func WithDisableRateLimit 

func WithDisableRateLimit(disable bool) func(*ClientConfig)

WithDisableRateLimit disables rate limiting

func WithDomainAdditionalParams 

func WithDomainAdditionalParams(params map[string]string) func(*DomainOptions)

WithDomainAdditionalParams sets additional API parameters

func WithDomainCache 

func WithDomainCache(enable bool) func(*DomainOptions)

WithDomainCache enables or disables caching

func WithDomainCertificates 

func WithDomainCertificates(include bool) func(*DomainOptions)

WithDomainCertificates enables or disables certificate data in the result

func WithDomainEngineDetail 

func WithDomainEngineDetail(includeDetail bool) func(*DomainOptions)

WithDomainEngineDetail enables or disables detailed engine results

func WithDomainResolutions 

func WithDomainResolutions(include bool) func(*DomainOptions)

WithDomainResolutions enables or disables resolution records in the result

func WithDomainSubdomains 

func WithDomainSubdomains(include bool) func(*DomainOptions)

WithDomainSubdomains enables or disables subdomains in the result

func WithDomainWhois 

func WithDomainWhois(include bool) func(*DomainOptions)

WithDomainWhois enables or disables WHOIS data in the result

func WithEngineDetail 

func WithEngineDetail(includeDetail bool) func(*FileScanOptions)

WithEngineDetail enables or disables detailed engine results

func WithFileCache 

func WithFileCache(enable bool) func(*FileScanOptions)

WithFileCache enables or disables caching

func WithIPAdditionalParams 

func WithIPAdditionalParams(params map[string]string) func(*IPOptions)

WithIPAdditionalParams sets additional API parameters

func WithIPCache 

func WithIPCache(enable bool) func(*IPOptions)

WithIPCache enables or disables caching

func WithIPEngineDetail 

func WithIPEngineDetail(includeDetail bool) func(*IPOptions)

WithIPEngineDetail enables or disables detailed engine results

func WithIPResolutions 

func WithIPResolutions(include bool) func(*IPOptions)

WithIPResolutions enables or disables resolution records in the result

func WithIPWhois 

func WithIPWhois(include bool) func(*IPOptions)

WithIPWhois enables or disables WHOIS data in the result

func WithPollingSettings 

func WithPollingSettings(interval, timeout time.Duration) func(*FileScanOptions)

WithPollingSettings configures polling settings

func WithProgressCallback 

func WithProgressCallback(callback func(float32)) func(*FileScanOptions)

WithProgressCallback sets a progress callback for upload

func WithRateLimit 

func WithRateLimit(requestsPerMinute int) func(*ClientConfig)

WithRateLimit sets the rate limit for API requests

func WithRetrySettings 

func WithRetrySettings(count int, delay time.Duration) func(*ClientConfig)

WithRetrySettings configures retry behavior

func WithURLAdditionalParams 

func WithURLAdditionalParams(params map[string]string) func(*URLScanOptions)

WithURLAdditionalParams sets additional API parameters

func WithURLCache 

func WithURLCache(enable bool) func(*URLScanOptions)

WithURLCache enables or disables caching

func WithURLCustomTags 

func WithURLCustomTags(tags []string) func(*URLScanOptions)

WithURLCustomTags sets custom tags for the URL scan

func WithURLEngineDetail 

func WithURLEngineDetail(includeDetail bool) func(*URLScanOptions)

WithURLEngineDetail enables or disables detailed engine results

func WithURLPollingSettings 

func WithURLPollingSettings(interval, timeout time.Duration) func(*URLScanOptions)

WithURLPollingSettings configures polling settings

func WithURLWaitForCompletion 

func WithURLWaitForCompletion(wait bool) func(*URLScanOptions)

WithURLWaitForCompletion sets whether to wait for scan completion

func WithWaitForCompletion 

func WithWaitForCompletion(wait bool) func(*FileScanOptions)

WithWaitForCompletion sets whether to wait for scan completion

Types

type Cache 

type Cache struct {
	// contains filtered or unexported fields
}

Cache represents the caching system for VirusTotal API results 

var (
	GlobalCache *Cache
)

GlobalCache is the global instance of the cache

func GetCache 

func GetCache() (*Cache, error)

GetCache returns the global cache instance

func (*Cache) Clear 

func (c *Cache) Clear() error

Clear removes all items from the cache

func (*Cache) Delete 

func (c *Cache) Delete(key string) error

Delete removes an item from the cache

func (*Cache) Disable 

func (c *Cache) Disable()

Disable disables the cache

func (*Cache) Enable 

func (c *Cache) Enable()

Enable enables the cache

func (*Cache) Get 

func (c *Cache) Get(key string, target interface{}) (bool, error)

Get retrieves an item from the cache

func (*Cache) IsEnabled 

func (c *Cache) IsEnabled() bool

IsEnabled returns whether the cache is enabled

func (*Cache) Set 

func (c *Cache) Set(key string, value interface{}) error

Set stores an item in the cache

func (*Cache) SetWithTTL 

func (c *Cache) SetWithTTL(key string, value interface{}, ttl time.Duration) error

SetWithTTL stores an item in the cache with a custom TTL

type CacheMode 

type CacheMode string

CacheMode determines how cache is stored 

const (
	// CacheModeNone disables caching
	CacheModeNone CacheMode = "none"

	// CacheModeMemory stores cache in memory
	CacheModeMemory CacheMode = "memory"

	// CacheModeFile stores cache in files
	CacheModeFile CacheMode = "file"
)

type CacheStorage 

type CacheStorage interface {
	// Get retrieves a value from the cache
	Get(key string) ([]byte, bool, error)

	// Set stores a value in the cache
	Set(key string, value []byte, ttl time.Duration) error

	// Delete removes a value from the cache
	Delete(key string) error

	// Clear removes all values from the cache
	Clear() error
}

CacheStorage defines the interface for cache storage backends

type CertificateInfo 

type CertificateInfo struct {
	Issuer         string    `json:"issuer"`
	Subject        string    `json:"subject"`
	ValidFrom      time.Time `json:"valid_from"`
	ValidTo        time.Time `json:"valid_to"`
	SerialNumber   string    `json:"serial_number"`
	Thumbprint     string    `json:"thumbprint"`
	Version        int       `json:"version"`
	SubjectAltName []string  `json:"subject_alt_name"`
}

CertificateInfo contains information about a domain's HTTPS certificate

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is a thread-safe wrapper for the VirusTotal client

func GetClient 

func GetClient() (*Client, error)

GetClient returns the initialized global client instance or an error if not initialized

func Initialize 

func Initialize(apiKey string, options ...func(*ClientConfig)) (*Client, error)

Initialize creates or returns the global client instance

type ClientConfig 

type ClientConfig struct {
	APIKey           string        // VirusTotal API key
	RateLimitPerMin  int           // Rate limit for API requests per minute
	RetryCount       int           // Number of retries for failed requests
	RetryDelay       time.Duration // Delay between retries
	ResultCacheTTL   int           // Time-to-live for cached results in seconds
	CustomHost       string        // Optional custom VirusTotal API host
	DisableRateLimit bool          // Option to disable rate limiting (use with caution)
}

ClientConfig holds configuration for the VirusTotal client

func DefaultClientConfig 

func DefaultClientConfig() ClientConfig

DefaultClientConfig returns a default configuration for the client

type Config 

type Config struct {
	// API configuration
	APIKey           string        `json:"api_key"`
	CustomHost       string        `json:"custom_host,omitempty"`
	RateLimitPerMin  int           `json:"rate_limit_per_min"`
	RetryCount       int           `json:"retry_count"`
	RetryDelay       time.Duration `json:"retry_delay"`
	DisableRateLimit bool          `json:"disable_rate_limit"`

	// Cache configuration
	CacheMode CacheMode     `json:"cache_mode"`
	CacheTTL  time.Duration `json:"cache_ttl"`
	CachePath string        `json:"cache_path,omitempty"`

	// File scan defaults
	FileDefaultWaitForCompletion bool          `json:"file_default_wait_for_completion"`
	FilePollingInterval          time.Duration `json:"file_polling_interval"`
	FilePollingTimeout           time.Duration `json:"file_polling_timeout"`

	// URL scan defaults
	URLDefaultWaitForCompletion bool          `json:"url_default_wait_for_completion"`
	URLPollingInterval          time.Duration `json:"url_polling_interval"`
	URLPollingTimeout           time.Duration `json:"url_polling_timeout"`

	// Domain scan defaults
	DomainDefaultIncludeSubdomains   bool `json:"domain_default_include_subdomains"`
	DomainDefaultIncludeResolutions  bool `json:"domain_default_include_resolutions"`
	DomainDefaultIncludeWhois        bool `json:"domain_default_include_whois"`
	DomainDefaultIncludeCertificates bool `json:"domain_default_include_certificates"`

	// IP scan defaults
	IPDefaultIncludeResolutions bool `json:"ip_default_include_resolutions"`
	IPDefaultIncludeWhois       bool `json:"ip_default_include_whois"`

	// Logging configuration
	LogSuccessfulScans bool `json:"log_successful_scans"`
	LogDetailLevel     int  `json:"log_detail_level"` // 0=minimal, 1=normal, 2=verbose
}

Config contains all configuration for the vtutil package

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns the default configuration

func GetConfig 

func GetConfig() *Config

GetConfig returns the current configuration

type ConfigMode 

type ConfigMode string

ConfigMode determines how the package handles configuration 

const (
	// ConfigModeManual requires explicit configuration through code
	ConfigModeManual ConfigMode = "manual"

	// ConfigModeFile loads configuration from a file
	ConfigModeFile ConfigMode = "file"

	// ConfigModeEnv loads configuration from environment variables
	ConfigModeEnv ConfigMode = "env"
)

type DomainOptions 

type DomainOptions struct {
	EnableCache         bool              // Whether to use caching
	IncludeSubdomains   bool              // Include subdomains list
	IncludeResolutions  bool              // Include DNS resolution history
	IncludeWhois        bool              // Include WHOIS data
	IncludeCertificates bool              // Include HTTPS certificate data
	SkipEngineDetail    bool              // Skip detailed engine results
	AdditionalParams    map[string]string // Additional API parameters
}

DomainOptions represents options for domain analysis

func DefaultDomainOptions 

func DefaultDomainOptions() DomainOptions

DefaultDomainOptions returns default options for domain analysis

type DomainReputationLevel 

type DomainReputationLevel string

DomainReputationLevel represents a domain's reputation level 

const (
	DomainReputationClean     DomainReputationLevel = "clean"
	DomainReputationLow       DomainReputationLevel = "low_risk"
	DomainReputationMedium    DomainReputationLevel = "medium_risk"
	DomainReputationHigh      DomainReputationLevel = "high_risk"
	DomainReputationMalicious DomainReputationLevel = "malicious"
	DomainReputationUnknown   DomainReputationLevel = "unknown"
)

Domain reputation levels

type DomainResult 

type DomainResult struct {
	Domain           string                `json:"domain"`
	Status           DomainScanStatus      `json:"status"`
	Resource         string                `json:"resource"`
	Permalink        string                `json:"permalink"`
	Categories       map[string]string     `json:"categories"`
	Reputation       int                   `json:"reputation"`
	ReputationLevel  DomainReputationLevel `json:"reputation_level"`
	LastAnalysisDate time.Time             `json:"last_analysis_date"`
	TotalVotes       struct {
		Harmless  int `json:"harmless"`
		Malicious int `json:"malicious"`
	} `json:"total_votes"`
	RegisteredDate       *time.Time              `json:"registered_date,omitempty"`
	ExpirationDate       *time.Time              `json:"expiration_date,omitempty"`
	Registrar            string                  `json:"registrar,omitempty"`
	Subdomains           []string                `json:"subdomains,omitempty"`
	ResolutionRecords    []ResolutionRecord      `json:"resolution_records,omitempty"`
	WhoisInfo            map[string]string       `json:"whois_info,omitempty"`
	LastHTTPSCertificate *CertificateInfo        `json:"last_https_certificate,omitempty"`
	EngineResults        map[string]EngineResult `json:"engine_results"`
	Tags                 []string                `json:"tags"`
	Error                string                  `json:"error,omitempty"`
}

DomainResult represents the result of a domain analysis

func CheckDomainReputation 

func CheckDomainReputation(domain string) (*DomainResult, error)

CheckDomainReputation checks if a domain has known malicious activities

func LookupDomain 

func LookupDomain(domain string, options ...func(*DomainOptions)) (*DomainResult, error)

LookupDomain retrieves information about a domain from VirusTotal

func (*DomainResult) GetError 

func (r *DomainResult) GetError() string
func (r *DomainResult) GetPermalink() string

func (*DomainResult) GetResource 

func (r *DomainResult) GetResource() string

func (*DomainResult) GetScanDate 

func (r *DomainResult) GetScanDate() time.Time

func (*DomainResult) GetStatus 

func (r *DomainResult) GetStatus() ScanStatus

Implement ScanResult interface for DomainResult

func (*DomainResult) GetThreatLevel 

func (r *DomainResult) GetThreatLevel() ThreatLevel

type DomainScanStatus 

type DomainScanStatus string

DomainScanStatus represents the status of a domain scan 

const (
	DomainScanStatusCompleted DomainScanStatus = "completed"
	DomainScanStatusError     DomainScanStatus = "error"
)

Domain scan status constants

type EngineResult 

type EngineResult struct {
	Category      string `json:"category"`
	Result        string `json:"result"`
	Method        string `json:"method"`
	EngineVersion string `json:"engine_version"`
	EngineUpdate  string `json:"engine_update"`
}

EngineResult represents the result from a single antivirus engine

type FileCache 

type FileCache struct {
	// contains filtered or unexported fields
}

FileCache implements a file-based cache storage

func NewFileCache 

func NewFileCache(basePath string) (*FileCache, error)

NewFileCache creates a new file-based cache

func (*FileCache) CleanExpiredEntries 

func (c *FileCache) CleanExpiredEntries() error

CleanExpiredEntries removes expired entries from the cache

func (*FileCache) Clear 

func (c *FileCache) Clear() error

Clear removes all values from the file cache

func (*FileCache) Delete 

func (c *FileCache) Delete(key string) error

Delete removes a value from the file cache

func (*FileCache) Get 

func (c *FileCache) Get(key string) ([]byte, bool, error)

Get retrieves a value from the file cache

func (*FileCache) Set 

func (c *FileCache) Set(key string, value []byte, ttl time.Duration) error

Set stores a value in the file cache

type FileInfo 

type FileInfo struct {
	Name         string            `json:"name"`
	Size         int64             `json:"size"`
	Type         string            `json:"type"`
	MD5          string            `json:"md5"`
	SHA1         string            `json:"sha1"`
	SHA256       string            `json:"sha256"`
	LastModified time.Time         `json:"last_modified"`
	Metadata     map[string]string `json:"metadata,omitempty"`
}

FileInfo contains information about a scanned file

func GetFileInfo 

func GetFileInfo(filePath string) (*FileInfo, error)

GetFileInfo retrieves detailed information about a file

type FileScanOptions 

type FileScanOptions struct {
	EnableCache       bool              // Whether to use caching
	SkipEngineDetail  bool              // Skip detailed engine results to reduce response size
	WaitForCompletion bool              // Wait for scan completion (may take time)
	PollingInterval   time.Duration     // Interval for polling scan results
	PollingTimeout    time.Duration     // Maximum time to wait for scan completion
	CustomName        string            // Custom name for the file
	CustomTags        []string          // Custom tags for the file
	ProgressCallback  func(float32)     // Callback for upload progress
	AdditionalParams  map[string]string // Additional API parameters
}

FileScanOptions represents options for file scanning

func DefaultFileScanOptions 

func DefaultFileScanOptions() FileScanOptions

DefaultFileScanOptions returns default options for file scanning

type FileScanResult 

type FileScanResult struct {
	FileInfo      FileInfo                `json:"file_info"`
	ScanID        string                  `json:"scan_id"`
	Status        FileScanStatus          `json:"status"`
	Resource      string                  `json:"resource"`
	Permalink     string                  `json:"permalink"`
	PositiveCount int                     `json:"positive_count"`
	TotalCount    int                     `json:"total_count"`
	ScanDate      time.Time               `json:"scan_date"`
	EngineResults map[string]EngineResult `json:"engine_results"`
	Categories    []string                `json:"categories"`
	Tags          []string                `json:"tags"`
	Error         string                  `json:"error,omitempty"`
}

FileScanResult represents the result of a file scan

func LookupFileByHash 

func LookupFileByHash(fileHash string) (*FileScanResult, error)

LookupFileByHash gets a file analysis report using its hash

func ScanFile 

func ScanFile(filePath string, options ...func(*FileScanOptions)) (*FileScanResult, error)

ScanFile uploads and scans a file with VirusTotal

func (*FileScanResult) GetError 

func (r *FileScanResult) GetError() string
func (r *FileScanResult) GetPermalink() string

func (*FileScanResult) GetResource 

func (r *FileScanResult) GetResource() string

func (*FileScanResult) GetScanDate 

func (r *FileScanResult) GetScanDate() time.Time

func (*FileScanResult) GetStatus 

func (r *FileScanResult) GetStatus() ScanStatus

Implement ScanResult interface for FileScanResult

func (*FileScanResult) GetThreatLevel 

func (r *FileScanResult) GetThreatLevel() ThreatLevel

type FileScanStatus 

type FileScanStatus string

FileScanStatus represents the status of a file scan 

const (
	FileScanStatusQueued     FileScanStatus = "queued"
	FileScanStatusInProgress FileScanStatus = "in_progress"
	FileScanStatusCompleted  FileScanStatus = "completed"
	FileScanStatusError      FileScanStatus = "error"
)

File scan status constants

type IPOptions 

type IPOptions struct {
	EnableCache        bool              // Whether to use caching
	IncludeResolutions bool              // Include DNS resolution history
	IncludeWhois       bool              // Include WHOIS data
	SkipEngineDetail   bool              // Skip detailed engine results
	AdditionalParams   map[string]string // Additional API parameters
}

IPOptions represents options for IP address analysis

func DefaultIPOptions 

func DefaultIPOptions() IPOptions

DefaultIPOptions returns default options for IP analysis

type IPReputationLevel 

type IPReputationLevel string

IPReputationLevel represents an IP's reputation level 

const (
	IPReputationClean     IPReputationLevel = "clean"
	IPReputationLow       IPReputationLevel = "low_risk"
	IPReputationMedium    IPReputationLevel = "medium_risk"
	IPReputationHigh      IPReputationLevel = "high_risk"
	IPReputationMalicious IPReputationLevel = "malicious"
	IPReputationUnknown   IPReputationLevel = "unknown"
)

IP reputation levels

type IPResult 

type IPResult struct {
	IP               string            `json:"ip"`
	Status           IPScanStatus      `json:"status"`
	Resource         string            `json:"resource"`
	Permalink        string            `json:"permalink"`
	ASN              int               `json:"asn"`
	ASOwner          string            `json:"as_owner"`
	Country          string            `json:"country"`
	Continent        string            `json:"continent"`
	Network          string            `json:"network"`
	Categories       map[string]string `json:"categories"`
	Reputation       int               `json:"reputation"`
	ReputationLevel  IPReputationLevel `json:"reputation_level"`
	LastAnalysisDate time.Time         `json:"last_analysis_date"`
	TotalVotes       struct {
		Harmless  int `json:"harmless"`
		Malicious int `json:"malicious"`
	} `json:"total_votes"`
	ResolutionRecords []ResolutionRecord      `json:"resolution_records,omitempty"`
	WhoisInfo         map[string]string       `json:"whois_info,omitempty"`
	EngineResults     map[string]EngineResult `json:"engine_results"`
	Tags              []string                `json:"tags"`
	Error             string                  `json:"error,omitempty"`
}

IPResult represents the result of an IP address analysis

func CheckIPReputation 

func CheckIPReputation(ip string) (*IPResult, error)

CheckIPReputation checks if an IP has known malicious activities

func GetIPLocationInfo 

func GetIPLocationInfo(ip string) (*IPResult, error)

GetIPLocationInfo retrieves geolocation information for an IP

func LookupIP 

func LookupIP(ip string, options ...func(*IPOptions)) (*IPResult, error)

LookupIP retrieves information about an IP address from VirusTotal

func (*IPResult) GetError 

func (r *IPResult) GetError() string
func (r *IPResult) GetPermalink() string

func (*IPResult) GetResource 

func (r *IPResult) GetResource() string

func (*IPResult) GetScanDate 

func (r *IPResult) GetScanDate() time.Time

func (*IPResult) GetStatus 

func (r *IPResult) GetStatus() ScanStatus

Implement ScanResult interface for IPResult

func (*IPResult) GetThreatLevel 

func (r *IPResult) GetThreatLevel() ThreatLevel

type IPScanStatus 

type IPScanStatus string

IPScanStatus represents the status of an IP scan 

const (
	IPScanStatusCompleted IPScanStatus = "completed"
	IPScanStatusError     IPScanStatus = "error"
)

IP scan status constants

type MemoryCache 

type MemoryCache struct {
	// contains filtered or unexported fields
}

MemoryCache implements an in-memory cache storage

func NewMemoryCache 

func NewMemoryCache() *MemoryCache

NewMemoryCache creates a new in-memory cache

func (*MemoryCache) Clear 

func (c *MemoryCache) Clear() error

Clear removes all values from the memory cache

func (*MemoryCache) Delete 

func (c *MemoryCache) Delete(key string) error

Delete removes a value from the memory cache

func (*MemoryCache) Get 

func (c *MemoryCache) Get(key string) ([]byte, bool, error)

Get retrieves a value from the memory cache

func (*MemoryCache) Set 

func (c *MemoryCache) Set(key string, value []byte, ttl time.Duration) error

Set stores a value in the memory cache

type ResolutionRecord 

type ResolutionRecord struct {
	Type  string    `json:"type"`
	Value string    `json:"value"`
	Date  time.Time `json:"date"`
	TTL   int       `json:"ttl,omitempty"`
}

ResolutionRecord represents a domain resolution record

type Result 

type Result struct {
	Data      interface{} // The result data
	Timestamp time.Time   // When the result was obtained
}

Result represents a cached scan result

type ScanResult 

type ScanResult interface {
	// GetStatus returns the status of the scan
	GetStatus() ScanStatus

	// GetPermalink returns a permanent link to the analysis on VirusTotal
	GetPermalink() string

	// GetResource returns the resource identifier (hash, URL, domain, IP)
	GetResource() string

	// GetThreatLevel returns a standardized threat level assessment
	GetThreatLevel() ThreatLevel

	// GetScanDate returns the date of the analysis
	GetScanDate() time.Time

	// GetError returns any error that occurred during analysis
	GetError() string
}

ScanResult is an interface implemented by all scan result types

type ScanResultSummary 

type ScanResultSummary struct {
	Resource    string      `json:"resource"`
	Type        string      `json:"type"`
	ThreatLevel ThreatLevel `json:"threat_level"`
	ThreatName  string      `json:"threat_name"`
	ScanDate    time.Time   `json:"scan_date"`
	Permalink   string      `json:"permalink"`
}

ScanResultSummary provides a common structure for summarizing scan results

func GetScanResultSummary 

func GetScanResultSummary(result ScanResult) ScanResultSummary

GetScanResultSummary returns a standardized summary from any scan result

type ScanStatus 

type ScanStatus string

ScanStatus represents the status of any kind of scan 

const (
	ScanStatusQueued     ScanStatus = "queued"
	ScanStatusInProgress ScanStatus = "in_progress"
	ScanStatusCompleted  ScanStatus = "completed"
	ScanStatusError      ScanStatus = "error"
)

Common scan status constants

type ThreatLevel 

type ThreatLevel int

ThreatLevel represents a standardized threat severity 

const (
	ThreatLevelClean    ThreatLevel = 0
	ThreatLevelLow      ThreatLevel = 1
	ThreatLevelMedium   ThreatLevel = 2
	ThreatLevelHigh     ThreatLevel = 3
	ThreatLevelCritical ThreatLevel = 4
	ThreatLevelUnknown  ThreatLevel = -1
)

Threat level constants

func ThreatLevelFromString 

func ThreatLevelFromString(level string) ThreatLevel

ThreatLevelFromString converts a string to its threat level

type URLInfo 

type URLInfo struct {
	Original    string            `json:"original"`
	Normalized  string            `json:"normalized"`
	Hostname    string            `json:"hostname"`
	Path        string            `json:"path"`
	Scheme      string            `json:"scheme"`
	QueryString string            `json:"query_string,omitempty"`
	Fragment    string            `json:"fragment,omitempty"`
	Parameters  map[string]string `json:"parameters,omitempty"`
}

URLInfo contains normalized information about a URL

type URLScanOptions 

type URLScanOptions struct {
	EnableCache       bool              // Whether to use caching
	SkipEngineDetail  bool              // Skip detailed engine results to reduce response size
	WaitForCompletion bool              // Wait for scan completion (may take time)
	PollingInterval   time.Duration     // Interval for polling scan results
	PollingTimeout    time.Duration     // Maximum time to wait for scan completion
	CustomTags        []string          // Custom tags for the scan
	AdditionalParams  map[string]string // Additional API parameters
}

URLScanOptions represents options for URL scanning

func DefaultURLScanOptions 

func DefaultURLScanOptions() URLScanOptions

DefaultURLScanOptions returns default options for URL scanning

type URLScanResult 

type URLScanResult struct {
	URL              string                  `json:"url"`
	ScanID           string                  `json:"scan_id"`
	Status           URLScanStatus           `json:"status"`
	Resource         string                  `json:"resource"`
	Permalink        string                  `json:"permalink"`
	PositiveCount    int                     `json:"positive_count"`
	TotalCount       int                     `json:"total_count"`
	ScanDate         time.Time               `json:"scan_date"`
	Categories       []string                `json:"categories"`
	Tags             []string                `json:"tags"`
	FinalURL         string                  `json:"final_url,omitempty"`
	Title            string                  `json:"title,omitempty"`
	EngineResults    map[string]EngineResult `json:"engine_results"`
	Error            string                  `json:"error,omitempty"`
	HttpStatus       int                     `json:"http_status,omitempty"`
	RedirectionChain []string                `json:"redirection_chain,omitempty"`
}

URLScanResult represents the result of a URL scan

func LookupURL 

func LookupURL(targetURL string) (*URLScanResult, error)

LookupURL gets the latest analysis of a URL

func ScanURL 

func ScanURL(targetURL string, options ...func(*URLScanOptions)) (*URLScanResult, error)

ScanURL submits a URL for scanning by VirusTotal

func (*URLScanResult) GetError 

func (r *URLScanResult) GetError() string
func (r *URLScanResult) GetPermalink() string

func (*URLScanResult) GetResource 

func (r *URLScanResult) GetResource() string

func (*URLScanResult) GetScanDate 

func (r *URLScanResult) GetScanDate() time.Time

func (*URLScanResult) GetStatus 

func (r *URLScanResult) GetStatus() ScanStatus

Implement ScanResult interface for URLScanResult

func (*URLScanResult) GetThreatLevel 

func (r *URLScanResult) GetThreatLevel() ThreatLevel

type URLScanStatus 

type URLScanStatus string

URLScanStatus represents the status of a URL scan 

const (
	URLScanStatusQueued     URLScanStatus = "queued"
	URLScanStatusInProgress URLScanStatus = "in_progress"
	URLScanStatusCompleted  URLScanStatus = "completed"
	URLScanStatusError      URLScanStatus = "error"
)

URL scan status constants

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.