govt

package module
v0.0.0-...-3ca547f Latest Latest
Warning

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

 Go to latest Published: Apr 15, 2019 License: Apache-2.0 Imports: 16 Imported by: 18

README

govt - VirusTotal API for Go

govt is a go module to use the API of VirusTotal.com.

Implemented Features

Resource Description VT API govt support
POST /vtapi/v2/file/scan Upload a file for scanning with VirusTotal. public true
GET /vtapi/v2/file/scan/upload_url Get a special URL to upload files bigger than 32MB in size. private false
POST /vtapi/v2/file/rescan Rescan a previously submitted file or schedule a scan to be performed in the future. public true
POST /vtapi/v2/file/rescan/delete Delete a previously scheduled scan. private false
GET /vtapi/v2/file/report Get the scan results for a file. public true
GET /vtapi/v2/file/behaviour Get a report about the behaviour of the file when executed in a sandboxed environment. private true
GET /vtapi/v2/file/network-traffic Get a dump of the network traffic generated by the file when executed. private true
GET /vtapi/v2/file/search Search for samples that match certain binary/metadata/detection criteria. private true
GET /vtapi/v2/file/clusters List file similarity clusters for a given time frame. private false
GET /vtapi/v2/file/distribution Get a live feed with the lastest files submitted to VirusTotal. private true
GET /vtapi/v2/file/download Download a file by its hash. private true
GET /vtapi/v2/file/false-positives Consume file false positives from your notifications pipe. private false
POST /vtapi/v2/url/scan Submmit a URL for scanning with VirusTotal. public true
GET /vtapi/v2/url/report Get the scan results for a given URL. public true
GET /vtapi/v2/url/distribution Get a live feed with the lastest URLs submitted to VirusTotal. private false
GET /vtapi/v2/ip-address/report Get information about a given IP address. public true
GET /vtapi/v2/domain/report Get information about a given domain. public true
POST /vtapi/v2/comments/put Post a comment on a file or URL. public true
GET /vtapi/v2/comments/get Get comments for a file or URL. private true

Missing Features

  • all of the above with a false in the govt support column.
  • at least for testing the VT apikey has currently be put into the source (get the apikey from a file or an environment variable would be better)
  • more and better testing

Install

If you have a go workplace setup and working you can simply do:

go get github.com/williballenthin/govt

go install github.com/williballenthin/govt

Usage

In order how to use the govt module please have a look at the SampleClients directory and it's content.

You need to have an VirusTotal API Key. You can register for an account at VirusTotal in order to get an public API key. There are also private API keys available, for those you have to be accepted by VirusTotal and you need to pay for. Depending on your API Key and the access level granted you can use all of the above functions, all but the ones reserved for AV companies, or just the public ones (if you have a free publich API key).

Check out the README.md file in the SampleClients directory to find out how to set-up your API key in order to use the provided Example programs.

Authors

govt was initially written by Willi Ballenthin. Later improved and new features added by Christopher 'tankbusta' Schmitt and Florian 'scusi' Walther

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.

Index

Constants

View Source 
const (
	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 APICall 

type APICall struct {
	FunctionName string     `json:"api"`
	Category     string     `json:"category"`
	Status       string     `json:"status"`
	Return       string     `json:"return"`
	Timestamp    string     `json:"timestamp"`
	Repeated     int        `json:"repeated"`
	Arguments    []Argument `json:"arguments"`
}

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 Argument 

type Argument struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

type AutoStartEntry 

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

type Behaviour 

type Behaviour struct {
	Processes   []Process          `json:"processes"`
	ProcessTree []ProcessTreeEntry `json:"processtree"`
	Summary     BehaviourSummary   `json:"Summary"`
}

type BehaviourSummary 

type BehaviourSummary struct {
	Files   []string `json:"files"`
	Keys    []string `json:"keys"`
	Mutexes []string `json:"mutexes"`
}

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) GetFileBehaviour 

func (client *Client) GetFileBehaviour(hash string) (r *FileBehaviourResult, err error)

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 url.

func (*Client) ScanUrls 

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

ScanUrls asks VT to redo analysis on the specified urls. Up to 25 urls.

func (*Client) SearchFile 

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

SearchFile(query, offset) - searches VT Inteligence 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 DNSEvent 

type DNSEvent struct {
	IP       string `json:"ip"`
	Hostname string `json:"hostname"`
}

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 FileBehaviourResult 

type FileBehaviourResult struct {
	Status
	Info        ReportInfo  `json:"info"`
	Behaviour   Behaviour   `json:"behavior"`
	NetworkInfo NetworkInfo `json:"network"`
	Syscalls    []Syscall   `json:"syscalls"`
}

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 HTTPEvent 

type HTTPEvent struct {
	Body    string `json:"body"`
	URI     string `json:"uri"`
	Method  string `json:"method"`
	Host    string `json:"host"`
	Version string `json:"version"`
	Path    string `json:"path"`
	Data    string `json:"data"`
	Port    int    `json:"port"`
}

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 NetworkInfo 

type NetworkInfo struct {
	HTTP  []HTTPEvent `json:"http"`
	TCP   []TCPEvent  `json:"tcp"`
	UDP   []UDPEvent  `json:"udp"`
	DNS   []DNSEvent  `json:"dns"`
	Hosts []string    `json:"hosts"`
}

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 Process 

type Process struct {
	Name      string    `json:"process_name"`
	ID        string    `json:"process_id"`
	ParentID  string    `json:"parent_id"`
	FirstSeen string    `json:"first_seen"`
	APICalls  []APICall `json:"calls"`
}

type ProcessTreeEntry 

type ProcessTreeEntry struct {
	ID       int                `json:"pid"`
	Name     string             `json:"name"`
	Children []ProcessTreeEntry `json:"children"`
}

type ReportInfo 

type ReportInfo struct {
	Started  string `json:"started"`
	Ended    string `json:"ended"`
	Duration string `json:"duration"`
	Version  string `json:"version"`
}

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 Syscall 

type Syscall struct {
	Command       string `json:"cmd"`
	PID           int    `json:"pid"`
	PPID          int    `json:"ppid"`
	WallTimestamp int64  `json:"walltimestamp"`
	FD            string `json:"fd"`
	Path          string `json:"path"`
	CWD           string `json:"cwd"`
	ExecName      string `json:"execname"`
}

type TCPEvent 

type TCPEvent struct {
	SrcIP   string `json:"src"`
	SrcPort int    `json:"sport"`

	DstIP   string `json:"dst"`
	DstPort int    `json:"dport"`
}

type TrustedVerdictResult 

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

type UDPEvent 

type UDPEvent struct {
	SrcIP   string `json:"src"`
	SrcPort int    `json:"sport"`

	DstIP   string `json:"dst"`
	DstPort int    `json:"dport"`
}

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

View all Source files

Directories

Path Synopsis
SampleClients
domainreport
vtDomainReport.go - fetches and shows a VirusTotal Domain Report.
 vtDomainReport.go - fetches and shows a VirusTotal Domain Report.
filebehaviour
vtFileBehaviour - fetches a Cuckoo behaviour report from VirusTotal for the given resource.
 vtFileBehaviour - fetches a Cuckoo behaviour report from VirusTotal for the given resource.
filecheck
vtFileCheck.go - checks if VirusTotal knows a given file.
 vtFileCheck.go - checks if VirusTotal knows a given file.
filedownload
vtFileDownload - fetches a sample from VirusTotal for the given resource.
 vtFileDownload - fetches a sample from VirusTotal for the given resource.
fileknownbysymantec
vtFileKnownBySymantec.go - checks via VirusTotal if a given file is detected by Symantec AV.
 vtFileKnownBySymantec.go - checks via VirusTotal if a given file is detected by Symantec AV.
filenetworktraffic
vtFileNetworkTraffic - fetches a pcap file from VirusTotal for the given resource.
 vtFileNetworkTraffic - fetches a pcap file from VirusTotal for the given resource.
filereport
vtFileReport - fetches a report from VirusTotal for the given resource.
 vtFileReport - fetches a report from VirusTotal for the given resource.
filerescan
vtFileRescan - asks VirusTotal to rescan a given resource.
 vtFileRescan - asks VirusTotal to rescan a given resource.
filescan
vtFileScan - request VirusTotal to scan a given file.
 vtFileScan - request VirusTotal to scan a given file.
filesearch
vtFileSearch - shows how to use VT Intelligence to search for files that match certain criteria.
 vtFileSearch - shows how to use VT Intelligence to search for files that match certain criteria.
ipreport
vtIpReport - fetches information about a given IP from VirusTotal.
 vtIpReport - fetches information about a given IP from VirusTotal.
urlreport
vtUrlReport - fetches a report for a given URL from VirusTotal vtUrlReport -url=http://www.heise.de/
 vtUrlReport - fetches a report for a given URL from VirusTotal vtUrlReport -url=http://www.heise.de/
urlscan
vtUrlScan - Requests VirusTotal to scan a given URL vtUrlScan -url=http://www.virustotal.com/
 vtUrlScan - Requests VirusTotal to scan a given URL vtUrlScan -url=http://www.virustotal.com/

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.