Documentation ¶
Overview ¶
Package yara provides bindings to the YARA library.
Index ¶
- Constants
- func Finalize() error
- func GetConfiguration(name ConfigName) (interface{}, error)
- func SetConfiguration(name ConfigName, src interface{}) error
- type Compiler
- func (c *Compiler) AddFile(file *os.File, namespace string) (err error)
- func (c *Compiler) AddString(rules string, namespace string) (err error)
- func (c *Compiler) DefineVariable(identifier string, value interface{}) (err error)
- func (c *Compiler) Destroy()
- func (c *Compiler) DisableIncludes()
- func (c *Compiler) GetRules() (*Rules, error)
- func (c *Compiler) SetIncludeCallback(cb CompilerIncludeFunc)
- type CompilerIncludeFunc
- type CompilerMessage
- type ConfigName
- type Error
- type Match
- type MatchRule
- type MatchRules
- type MatchString
- type MemoryBlock
- type MemoryBlockIterator
- type MemoryBlockIteratorWithFilesize
- type Meta
- type Object
- type ProfilingInfo
- type Rule
- type Rules
- func (r *Rules) DefineVariable(identifier string, value interface{}) (err error)
- func (r *Rules) Destroy()
- func (r *Rules) GetRules() (rules []Rule)
- func (r *Rules) Save(filename string) (err error)
- func (r *Rules) ScanFile(filename string, flags ScanFlags, timeout time.Duration, cb ScanCallback) (err error)
- func (r *Rules) ScanFileDescriptor(fd uintptr, flags ScanFlags, timeout time.Duration, cb ScanCallback) (err error)
- func (r *Rules) ScanMem(buf []byte, flags ScanFlags, timeout time.Duration, cb ScanCallback) (err error)
- func (r *Rules) ScanMemBlocks(mbi MemoryBlockIterator, flags ScanFlags, timeout time.Duration, ...) (err error)
- func (r *Rules) ScanProc(pid int, flags ScanFlags, timeout time.Duration, cb ScanCallback) (err error)
- func (r *Rules) Write(wr io.Writer) (err error)
- type ScanCallback
- type ScanCallbackFinished
- type ScanCallbackMatch
- type ScanCallbackModuleImport
- type ScanCallbackModuleImportFinished
- type ScanCallbackNoMatch
- type ScanContext
- type ScanFlags
- type Scanner
- func (s *Scanner) DefineVariable(identifier string, value interface{}) (err error)
- func (s *Scanner) Destroy()
- func (s *Scanner) GetLastErrorRule() *Rule
- func (s *Scanner) GetLastErrorString() *String
- func (s *Scanner) GetProfilingInfo(n int) (result []ProfilingInfo)
- func (s *Scanner) ResetProfilingInfo()
- func (s *Scanner) ScanFile(filename string) (err error)
- func (s *Scanner) ScanFileDescriptor(fd uintptr) (err error)
- func (s *Scanner) ScanMem(buf []byte) (err error)
- func (s *Scanner) ScanMemBlocks(mbi MemoryBlockIterator) (err error)
- func (s *Scanner) ScanProc(pid int) (err error)
- func (s *Scanner) SetCallback(cb ScanCallback) *Scanner
- func (s *Scanner) SetFlags(flags ScanFlags) *Scanner
- func (s *Scanner) SetTimeout(timeout time.Duration) *Scanner
- type String
Constants ¶
const ( ConfigStackSize ConfigName = C.YR_CONFIG_STACK_SIZE ConfigMaxMatchData = C.YR_CONFIG_MAX_MATCH_DATA ConfigMaxStringsPerRule = C.YR_CONFIG_MAX_STRINGS_PER_RULE )
const ( ERROR_SUCCESS = C.ERROR_SUCCESS ERROR_INSUFFICIENT_MEMORY = C.ERROR_INSUFFICIENT_MEMORY ERROR_COULD_NOT_ATTACH_TO_PROCESS = C.ERROR_COULD_NOT_ATTACH_TO_PROCESS ERROR_COULD_NOT_OPEN_FILE = C.ERROR_COULD_NOT_OPEN_FILE ERROR_COULD_NOT_MAP_FILE = C.ERROR_COULD_NOT_MAP_FILE ERROR_INVALID_FILE = C.ERROR_INVALID_FILE ERROR_CORRUPT_FILE = C.ERROR_CORRUPT_FILE ERROR_UNSUPPORTED_FILE_VERSION = C.ERROR_UNSUPPORTED_FILE_VERSION ERROR_INVALID_REGULAR_EXPRESSION = C.ERROR_INVALID_REGULAR_EXPRESSION ERROR_INVALID_HEX_STRING = C.ERROR_INVALID_HEX_STRING ERROR_SYNTAX_ERROR = C.ERROR_SYNTAX_ERROR ERROR_LOOP_NESTING_LIMIT_EXCEEDED = C.ERROR_LOOP_NESTING_LIMIT_EXCEEDED ERROR_DUPLICATED_LOOP_IDENTIFIER = C.ERROR_DUPLICATED_LOOP_IDENTIFIER ERROR_DUPLICATED_IDENTIFIER = C.ERROR_DUPLICATED_IDENTIFIER ERROR_DUPLICATED_TAG_IDENTIFIER = C.ERROR_DUPLICATED_TAG_IDENTIFIER ERROR_DUPLICATED_META_IDENTIFIER = C.ERROR_DUPLICATED_META_IDENTIFIER ERROR_DUPLICATED_STRING_IDENTIFIER = C.ERROR_DUPLICATED_STRING_IDENTIFIER ERROR_UNREFERENCED_STRING = C.ERROR_UNREFERENCED_STRING ERROR_UNDEFINED_STRING = C.ERROR_UNDEFINED_STRING ERROR_UNDEFINED_IDENTIFIER = C.ERROR_UNDEFINED_IDENTIFIER ERROR_MISPLACED_ANONYMOUS_STRING = C.ERROR_MISPLACED_ANONYMOUS_STRING ERROR_INCLUDES_CIRCULAR_REFERENCE = C.ERROR_INCLUDES_CIRCULAR_REFERENCE ERROR_INCLUDE_DEPTH_EXCEEDED = C.ERROR_INCLUDE_DEPTH_EXCEEDED ERROR_WRONG_TYPE = C.ERROR_WRONG_TYPE ERROR_EXEC_STACK_OVERFLOW = C.ERROR_EXEC_STACK_OVERFLOW ERROR_SCAN_TIMEOUT = C.ERROR_SCAN_TIMEOUT ERROR_TOO_MANY_SCAN_THREADS = C.ERROR_TOO_MANY_SCAN_THREADS ERROR_CALLBACK_ERROR = C.ERROR_CALLBACK_ERROR ERROR_INVALID_ARGUMENT = C.ERROR_INVALID_ARGUMENT ERROR_TOO_MANY_MATCHES = C.ERROR_TOO_MANY_MATCHES ERROR_INTERNAL_FATAL_ERROR = C.ERROR_INTERNAL_FATAL_ERROR ERROR_NESTED_FOR_OF_LOOP = C.ERROR_NESTED_FOR_OF_LOOP ERROR_INVALID_FIELD_NAME = C.ERROR_INVALID_FIELD_NAME ERROR_UNKNOWN_MODULE = C.ERROR_UNKNOWN_MODULE ERROR_NOT_A_STRUCTURE = C.ERROR_NOT_A_STRUCTURE ERROR_NOT_INDEXABLE = C.ERROR_NOT_INDEXABLE ERROR_NOT_A_FUNCTION = C.ERROR_NOT_A_FUNCTION ERROR_INVALID_FORMAT = C.ERROR_INVALID_FORMAT ERROR_TOO_MANY_ARGUMENTS = C.ERROR_TOO_MANY_ARGUMENTS ERROR_WRONG_ARGUMENTS = C.ERROR_WRONG_ARGUMENTS ERROR_WRONG_RETURN_TYPE = C.ERROR_WRONG_RETURN_TYPE ERROR_DUPLICATED_STRUCTURE_MEMBER = C.ERROR_DUPLICATED_STRUCTURE_MEMBER )
const ( // ScanFlagsFastMode avoids multiple matches of the same string // when not necessary. ScanFlagsFastMode = C.SCAN_FLAGS_FAST_MODE // ScanFlagsProcessMemory causes the scanned data to be // interpreted like live, in-process memory rather than an on-disk // file. ScanFlagsProcessMemory = C.SCAN_FLAGS_PROCESS_MEMORY )
Variables ¶
This section is empty.
Functions ¶
func Finalize ¶
func Finalize() error
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 ¶
func GetConfiguration(name ConfigName) (interface{}, error)
GetConfiguration gets a global YARA configuration option.
func SetConfiguration ¶
func SetConfiguration(name ConfigName, src interface{}) error
SetConfiguration sets a global YARA configuration option.
Types ¶
type Compiler ¶
type Compiler struct { Errors []CompilerMessage Warnings []CompilerMessage // contains filtered or unexported fields }
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 (*Compiler) AddFile ¶
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.
func (*Compiler) AddString ¶
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 (*Compiler) DefineVariable ¶
DefineVariable defines a named variable for use by the compiler. Boolean, int64, float64, and string types are supported.
func (*Compiler) Destroy ¶
func (c *Compiler) Destroy()
Destroy destroys the YARA data structure representing a compiler.
It should not be necessary to call this method directly.
func (*Compiler) DisableIncludes ¶
func (c *Compiler) DisableIncludes()
DisableIncludes disables all include statements in the compiler. See yr_compiler_set_include_callbacks.
func (*Compiler) SetIncludeCallback ¶
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 ¶
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.
type CompilerMessage ¶
A CompilerMessage contains an error or warning message produced while compiling sets of rules using AddString or AddFile.
type ConfigName ¶
type ConfigName uint32
type Error ¶
type Error struct { // YARA error code. Code int // Namespace in which the error occurred, if applicable. It can be empty. Namespace string // Rule in which the error occurred, if applicable. It can be empty. RuleIdentifier string // String in which the error occurred, if applicable. It can be empty. StringIdentifier string }
Error is an implementation of the error interface that includes the YARA error code. All functions in this package return this type of errors.
type Match ¶
type Match struct {
// contains filtered or unexported fields
}
Match represents a string match.
func (*Match) Base ¶
Base returns the base offset of the memory block in which the string match occurred.
type MatchRule ¶
type MatchRule struct { Rule string Namespace string Tags []string Metas []Meta Strings []MatchString }
A MatchRule represents a rule successfully matched against a block of data.
type MatchRules ¶
type MatchRules []MatchRule
MatchRules is used to collect matches that are returned by the simple (*Rules).Scan* methods.
func (*MatchRules) RuleMatching ¶
func (mr *MatchRules) RuleMatching(sc *ScanContext, r *Rule) (abort bool, err error)
RuleMatching implements the ScanCallbackMatch interface for MatchRules.
type MatchString ¶
A MatchString represents a string declared and matched in a rule. Name is the string's identifier. Offset is the offset within the file where the match was found. Data contains the portion of the file that matches, but it will be truncated to the amount specified with SetMaxMatchData, which by default is 512 bytes (this default value is controlled by the DEFAULT_MAX_MATCH_DATA macro defined in libyara.h). Length is the actual length of the match, and can be higher than len(Data).
type MemoryBlock ¶
type MemoryBlock struct { // Base contains the base address of the current block Base uint64 // Size contains the size of the current block Size uint64 // FetchData is used to read size bytes into a byte slice FetchData func([]byte) }
MemoryBlock is returned by the MemoryBlockIterator's First and Next methods
type MemoryBlockIterator ¶
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 ¶
type MemoryBlockIteratorWithFilesize interface { MemoryBlockIterator Filesize() uint64 }
type Meta ¶
type Meta struct { Identifier string Value interface{} }
Meta represents a rule meta variable. Value can be of type string, int, boolean, or nil.
type ProfilingInfo ¶
type Rule ¶
type Rule struct {
// contains filtered or unexported fields
}
Rule represents a single rule as part of a ruleset.
type Rules ¶
type Rules struct {
// contains filtered or unexported fields
}
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.
func Compile ¶
Compile compiles rules and an (optional) set of variables into a Rules object in a single step.
func MustCompile ¶
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.
func (*Rules) DefineVariable ¶
DefineVariable defines a named variable for use by the compiler. Boolean, int64, float64, and string types are supported.
func (*Rules) Destroy ¶
func (r *Rules) Destroy()
Destroy destroys the YARA data structure representing a ruleset.
It should not be necessary to call this method directly.
func (*Rules) ScanFile ¶
func (r *Rules) ScanFile(filename string, flags ScanFlags, timeout time.Duration, cb ScanCallback) (err error)
ScanFile scans a file using the ruleset. For every event emitted by libyara, the corresponding method on the ScanCallback object is called.
func (*Rules) ScanFileDescriptor ¶
func (r *Rules) ScanFileDescriptor(fd uintptr, flags ScanFlags, timeout time.Duration, cb ScanCallback) (err error)
ScanFileDescriptor scans a file using the ruleset. For every event emitted by libyara, the corresponding method on the ScanCallback object is called.
func (*Rules) ScanMem ¶
func (r *Rules) ScanMem(buf []byte, flags ScanFlags, timeout time.Duration, cb ScanCallback) (err error)
ScanMem scans an in-memory buffer using the ruleset. For every event emitted by libyara, the corresponding method on the ScanCallback object is called.
func (*Rules) ScanMemBlocks ¶
func (r *Rules) ScanMemBlocks(mbi MemoryBlockIterator, flags ScanFlags, timeout time.Duration, cb ScanCallback) (err error)
ScanMemBlocks scans over a MemoryBlockIterator using the ruleset. For every event emitted by libyara, the corresponding method on the ScanCallback object is called.
type ScanCallback ¶
type ScanCallback interface{}
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.
type ScanCallbackFinished ¶
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.
type ScanCallbackMatch ¶
type ScanCallbackMatch interface {
RuleMatching(*ScanContext, *Rule) (bool, error)
}
ScanCallbackMatch is used to record rules that matched during a scan. The RuleMatching method corresponds to YARA's CALLBACK_MSG_RULE_MATCHING message.
type ScanCallbackModuleImport ¶
type ScanCallbackModuleImport interface {
ImportModule(*ScanContext, string) ([]byte, bool, error)
}
ScanCallbackModuleImport is used to provide data to a YARA module. The ImportModule method corresponds to YARA's CALLBACK_MSG_IMPORT_MODULE message.
type ScanCallbackModuleImportFinished ¶
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 ¶
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 message.
type ScanContext ¶
type ScanContext struct {
// contains filtered or unexported fields
}
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.
func (*ScanContext) GetMatchStrings ¶
func (sc *ScanContext) GetMatchStrings(r *Rule) (matchstrings []MatchString)
GetMatchStrings returns a list of MatchString structures with the matches found for the rule r during the scan represented by the ScanContext.
type Scanner ¶
type Scanner struct { // Current callback object, set by SetCallback Callback ScanCallback // contains filtered or unexported fields }
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 (*Scanner) DefineVariable ¶
DefineVariable defines a named variable for use by the scanner. Boolean, int64, float64, and string types are supported.
func (*Scanner) Destroy ¶
func (s *Scanner) Destroy()
Destroy destroys the YARA data structure representing a scanner.
It should not be necessary to call this method directly.
func (*Scanner) GetLastErrorRule ¶
GetLastErrorRule returns the rule that caused the last scanner error.
func (*Scanner) GetLastErrorString ¶
GetLastErrorString returns the string that caused the last scanner error.
func (*Scanner) GetProfilingInfo ¶
func (s *Scanner) GetProfilingInfo(n int) (result []ProfilingInfo)
GetProfilingInfo returns a list of ProfilingInfo structures containing the profiling information for the slowest n rules.
func (*Scanner) ResetProfilingInfo ¶
func (s *Scanner) ResetProfilingInfo()
ResetProfilingInfo resets the profiling information accumulated by the scanner so far. When you scan multiple files/buffer with the same scanner the profiling information is not automatically reset after each scan, instead it gets accumulated. If you want to reset profiling information so that the counters start a zero again you must call this function.
func (*Scanner) ScanFile ¶
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.
func (*Scanner) ScanFileDescriptor ¶
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.
func (*Scanner) ScanMem ¶
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 (*Scanner) ScanMemBlocks ¶
func (s *Scanner) ScanMemBlocks(mbi MemoryBlockIterator) (err error)
ScahMemBlocks 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.
func (*Scanner) ScanProc ¶
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 (*Scanner) SetCallback ¶
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.
type String ¶
type String struct {
// contains filtered or unexported fields
}
String represents a string as part of a rule.
func (*String) Identifier ¶
Identifier returns the string's name.
func (*String) Matches ¶
func (s *String) Matches(sc *ScanContext) (matches []Match)
Matches returns all matches that have been recorded for the string.