gdetect

Documentation

Overview

Package gdetect provides implements utility functions to interact with GLIMPS' detect API.

The gdetect package should only be used to interact with detect API. Package path implements utility routines for manipulating slash-separated paths.

Index

• Variables
• type AvResult
• type Client
  • func NewClient(endpoint, token string, insecure bool, httpClient *http.Client) (client *Client, err error)
  • func (c *Client) ExtractExpertViewURL(result *Result) (urlExpertView string, err error)
  • func (c *Client) ExtractTokenViewURL(result *Result) (urlTokenView string, err error)
  • func (c *Client) GetAPIVersion(ctx context.Context) (version string, err error)
  • func (c *Client) GetFullSubmissionByUUID(ctx context.Context, uuid string) (result interface{}, err error)
  • func (c *Client) GetProfileStatus(ctx context.Context) (status ProfileStatus, err error)
  • func (c *Client) GetResultBySHA256(ctx context.Context, sha256 string) (result Result, err error)
  • func (c *Client) GetResultByUUID(ctx context.Context, uuid string) (result Result, err error)
  • func (c *Client) GetResults(ctx context.Context, from int, size int, tags ...string) (submissions []Submission, err error)
  • func (c *Client) SetSyndetect()
  • func (c *Client) SubmitFile(ctx context.Context, filepath string, submitOptions SubmitOptions) (uuid string, err error)
  • func (c *Client) SubmitReader(ctx context.Context, r io.Reader, submitOptions SubmitOptions) (uuid string, err error)
  • func (c *Client) WaitForFile(ctx context.Context, filepath string, waitOptions WaitForOptions) (result Result, err error)
  • func (c *Client) WaitForReader(ctx context.Context, r io.Reader, waitOptions WaitForOptions) (result Result, err error)
• type ExtendedGDetectSubmitter
• type FeatureNotAvailableError
  • func (e FeatureNotAvailableError) Error() string
• type FileResult
• type GDetectSubmitter
• type HTTPError
  • func NewHTTPError(r *http.Response, body string) HTTPError
  • func (e HTTPError) Error() string
• type ProfileStatus
• type Result
• type Submission
• type SubmitOptions
• type Tag
• type Threat
• type WaitForOptions

Examples

• Client.SubmitFile

Variables

var (
	ErrTimeout      = fmt.Errorf("timeout")
	ErrBadToken     = fmt.Errorf("bad token")
	ErrNoToken      = fmt.Errorf("no token in result")
	ErrNoSID        = fmt.Errorf("no sid in result")
	ErrNotAvailable = fmt.Errorf("this feature is not available")
)

Generic gdetect client errors.

var (
	DetectPaths = map[string]string{
		"results": "/api/lite/v2/results/",
		"search":  "/api/lite/v2/search/",
		"submit":  "/api/lite/v2/submit",
	}
	SyndetectPaths = map[string]string{
		"results": "/api/v1/results/",
		"search":  "/api/v1/results/",
		"submit":  "/api/v1/submit",
	}
)

var DefaultTimeout = time.Minute * 5

DefaultTimeout is the default timeout for gdetect client

var Logger = slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelWarn}))

Types

type AvResult

type AvResult struct {
	AVName string `json:"av"`
	Result string `json:"result"`
	Score  int    `json:"score"`
}

AvResult represents antivirus results from an analysis result

type Client

type Client struct {
	Endpoint   string
	Token      string
	HttpClient *http.Client
	// contains filtered or unexported fields
}

Client is the representation of a Detect API CLient.

func NewClient

func NewClient(endpoint, token string, insecure bool, httpClient *http.Client) (client *Client, err error)

NewClient returns a fresh client, given endpoint token and insecure params. The returned client could be used to perform operations on gdetect.

If Client is well-formed, it returns error == nil. If error != nil, that could mean that Token is invalid (by its length for example).

func (*Client) ExtractExpertViewURL

func (c *Client) ExtractExpertViewURL(result *Result) (urlExpertView string, err error)

ExtractExpertViewURL extracts URL analysis expert view from given result, use client to retrieve API base endpoint

func (*Client) ExtractTokenViewURL

func (c *Client) ExtractTokenViewURL(result *Result) (urlTokenView string, err error)

ExtractTokenViewURL extracts URL token view from given result, use client to retrieve API base endpoint

func (*Client) GetAPIVersion

func (c *Client) GetAPIVersion(ctx context.Context) (version string, err error)

GetAPIVersion retrieves detect API version

func (*Client) GetFullSubmissionByUUID

func (c *Client) GetFullSubmissionByUUID(ctx context.Context, uuid string) (result interface{}, err error)

GetFullSubmissionByUUID retrieves full submission using results full endpoint on Detect API with given UUID.

func (*Client) GetProfileStatus

func (c *Client) GetProfileStatus(ctx context.Context) (status ProfileStatus, err error)

func (*Client) GetResultBySHA256

func (c *Client) GetResultBySHA256(ctx context.Context, sha256 string) (result Result, err error)

GetResultBySHA256 search for an analysis using search endpoint on Detect API with given file SHA256.

func (*Client) GetResultByUUID

func (c *Client) GetResultByUUID(ctx context.Context, uuid string) (result Result, err error)

GetResultByUUID retrieves result using results endpoint on Detect API with given UUID.

func (*Client) GetResults

func (c *Client) GetResults(ctx context.Context, from int, size int, tags ...string) (submissions []Submission, err error)

func (*Client) SetSyndetect

func (c *Client) SetSyndetect()

func (*Client) SubmitFile

func (c *Client) SubmitFile(ctx context.Context, filepath string, submitOptions SubmitOptions) (uuid string, err error)

SubmitFile submits a file to Detect API. The file is described by its path and it's possible to provides some params to be submitted with the file.

Example

// example mock up
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusUnauthorized)
	w.Header().Add("Content-Type", "application/json")
	w.Write([]byte(`{"status":false,"error":"unauthorized"}`))
}))

defer srv.Close()

client, err := NewClient(srv.URL, "2b886d5f-aa81d629-4299e60b-41b728ba-9bcbbc00", false, nil)
if err != nil {
	fmt.Println(err)
}

result, err := client.SubmitFile(context.Background(), "/bin/sh", SubmitOptions{
	Tags:        []string{"test"},
	Description: "test submission",
	BypassCache: false,
})
if err != nil {
	fmt.Println(err)
} else {
	fmt.Println(result)
}

Output:

invalid response from endpoint, 401 Unauthorized: {"status":false,"error":"unauthorized"}

func (*Client) SubmitReader

func (c *Client) SubmitReader(ctx context.Context, r io.Reader, submitOptions SubmitOptions) (uuid string, err error)

SubmitReader submits a file to Detect API.

func (*Client) WaitForFile

func (c *Client) WaitForFile(ctx context.Context, filepath string, waitOptions WaitForOptions) (result Result, err error)

WaitForFile submits a file, using SubmitFile method, and try to get analysis results using GetResultByUUID method.

func (*Client) WaitForReader

func (c *Client) WaitForReader(ctx context.Context, r io.Reader, waitOptions WaitForOptions) (result Result, err error)

type ExtendedGDetectSubmitter

type ExtendedGDetectSubmitter interface {
	GetResultByUUID(ctx context.Context, uuid string) (result Result, err error)
	GetResultBySHA256(ctx context.Context, sha256 string) (result Result, err error)
	GetResults(ctx context.Context, from int, size int, tags ...string) (submissions []Submission, err error)
	SubmitFile(ctx context.Context, filepath string, options SubmitOptions) (uuid string, err error)
	SubmitReader(ctx context.Context, r io.Reader, options SubmitOptions) (uuid string, err error)
	WaitForFile(ctx context.Context, filepath string, options WaitForOptions) (result Result, err error)
	WaitForReader(ctx context.Context, r io.Reader, options WaitForOptions) (result Result, err error)
	ExtractTokenViewURL(result *Result) (urlTokenView string, err error)
	ExtractExpertViewURL(result *Result) (urlExpertView string, err error)
	GetFullSubmissionByUUID(ctx context.Context, uuid string) (result interface{}, err error)
	GetProfileStatus(ctx context.Context) (status ProfileStatus, err error)
	GetAPIVersion(ctx context.Context) (version string, err error)
}

type FeatureNotAvailableError

type FeatureNotAvailableError struct {
	Version string
}

func (FeatureNotAvailableError) Error

func (e FeatureNotAvailableError) Error() string

type FileResult

type FileResult struct {
	SHA256    string     `json:"sha256"`
	SHA1      string     `json:"sha1"`
	MD5       string     `json:"md5"`
	SSDeep    string     `json:"ssdeep"`
	Magic     string     `json:"magic"`
	AVResults []AvResult `json:"av_results,omitempty"`
	Size      int64      `json:"size"`
	IsMalware bool       `json:"is_malware"`
}

FileResult represents results for a file in an analysis result

type GDetectSubmitter

type GDetectSubmitter interface {
	GetResultByUUID(ctx context.Context, uuid string) (result Result, err error)
	GetResultBySHA256(ctx context.Context, sha256 string) (result Result, err error)
	GetResults(ctx context.Context, from int, size int, tags ...string) (submissions []Submission, err error)
	SubmitFile(ctx context.Context, filepath string, options SubmitOptions) (uuid string, err error)
	SubmitReader(ctx context.Context, r io.Reader, options SubmitOptions) (uuid string, err error)
	WaitForFile(ctx context.Context, filepath string, options WaitForOptions) (result Result, err error)
	WaitForReader(ctx context.Context, r io.Reader, options WaitForOptions) (result Result, err error)
	GetProfileStatus(ctx context.Context) (status ProfileStatus, err error)
	GetAPIVersion(ctx context.Context) (version string, err error)
}

type HTTPError

type HTTPError struct {
	Status string
	Code   int
	Body   string
}

func NewHTTPError

func NewHTTPError(r *http.Response, body string) HTTPError

func (HTTPError) Error

func (e HTTPError) Error() string

type ProfileStatus

type ProfileStatus struct {
	// DailyQuota is the amount of analyses allowed in 24h
	DailyQuota int `json:"daily_quota"`
	// AvailableDailyQuota is the amount of analyses currently available
	AvailableDailyQuota int `json:"available_daily_quota"`
	// Cache is true if the profile is configured to use detect SHA256 cache
	Cache bool `json:"cache"`
	// EstimatedAnalysisDuration is an estimated duration for the next analysis in milliseconds
	// It's an optimistic estimation based on the average analysis time and the analysis queue
	EstimatedAnalysisDuration int `json:"estimated_analysis_duration"`
	// Malware threshold is the threshold at which a file is considered malicious
	MalwareThreshold int `json:"malware_threshold"`
}

ProfileStatus contains information about profile status

type Result

type Result struct {
	UUID              string            `json:"uuid"`
	SHA256            string            `json:"sha256"`
	SHA1              string            `json:"sha1"`
	MD5               string            `json:"md5"`
	SSDeep            string            `json:"ssdeep"`
	Malware           bool              `json:"is_malware"`
	Score             int               `json:"score"`
	Done              bool              `json:"done"`
	Timestamp         int64             `json:"timestamp"`
	Errors            map[string]string `json:"errors,omitempty"`
	Error             string            `json:"error,omitempty"`
	FileType          string            `json:"filetype"`
	FileSize          int64             `json:"size"`
	Filenames         []string          `json:"filenames,omitempty"`
	Malwares          []string          `json:"malwares,omitempty"`
	Files             []FileResult      `json:"files,omitempty"`
	SID               string            `json:"sid,omitempty"`
	Comment           string            `json:"comment,omitempty"`
	FileCount         int               `json:"file_count"`
	Duration          int64             `json:"duration"`
	Token             string            `json:"token,omitempty"`
	Threats           map[string]Threat `json:"threats,omitempty"`
	SpecialStatusCode int               `json:"special_status_code"`
}

Result represent typical json result from Detect API operations like get or search. It maps elements from the json result to fields.

type Submission

type Submission struct {
	UUID              string   `json:"uuid"`
	Malware           bool     `json:"is_malware"`
	Done              bool     `json:"done"`
	Error             bool     `json:"error"`
	Filename          string   `json:"filename"`
	Date              int64    `json:"date"`
	FileSize          int64    `json:"file_size"`
	FileType          string   `json:"file_type"`
	Score             int      `json:"score"`
	Malwares          []string `json:"malwares"`
	SpecialStatusCode int      `json:"special_status_code"`
}

type SubmitOptions

type SubmitOptions struct {
	Tags            []string
	Description     string
	BypassCache     bool
	Filename        string
	ArchivePassword string
}

Options for SubmitFile method

type Tag

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

Tag part for Threat

type Threat

type Threat struct {
	Filenames []string `json:"filenames"`
	Tags      []Tag    `json:"tags"`
	Score     int      `json:"score"`
	Magic     string   `json:"magic"`
	SHA256    string   `json:"sha256"`
	SHA1      string   `json:"sha1"`
	MD5       string   `json:"md5"`
	SSDeep    string   `json:"ssdeep"`
	FileSize  int64    `json:"file_size"`
	Mime      string   `json:"mime"`
}

Threat part of an analysis result

type WaitForOptions

type WaitForOptions struct {
	Tags            []string
	Description     string
	BypassCache     bool
	ArchivePassword string
	Timeout         time.Duration
	PullTime        time.Duration
	Filename        string
}

Options for WaitForFile method