govt

package
Version: v0.0.0-...-295d2dc Latest Latest
Warning

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

Go to latest
Published: Oct 17, 2019 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package govt is a VirusTotal API v2 client written for the Go programming language.

Written by Willi Ballenthin while at Mandiant. June, 2013.

File upload capabilities by Florian 'scusi' Walther June, 2014.

File distribution support by Christopher 'tankbusta' Schmitt while at Mandiant October, 2014.

File updated and patched by M. Moldabek, 2017.

Index

Constants

View Source
const (
	// Fallback VT API URL
	DefaultURL = "https://www.virustotal.com/vtapi/v2/"
)

Variables

This section is empty.

Functions

func SetErrorLog

func SetErrorLog(logger *log.Logger) func(*Client) error

SetErrorLog sets the logger for critical messages. It is nil by default.

func SetTraceLog

func SetTraceLog(logger *log.Logger) func(*Client) error

SetTraceLog specifies the logger to use for output of trace messages like HTTP requests and responses. It is nil by default.

Types

type AdditionnalInfoResult

type AdditionnalInfoResult struct {
	Magic            string               `json:"magic"`
	Signature        SigCheck             `json:"sigcheck"`
	PEImpHash        string               `json:"pe-imphash"`
	PETimeStamp      int                  `json:"pe-timestamp"`
	PEResourceList   map[string]string    `json:"pe-resource-list"`
	PEResourceLangs  map[string]int       `json:"pe-resource-langs"`
	PEResourceTypes  map[string]int       `json:"pe-resource-types"`
	PEResourceDetail []PEResource         `json:"pe-resource-detail"`
	PEMachineType    int                  `json:"pe-machine-type"`
	PEEntryPoint     int                  `json:"pe-entry-point"`
	AutoStart        []AutoStartEntry     `json:"autostart"`
	Imports          map[string][]string  `json:"imports"`
	TrustedVerdict   TrustedVerdictResult `json:"trusted_verdict"`
}

type AutoStartEntry

type AutoStartEntry struct {
	Entry    string `json:"entry"`
	Location string `json:"location"`
}

type Client

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

Client interacts with the services provided by VirusTotal.

func New

func New(options ...OptionFunc) (*Client, error)

New creates a new virustotal client.

The caller can configure the new client by passing configuration options to the func.

Example:

client, err := govt.New(
  govt.SetUrl("http://some.url.com:port"),
  govt.SetErrorLog(log.New(os.Stderr, "VT: ", log.Lshortfile))

If no URL is configured, Client uses DefaultURL by default.

If no HttpClient is configured, then http.DefaultClient is used. You can use your own http.Client with some http.Transport for advanced scenarios.

An error is also returned when some configuration option is invalid.

func (*Client) GetComments

func (client *Client) GetComments(resource string) (r *CommentReport, err error)

GetComments gets comments for file/URL/IP/domain.

func (*Client) GetDetailedFileReport

func (client *Client) GetDetailedFileReport(md5 string) (r *DetailedFileReport, err error)

GetDetailedFileReport fetches the AV scan reports tracked by VT given an MD5 hash value. This API is part of the VTI Private API, requiring a licenced API key

func (*Client) GetDomainReport

func (client *Client) GetDomainReport(domain string) (r *DomainReport, err error)

GetDomainReport fetches the passive DNS information about a DNS address.

func (*Client) GetFile

func (client *Client) GetFile(hash string) (r *FileDownloadResult, err error)

GetFile fetches a file from VT that matches a given md5/sha1/sha256 sum

func (*Client) GetFileDistribution

func (client *Client) GetFileDistribution(params *Parameters) (r *FileDistributionResults, err error)

GetFileDistribution fetches files from the VT distribution API

func (*Client) GetFileFeed

func (client *Client) GetFileFeed(packageRange string) ([]FileFeed, error)

GetFileFeed fetches files from the VT feed API

func (*Client) GetFileNetworkTraffic

func (client *Client) GetFileNetworkTraffic(hash string) (r *FileDownloadResult, err error)

func (*Client) GetFileReport

func (client *Client) GetFileReport(md5 string) (r *FileReport, err error)

GetFileReport fetches the AV scan reports tracked by VT given an MD5 hash value.

func (*Client) GetFileReports

func (client *Client) GetFileReports(md5s []string) (r *FileReportResults, err error)

GetFileReports fetches the AV scan reports tracked by VT given set of MD5 hash values.

func (*Client) GetIpReport

func (client *Client) GetIpReport(ip string) (r *IpReport, err error)

GetIpReport fetches the passive DNS information about an IP address.

func (*Client) GetUrlReport

func (client *Client) GetUrlReport(url string) (r *UrlReport, err error)

GetUrlReport fetches the AV scan reports tracked by VT given a URL. Does not support the optional `scan` parameter.

func (*Client) GetUrlReports

func (client *Client) GetUrlReports(urls []string) (r *UrlReports, err error)

GetUrlReports fetches AV scan reports tracked by VT given URLs. Does not support the optional `scan` parameter.

func (*Client) MakeAPIGetRequest

func (client *Client) MakeAPIGetRequest(fullurl string, parameters Parameters) (resp *http.Response, err error)

MakeAPIGetRequest fetches a URL with querystring via HTTP GET and

returns the response if the status code is HTTP 200

`parameters` should not include the apikey. The caller must call `resp.Body.Close()`.

func (*Client) MakeComment

func (client *Client) MakeComment(resource string, comment string) (r *Status, err error)

MakeComment adds a comment to a file/URL/IP/domain.

func (*Client) RescanFile

func (client *Client) RescanFile(md5 string) (r *RescanFileResult, err error)

RescanFile asks VT to redo analysis on the specified file.

func (*Client) RescanFiles

func (client *Client) RescanFiles(md5s []string) (r *RescanFileResults, err error)

RescanFiles asks VT to redo analysis on the specified files.

func (*Client) ScanFile

func (client *Client) ScanFile(file string) (r *ScanFileResult, err error)

ScanFile asks VT to analysis on the specified file, thats also uploaded.

func (*Client) ScanUrl

func (client *Client) ScanUrl(url string) (r *ScanUrlResult, err error)

ScanUrl asks VT to redo analysis on the specified file.

func (*Client) ScanUrls

func (client *Client) ScanUrls(urls []string) (r *ScanUrlResults, err error)

ScanUrls asks VT to redo analysis on the specified files.

func (*Client) SearchFile

func (client *Client) SearchFile(query, offset string) (r *FileSearchResult, err error)

SearchFile(query, offset) - searches VT Intelligence for files that meet the given search criteria It returns a list of hashes of files that matched the search criteria. See the following URL for possible search operators: https://www.virustotal.com/intelligence/help/file-search/#search-operators This functionality is part of the VT PrivateAPI.

type ClientError

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

ClientError is a generic error specific to the `govt` package.

func (ClientError) Error

func (client ClientError) Error() string

Error returns a string representation of the error condition.

type Comment

type Comment struct {
	Date    string `json:"date"`
	Comment string `json:"comment"`
}

Comment is defined by VT

type CommentReport

type CommentReport struct {
	Status
	Resource string    `json:"resource"`
	Comments []Comment `json:"comments"`
}

CommentReport is defined by VT.

type DetailedFileReport

type DetailedFileReport struct {
	FileReportDistrib
	Tags                []string              `json:"tags"`
	UniqueSources       uint16                `json:"unique_sources"`
	TimesSubmitted      uint16                `json:"times_submitted"`
	HarmlessVotes       uint16                `json:"harmless_votes"`
	MaliciousVotes      uint16                `json:"malicious_votes"`
	CommunityReputation int                   `json:"community_reputation"`
	AdditionnalInfo     AdditionnalInfoResult `json:"additional_info"`
	IntoTheWildURLs     []string              `json:"ITW_urls"`
	SubmissionNames     []string              `json:"submission_names"`
	Ssdeep              string                `json:"ssdeep"`
}

type DetectedUrl

type DetectedUrl struct {
	Url       string `json:"url"`
	Total     uint16 `json:"total"`
	Positives uint16 `json:"positives"`
	ScanDate  string `json:"scan_date"`
}

DetectedUrl is defined by VT.

type DomainReport

type DomainReport struct {
	Status
	Resolutions  []DomainResolution
	DetectedUrls []DetectedUrl `json:"detected_urls"`
}

DomainReport is defined by VT.

type DomainResolution

type DomainResolution struct {
	LastResolved string `json:"last_resolved"`
	IpAddress    string `json:"ip_address"`
}

DomainResolution is defined by VT.

type FileDistributionResults

type FileDistributionResults []FileReportDistrib

type FileDownloadResult

type FileDownloadResult struct {
	Content []byte
}

FileDownloadResult

type FileFeed

type FileFeed struct {
	Vhash               string        `json:"vhash"`
	SubmissionNames     []string      `json:"submission_names"`
	ScanDate            string        `json:"scan_date"`
	FirstSeen           string        `json:"first_seen"`
	TimesSubmitted      int           `json:"times_submitted"`
	Size                int           `json:"size"`
	ScanID              string        `json:"scan_id"`
	Total               int           `json:"total"`
	HarmlessVotes       int           `json:"harmless_votes"`
	VerboseMsg          string        `json:"verbose_msg"`
	Sha256              string        `json:"sha256"`
	Type                string        `json:"type"`
	Link                string        `json:"link"`
	Positives           int           `json:"positives"`
	Ssdeep              string        `json:"ssdeep"`
	Md5                 string        `json:"md5"`
	Permalink           string        `json:"permalink"`
	Sha1                string        `json:"sha1"`
	ResponseCode        int           `json:"response_code"`
	CommunityReputation int           `json:"community_reputation"`
	MaliciousVotes      int           `json:"malicious_votes"`
	ITWUrls             []interface{} `json:"ITW_urls"`
	LastSeen            string        `json:"last_seen"`
}

FileFeed high level elements of the file feed API As much more data but kept simple for brevity

type FileReport

type FileReport struct {
	Status
	Resource  string              `json:"resource"`
	ScanId    string              `json:"scan_id"`
	Md5       string              `json:"md5"`
	Sha1      string              `json:"sha1"`
	Sha256    string              `json:"sha256"`
	ScanDate  string              `json:"scan_date"`
	Positives uint16              `json:"positives"`
	Total     uint16              `json:"total"`
	Scans     map[string]FileScan `json:"scans"`
	Permalink string              `json:"permalink"`
}

FileReport is defined by VT.

type FileReportDistrib

type FileReportDistrib struct {
	Status
	Md5           string `json:"md5"`
	Sha1          string `json:"sha1"`
	Sha256        string `json:"sha256"`
	Type          string `json:"type"`
	FirstSeen     string `json:"first_seen"`
	LastSeen      string `json:"last_seen"`
	Link          string `json:"link"`
	Name          string `json:"name"`
	Size          int    `json:"size"`
	SourceCountry string `json:"source_country"`
	SourceId      string `json:"source_id"`
	Timestamp     int    `json:"timestamp"`
	VHash         string `json:"vhash"`
	// Ugh. VT inconsistency. Data is an array rather than k/v like other APIs
	Scans map[string][]string `json:"report"`
}

type FileReportResults

type FileReportResults []FileReport

FileReportResults is defined by VT.

type FileScan

type FileScan struct {
	Detected bool   `json:"detected"`
	Version  string `json:"version"`
	Result   string `json:"result"`
	Update   string `json:"update"`
}

FileScan is defined by VT.

type FileSearchResult

type FileSearchResult struct {
	ResponseCode int      `json:"response_code"`
	Offset       string   `json:"offset"`
	Hashes       []string `json:"hashes"`
}

File Search Result

type IpReport

type IpReport struct {
	Status
	Resolutions  []IpResolution
	DetectedUrls []DetectedUrl `json:"detected_urls"`
}

IpReport is defined by VT.

type IpResolution

type IpResolution struct {
	LastResolved string `json:"last_resolved"`
	Hostname     string `json:"hostname"`
}

IpResolution is defined by VT.

type OptionFunc

type OptionFunc func(*Client) error

OptionFunc is a function that configures a Client. It is used in New

func SetApikey

func SetApikey(apikey string) OptionFunc

SetApikey sets the VT API key to use

func SetBasicAuth

func SetBasicAuth(username, password string) OptionFunc

SetBasicAuth allows to set proxy credentials

func SetHttpClient

func SetHttpClient(httpClient *http.Client) OptionFunc

SetHttpClient can be used to specify the http.Client to use when making HTTP requests to VT.

func SetUrl

func SetUrl(rawurl string) OptionFunc

SetUrl defines the URL endpoint VT

type PEResource

type PEResource struct {
	Lang     string `json:"lang"`
	FileType string `json:"filetype"`
	Sha256   string `json:"sha256"`
	Type     string `json:"type"`
}

type Parameters

type Parameters map[string]string

Parameters for the HTTP requests

type RescanFileResult

type RescanFileResult struct {
	Status
	Resource  string `json:"resource"`
	ScanId    string `json:"scan_id"`
	Permalink string `json:"permalink"`
	Sha256    string `json:"sha256"`
}

RescanFileResult is defined by VT.

type RescanFileResults

type RescanFileResults []RescanFileResult

RescanFileResults is defined by VT.

type ScanFileResult

type ScanFileResult struct {
	Status
	Resource  string `json:"resource"`
	ScanId    string `json:"scan_id"`
	Permalink string `json:"permalink"`
	Sha256    string `json:"sha256"`
	Sha1      string `json:"sha1"`
	Md5       string `json:"md5"`
}

ScanFileResult is defined by VT.

type ScanUrlResult

type ScanUrlResult struct {
	Status
	ScanId    string `json:"scan_id"`
	ScanDate  string `json:"scan_date"`
	Permalink string `json:"permalink"`
	Url       string `json:"url"`
}

ScanUrlResult is defined by VT.

type ScanUrlResults

type ScanUrlResults []ScanUrlResult

ScanUrlResults is defined by VT.

type SigCheck

type SigCheck struct {
	SignersDetails []SignerDetail `json:"signers details"`
	Verified       string         `json:"verified"`
	Publisher      string         `json:"publisher"`
	Product        string         `json:"product"`
	Description    string         `json:"description"`
	SigningDate    string         `json:"signing date"`
}

type SignerDetail

type SignerDetail struct {
	Status       string `json:"status"`
	Name         string `json:"name"`
	Thumbprint   string `json:"thumbprint"`
	SerialNumber string `json:"serial number"`
	ValidFrom    string `json:"valid from"`
	ValidTo      string `json:"valid to"`
}

type Status

type Status struct {
	ResponseCode int    `json:"response_code"`
	VerboseMsg   string `json:"verbose_msg"`
}

Status is the set of fields shared among all VT responses.

type TrustedVerdictResult

type TrustedVerdictResult struct {
	Organization string `json:"organization"`
	Verdict      string `json:"verdict"`
	Filename     string `json:"filename"`
}

type UrlReport

type UrlReport struct {
	Status
	Url        string             `json:"url"`
	Resource   string             `json:"resource"`
	ScanId     string             `json:"scan_id"`
	ScanDate   string             `json:"scan_date"`
	Permalink  string             `json:"permalink"`
	Positives  uint16             `json:"positives"`
	Total      uint16             `json:"total"`
	Scans      map[string]UrlScan `json:"scans"`
	FileScanId string             `json:"filescan_id"`
}

UrlReport is defined by VT.

type UrlReports

type UrlReports []UrlReport

UrlReports is defined by VT.

type UrlScan

type UrlScan struct {
	Detected bool   `json:"detected"`
	Result   string `json:"result"`
}

UrlScan is defined by VT.

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL