Home Original page

yara package - github.com/hillu/go-yara/v4 - Go Packages

Package yara provides bindings to the YARA library.

This section is empty.

Finalize releases all the resources allocated by the YARA library. It should be called by the program when it no longer needs YARA, e.g. just before the program exits. It is not strictly necessary to call Finalize because the allocated memory will be freed on program exit; however, explicitly-freed resources will not show up as a leak in memory profiling tools.

A good practice is calling Finalize as a deferred function in the program's main function: 

defer yara.Finalize()

func GetConfiguration(name ConfigName) (interface{}, error)

GetConfiguration gets a global YARA configuration option. 

func SetConfiguration(name ConfigName, src interface{}) error

SetConfiguration sets a global YARA configuration option. 

type Compiler struct {
	Errors   []CompilerMessage
	Warnings []CompilerMessage
	
}

A Compiler encapsulates the YARA compiler that transforms rules into YARA's internal, binary form which in turn is used for scanning files or memory blocks.

Since this type contains a C pointer to a YR_COMPILER structure that may be automatically freed, it should not be copied. 

func NewCompiler() (*Compiler, error)

NewCompiler creates a YARA compiler.

AddFile compiles rules from a file. Rules are added to the specified namespace.

If this function returns an error, the Compiler object will become unusable.

AddString compiles rules from a string. Rules are added to the specified namespace.

If this function returns an error, the Compiler object will become unusable. 

func (c *Compiler) DefineVariable(identifier string, value interface{}) (err error)

DefineVariable defines a named variable for use by the compiler. Boolean, int64, float64, and string types are supported. 

func (c *Compiler) Destroy()

Destroy destroys the YARA data structure representing a compiler.

It should not be necessary to call this method directly. 

func (c *Compiler) DisableIncludes()

DisableIncludes disables all include statements in the compiler. See yr_compiler_set_include_callbacks. 

func (c *Compiler) GetRules() (*Rules, error)

GetRules returns the compiled ruleset. 

func (c *Compiler) SetIncludeCallback(cb CompilerIncludeFunc)

SetIncludeCallback registers an include function that is called (through Go glue code) by the YARA compiler for every include statement. 

type CompilerIncludeFunc func(name, filename, namespace string) []byte

CompilerIncludeFunc is used with Compiler.SetIncludeCallback. Arguments are: name for the rule file to be included, filename for the file that contains the include statement, namespace for the rule namespace. The function returns a byte slice containing the contents of the included file. It must return a nil return value on error.

See also: yr_compiler_set_include_callback in the YARA C API documentation.

A CompilerMessage contains an error or warning message produced while compiling sets of rules using AddString or AddFile.

Error encapsulates the C API error codes. 

func (e Error) Error() (errorString string)

Match represents a string match.

Base returns the base offset of the memory block in which the string match occurred. 

func (m *Match) Data() []byte

Data returns the blob of data associated with the string match.

Offset returns the offset at which the string match occurred.

XorKey returns the XOR value with which the string match occurred.

A MatchRule represents a rule successfully matched against a block of data. 

type MatchRules []MatchRule

MatchRules is used to collect matches that are returned by the simple (*Rules).Scan* methods. 

func (mr *MatchRules) RuleMatching(sc *ScanContext, r *Rule) (abort bool, err error)

RuleMatching implements the ScanCallbackMatch interface for MatchRules.

A MatchString represents a string declared and matched in a rule.

MemoryBlock is returned by the MemoryBlockIterator's First and Next methods 

type MemoryBlockIterator interface {
	First() *MemoryBlock
	Next() *MemoryBlock
}

MemoryBlockIterator is a Go representation of YARA's YR_MEMORY_BLOCK_ITERATOR mechanism that is used within yr_rules_mem_scan_blobs. 

type MemoryBlockIteratorWithFilesize interface {
	MemoryBlockIterator
	Filesize() uint64
}
type Meta struct {
	Identifier string
	Value      interface{}
}

Meta represents a rule meta variable. Value can be of type string, int, boolean, or nil.

Rule represents a single rule as part of a ruleset.

Disable disables a single rule.

Enable enables a single rule.

Identifier returns the rule's name. 

func (r *Rule) IsGlobal() bool

IsGlobal returns true if the rule is marked as global. 

func (r *Rule) IsPrivate() bool

IsPrivate returns true if the rule is marked as private. 

func (r *Rule) Metas() (metas []Meta)

Metas returns the rule's meta variables as a list of Meta objects.

Namespace returns the rule's namespace. 

func (r *Rule) Strings() (strs []String)

Strings returns the rule's strings. 

func (r *Rule) Tags() (tags []string)

Tags returns the rule's tags. 

type RuleProfilingInfo struct {
	Rule
	Cost uint64
}

Rules contains a compiled YARA ruleset.

Since this type contains a C pointer to a YR_RULES structure that may be automatically freed, it should not be copied.

Compile compiles rules and an (optional) set of variables into a Rules object in a single step.

LoadRules retrieves a compiled ruleset from filename. 

func MustCompile(rules string, variables map[string]interface{}) (r *Rules)

MustCompile is like Compile but panics if the rules and optional variables can't be compiled. Like regexp.MustCompile, it allows for simple, safe initialization of global or test data.

ReadRules retrieves a compiled ruleset from an io.Reader. 

func (r *Rules) DefineVariable(identifier string, value interface{}) (err error)

DefineVariable defines a named variable for use by the compiler. Boolean, int64, float64, and string types are supported. 

func (r *Rules) Destroy()

Destroy destroys the YARA data structure representing a ruleset.

It should not be necessary to call this method directly. 

func (r *Rules) GetRules() (rules []Rule)

GetRules returns a slice of rule objects that are part of the ruleset.

Save writes a compiled ruleset to filename.

ScanFile scans a file using the ruleset. For every event emitted by libyara, the corresponding method on the ScanCallback object is called.

Note that the filename is passed as-is to the YARA library and may not be processed in a sensible way. It is recommended to avoid this function and to obtain an os.File handle f using os.Open() and use ScanFileDescriptor(f.Fd(), …) instead.

ScanFileDescriptor scans a file using the ruleset. For every event emitted by libyara, the corresponding method on the ScanCallback object is called.

ScanMem scans an in-memory buffer using the ruleset. For every event emitted by libyara, the corresponding method on the ScanCallback object is called.

ScanMemBlocks scans over a MemoryBlockIterator using the ruleset. For every event emitted by libyara, the corresponding method on the ScanCallback object is called.

ScanProc scans a live process using the ruleset. For every event emitted by libyara, the corresponding method on the ScanCallback object is called.

Write writes a compiled ruleset to an io.Writer. 

type ScanCallback interface {
	RuleMatching(*ScanContext, *Rule) (bool, error)
}

ScanCallback is a placeholder for different interfaces that may be implemented by the callback object that is passed to the (*Rules).ScanXxxx and (*Scanner).ScanXxxx methods.

The RuleMatching method corresponds to YARA's CALLBACK_MSG_RULE_MATCHING message. 

type ScanCallbackConsoleLog interface {
	ConsoleLog(*ScanContext, string)
}

ScanCallbackConsoleLog can be used to implement custom functions to handle the console.log feature introduced in YARA 4.2. 

type ScanCallbackFinished interface {
	ScanFinished(*ScanContext) (bool, error)
}

ScanCallbackFinished is used to signal that a scan has finished. The ScanFinished method corresponds to YARA's CALLBACK_MSG_SCAN_FINISHED message.

ScanCallbackModuleImport is used to provide data to a YARA module. The ImportModule method corresponds to YARA's CALLBACK_MSG_IMPORT_MODULE message. 

type ScanCallbackModuleImportFinished interface {
	ModuleImported(*ScanContext, *Object) (bool, error)
}

ScanCallbackModuleImportFinished can be used to free resources that have been used in the ScanCallbackModuleImport implementation. The ModuleImported method corresponds to YARA's CALLBACK_MSG_MODULE_IMPORTED message. 

type ScanCallbackNoMatch interface {
	RuleNotMatching(*ScanContext, *Rule) (bool, error)
}

ScanCallbackNoMatch is used to record rules that did not match during a scan. The RuleNotMatching method corresponds to YARA's CALLBACK_MSG_RULE_NOT_MATCHING mssage. 

type ScanCallbackTooManyMatches interface {
	TooManyMatches(*ScanContext, *Rule, string) (bool, error)
}

ScanCallbackTooManyMatches can be used to receive information about strings that match too many times. 

type ScanContext struct {
	
}

ScanContext contains the data passed to the ScanCallback methods.

Since this type contains a C pointer to a YR_SCAN_CONTEXT structure that may be automatically freed, it should not be copied.

ScanFlags are used to tweak the behavior of Scan* functions. 

type Scanner struct {

	
	Callback ScanCallback
	
}

Scanner contains a YARA scanner (YR_SCANNER). The main difference to Rules (YR_RULES) is that it is possible to set variables in a thread-safe manner (cf. https://github.com/VirusTotal/yara/issues/350).

Since this type contains a C pointer to a YR_SCANNER structure that may be automatically freed, it should not be copied. 

func NewScanner(r *Rules) (*Scanner, error)

NewScanner creates a YARA scanner. 

func (s *Scanner) DefineVariable(identifier string, value interface{}) (err error)

DefineVariable defines a named variable for use by the scanner. Boolean, int64, float64, and string types are supported. 

func (s *Scanner) Destroy()

Destroy destroys the YARA data structure representing a scanner.

It should not be necessary to call this method directly. 

func (s *Scanner) GetLastErrorRule() (r *Rule)

GetLastErrorRule returns the Rule which caused the last error.

The result is nil, if scanner returned no rule 

func (s *Scanner) GetLastErrorString() (r *String)

GetLastErrorString returns the String which caused the last error.

The result is nil, if scanner returned no string 

func (s *Scanner) GetProfilingInfo() (rpis []RuleProfilingInfo)

GetProfilingInfo retrieves profiling information from the Scanner. 

func (s *Scanner) ResetProfilingInfo()

ResetProfilingInfo resets the Scanner's profiling information

ScanFile scans a file using the scanner.

If no callback object has been set for the scanner using SetCAllback, it is initialized with an empty MatchRules object.

Note that the filename is passed as-is to the YARA library and may not be processed in a sensible way. It is recommended to avoid this function and to obtain an os.File handle f using os.Open() and use ScanFileDescriptor(f.Fd()) instead.

ScanFileDescriptor scans a file using the scanner.

If no callback object has been set for the scanner using SetCAllback, it is initialized with an empty MatchRules object.

ScanMem scans an in-memory buffer using the scanner.

If no callback object has been set for the scanner using SetCAllback, it is initialized with an empty MatchRules object. 

func (s *Scanner) ScanMemBlocks(mbi MemoryBlockIterator) (err error)

ScanMemBlocks scans over a MemoryBlockIterator using the scanner.

If no callback object has been set for the scanner using SetCallback, it is initialized with an empty MatchRules object.

ScanProc scans a live process using the scanner.

If no callback object has been set for the scanner using SetCAllback, it is initialized with an empty MatchRules object. 

func (s *Scanner) SetCallback(cb ScanCallback) *Scanner

SetCallback sets a callback object for the scanner. For every event emitted by libyara during subsequent scan, the appropriate method on the ScanCallback object is called.

For the common case where only a list of matched rules is relevant, setting a callback object is not necessary. 

func (s *Scanner) SetFlags(flags ScanFlags) *Scanner

SetFlags sets flags for the scanner.

SetTimeout sets a timeout for the scanner.

String represents a string as part of a rule.

Identifier returns the string's name. 

func (s *String) Matches(sc *ScanContext) (matches []Match)

Matches returns all matches that have been recorded for the string.