gdetect

package
v1.2.1 Latest Latest
Warning

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

Go to latest
Published: Apr 18, 2024 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

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

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

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	ErrTimeout  = fmt.Errorf("timeout")
	ErrBadToken = fmt.Errorf("bad token")
	ErrNoToken  = fmt.Errorf("no token in result")
	ErrNoSID    = fmt.Errorf("no sid in result")
)

Generic gdetect client errors.

View Source
var DefaultTimeout = time.Minute * 5

DefaultTimeout is the default timeout for gdetect client

Functions

This section is empty.

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
}

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 added in v1.1.0

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

GetAPIVersion retrieves detect API version

func (*Client) GetFullSubmissionByUUID added in v1.1.0

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 added in v1.1.0

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) 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 added in v1.1.0

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 added in v1.1.0

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

type ExtendedGDetectSubmitter added in v1.2.1

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 added in v1.1.0

type FeatureNotAvailableError struct {
	Version string
}

func (FeatureNotAvailableError) Error added in v1.1.0

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 added in v1.1.0

type HTTPError struct {
	Status string
	Code   int
	Body   string
}

func NewHTTPError added in v1.1.0

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

func (HTTPError) Error added in v1.1.0

func (e HTTPError) Error() string

type ProfileStatus added in v1.1.0

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"`
}

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"`
}

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

type Submission added in v1.1.0

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"`
}

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

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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