yara

package module
v0.0.0-...-a24afc7 Latest Latest
Warning

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

 Go to latest Published: Aug 12, 2019 License: BSD-2-Clause Imports: 12 Imported by: 0

README

Logo

go-yara

GoDoc Travis Go Report Card

Go bindings for YARA, staying as close as sensible to the library's C-API while taking inspiration from the yara-python implementation.

Installation

Unix

On a Unix system with libyara, its header files, and pkg-config installed, the following should simply work, provided that GOPATH is set:

go get github.com/hillu/go-yara
go install github.com/hillu/go-yara

The pkg-config program should be able to output the correct compiler and linker flags from the yara.pc file that has been generated and installed by YARA's build system. If libyara has been installed to a custom location, the PKG_CONFIG_PATH environment variable can be used to point pkg-config at the right yara.pc file. If pkg-config cannot be used at all, please see "Build Tags" below.

Linker errors in the compiler output such as

undefined reference to `yr_compiler_add_file'

indicate that the linker is probably looking at an old version of libyara.

Cross-building for Windows

go-yara can be cross-built on a current Debian system using the MinGW cross compiler (gcc-mingw-w64) if the Go compiler contains Windows runtime libraries with CGO support (cf.). After libyara has been built from the source tree with the MinGW compiler using the usual ./configure && make && make install, go-yara can be built and installed. Some environment variables need to be set when running go build or go install:

  • GOOS, GOARCH indicate the cross compilation target.
  • CGO_ENABLED is set to 1 beacuse it defaults to 0 when cross-compiling.
  • CC has to specified because the go tool has no knowledge on what C compiler to use (it defaults to the system C compiler, usually gcc).
  • PKG_CONFIG_PATH is set so the go tool can determine correct locations for headers and libraries through pkg-config.

32bit:

$ cd ${YARA_SRC} \
  && ./bootstrap.sh \
  && ./configure --host=i686-w64-mingw32 --disable-magic --disable-cuckoo --without-crypto --prefix=${YARA_SRC}/i686-w64-mingw32 \
  && make -C ${YARA_SRC} \
  && make -C ${YARA_SRC} install 
$ GOOS=windows GOARCH=amd64 CGO_ENABLED=1 \
  CC=i686-w64-mingw32-gcc \
  PKG_CONFIG_PATH=${YARA_SRC}/i686-w64-mingw32/lib/pkgconfig \
  go install -ldflags '-extldflags "-static"' github.com/hillu/go-yara

64bit:

$ cd ${YARA_SRC} \
  && ./bootstrap.sh \
  && ./configure --host=x86_64-w64-mingw32 --disable-magic --disable-cuckoo --without-crypto --prefix=${YARA_SRC}/x86_64-w64-mingw32 \
  && make -C ${YARA_SRC} \
  && make -C ${YARA_SRC} install 
$ GOOS=windows GOARCH=amd64 CGO_ENABLED=1 \
  CC=x86_64-w64-mingw32-gcc \
  PKG_CONFIG_PATH=${YARA_SRC}/x86_64-w64-mingw32/lib/pkgconfig \
  go install -ldflags '-extldflags "-static"' github.com/hillu/go-yara

Build Tags

go-yara is tested with the latest stable version of YARA, currently 3.7. If you need to to build with an older version of YARA, certain features that are not present in older versions can be excluded by passing a build tag such as yara3.3, yara3.4, yara3.5. If you want to build with a git snapshot of YARA, you may use a build tag corresponding to the upcoming stable YARA version, currently yara3.8.

The build tag yara_static can be used to tell the Go toolchain to run pkg-config with the --static switch.

The build tag no_pkg_config can be used to tell the Go toolchain not to use pkg-config's output. In this case, any compiler or linker flags have to be set via the CGO_CFLAGS and CGO_LDFLAGS environment variables, e.g.:

export CGO_CFLAGS="-I${YARA_SRC}/libyara/include"
export CGO_LDFLAGS="-L${YARA_SRC}/libyara/.libs -lyara"
go install github.com/hillu/go-yara -tags no_pkg_config

License

BSD 2-clause, see LICENSE file in the source distribution.

Author

Hilko Bengen bengen@hilluzination.de

Documentation

Overview

Package yara provides bindings to the YARA library.

Index

Constants

View Source 
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-prcess 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 library. It should be called when the program finishes using it.

func GetMaxMatchData 

func GetMaxMatchData() int

GetMaxMatchData returns the value for YARA's YR_CONFIG_MAX_MATCH_DATA configuration option. This controls the maximum amount of bytes that YARA stores for each matching string.

func Initialize 

func Initialize() error

Initialize prepares the library to be used.

func SetMaxMatchData 

func SetMaxMatchData(n int)

SetMaxMatchData sets the value for YR_CONFIG_MAX_MATCH_DATA configuration option, which controls the maximum amount of bytes that YARA stores for each matching string. If this value is zero YARA won't copy any data at all.

Types

type ByCostDesc 

type ByCostDesc []Rule

ByCostDesc is a type used for sorting an slice of Rule by time cost in descending order.

func (ByCostDesc) Len 

func (r ByCostDesc) Len() int

func (ByCostDesc) Less 

func (r ByCostDesc) Less(i, j int) bool

func (ByCostDesc) Swap 

func (r ByCostDesc) Swap(i, j int)

type Callback 

type Callback interface{}

Callback is the interface for the callback object passed to the Scan*WithCallback functions.

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.

func NewCompiler 

func NewCompiler() (*Compiler, error)

NewCompiler creates a YARA compiler.

func (*Compiler) AddFile 

func (c *Compiler) AddFile(file *os.File, namespace string) (err error)

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

func (*Compiler) AddString 

func (c *Compiler) AddString(rules string, namespace string) (err error)

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

func (*Compiler) DefineVariable 

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 (*Compiler) Destroy 

func (c *Compiler) Destroy()

Destroy destroys the YARA data structure representing a compiler. Since a Finalizer for the underlying YR_COMPILER structure is automatically set up on creation, it should not be necessary to explicitly call this method.

func (*Compiler) DisableIncludes 

func (c *Compiler) DisableIncludes()

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

func (*Compiler) GetRules 

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

GetRules returns the compiled ruleset.

func (*Compiler) LoadAtomQualityTable 

func (c *Compiler) LoadAtomQualityTable(path string, qualityWarningThreshold uint8) error

LoadAtomQualityTable loads an atom quality table from a file.

func (*Compiler) SetIncludeCallback 

func (c *Compiler) SetIncludeCallback(cb CompilerIncludeFunc)

SetIncludeCallback sets up cb as an include callback that is called (through Go glue code) by the YARA compiler for every include statement.

type CompilerIncludeFunc 

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

CompilerIncludeFunc is the type of the function that can be registered through SetIncludeCallback. It is called for every include statement encountered by the compiler. The argument "name" specifies the rule file to be included, "filename" specifies the name of the rule file where the include statement has been encountered, and "namespace" specifies the rule namespace. The sole return value is a byte slice containing the contents of the included file. A return value of nil signals an error to the YARA compiler.

See also: yr_compiler_set_include_callback in the YARA C API documentation.

type CompilerMessage 

type CompilerMessage struct {
	Filename string
	Line     int
	Text     string
}

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

type Error 

type Error struct {
	Code int
}

Error is an implementation of the error interface that includes the YARA error code. All functions in this package return this type of errors.

func (Error) Error 

func (e Error) Error() string

type ImportModuleCallback 

type ImportModuleCallback interface {
	OnImportModule(string) ([]byte, bool, error)
}

ImportModuleCallback is the interface that must satisfy the object passed to Scan*WithCallback in order to receive a message when a module is about to be loaded.

type Match 

type Match struct {
	// contains filtered or unexported fields
}

Match represents a string match

func (*Match) Data 

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

Data returns the blob of data associated with the match. Returns nil if YARA was configured for not storing the matching data by passing zero to SetMaxMatchData.

func (*Match) Length 

func (m *Match) Length() int64

Length returns the length of the match.

func (*Match) Offset 

func (m *Match) Offset() int64

Offset returns the offset at which the string match occurred

type MatchRule 

type MatchRule struct {
	Rule      string
	Namespace string
	Tags      []string
	Meta      map[string]interface{}
	Strings   []MatchString
}

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

type MatchRules 

type MatchRules []MatchRule

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

func (*MatchRules) OnRuleMatching 

func (mr *MatchRules) OnRuleMatching(r *Rule) (abort bool, err error)

type MatchString 

type MatchString struct {
	Name   string
	Offset uint64
	Data   []byte
	Length uint64
}

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

type ModuleImportedCallback 

type ModuleImportedCallback interface {
	OnModuleImported(*Object) (bool, error)
}

ModuleImportedCallback is the interface that must satisfy the object passed to Scan*WithCallback in order to receive a message when a module has been imported.

type Object 

type Object struct {
	// contains filtered or unexported fields
}

type Rule 

type Rule struct {
	// contains filtered or unexported fields
}

Rule represents a single rule as part of a ruleset

func (*Rule) Disable 

func (r *Rule) Disable()

Disable disables a single rule

func (*Rule) Enable 

func (r *Rule) Enable()

Enable enables a single rule

func (*Rule) Identifier 

func (r *Rule) Identifier() string

Identifier returns the rule's name.

func (*Rule) Metas 

func (r *Rule) Metas() (metas map[string]interface{})

Metas returns a map containing the rule's meta variables. Values can be of type string, int, bool, or nil.

func (*Rule) Namespace 

func (r *Rule) Namespace() string

Namespace returns the rule's namespace.

func (*Rule) Strings 

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

Strings returns the rule's strings

func (*Rule) Tags 

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

Tags returns the rule's tags.

type RuleCost 

type RuleCost struct {
	Rule       Rule
	Cost       int64
	Percentage float64
}

RuleCost contains information about the time cost of a Rule.

type RuleMatchingCallback 

type RuleMatchingCallback interface {
	OnRuleMatching(*Rule) (bool, error)
}

RuleMatchingCallback is the interface that must satisfy the object passed to Scan*WithCallback in order to receive messages about matching rules.

type RuleNotMatchingCallback 

type RuleNotMatchingCallback interface {
	OnRuleNotMatching(*Rule) (bool, error)
}

RuleNotMatchingCallback is the interface that must satisfy the object passed to Scan*WithCallback in order to receive messages about not matching rules.

type Rules 

type Rules struct {
	// contains filtered or unexported fields
}

Rules contains a compiled YARA ruleset.

func Compile 

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

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

func LoadRules 

func LoadRules(filename string) (*Rules, error)

LoadRules retrieves a compiled ruleset from filename.

func MustCompile 

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.

func ReadRules 

func ReadRules(rd io.Reader) (*Rules, error)

ReadRules retrieves a compiled ruleset from an io.Reader

func (*Rules) DefineVariable 

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 (*Rules) Destroy 

func (r *Rules) Destroy()

Destroy destroys the YARA data structure representing a ruleset. Since a Finalizer for the underlying YR_RULES structure is automatically set up on creation, it should not be necessary to explicitly call this method.

func (*Rules) GetMostCostlyRules 

func (r *Rules) GetMostCostlyRules(n int) []RuleCost

GetMostCostlyRules returns the top n rules according to their cost. The cost is calculated according to the time spend in matching the rule's strings and evaluating its condition. If the same Rules are used for scanning multiple files, buffers or processes the costs are accumulated.

func (*Rules) GetRules 

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

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

func (*Rules) ResetCosts 

func (r *Rules) ResetCosts()

ResetCosts resets the rules' cost counters to zero. The cost computation is cumulative, which means that everytime you scan some data with a set of Rules the counters are incremented according to the time spent by each rule, those counters are never reset to zero unless you call this function.

func (*Rules) Save 

func (r *Rules) Save(filename string) (err error)

Save writes a compiled ruleset to filename.

func (*Rules) ScanFile 

func (r *Rules) ScanFile(filename string, flags ScanFlags, timeout time.Duration) (matches []MatchRule, err error)

ScanFile scans a file using the ruleset, returning matches via a list of MatchRule objects.

func (*Rules) ScanFileDescriptor 

func (r *Rules) ScanFileDescriptor(fd uintptr, flags ScanFlags, timeout time.Duration) (matches []MatchRule, err error)

ScanFileDescriptor scans a file using the ruleset, returning matches via a list of MatchRule objects.

func (*Rules) ScanFileDescriptorWithCallback 

func (r *Rules) ScanFileDescriptorWithCallback(fd uintptr, flags ScanFlags, timeout time.Duration, cb Callback) (err error)

ScanFileDescriptorWithCallback scans a file using the ruleset, calling methods on the ScanCallback object for the various events generated from libyara.

func (*Rules) ScanFileWithCallback 

func (r *Rules) ScanFileWithCallback(filename string, flags ScanFlags, timeout time.Duration, cb Callback) (err error)

ScanFileWithCallback scans a file using the ruleset, calling methods on the ScanCallback object for the various events generated from libyara.

func (*Rules) ScanMem 

func (r *Rules) ScanMem(buf []byte, flags ScanFlags, timeout time.Duration) (matches []MatchRule, err error)

ScanMem scans an in-memory buffer using the ruleset, returning matches via a list of MatchRule objects.

func (*Rules) ScanMemWithCallback 

func (r *Rules) ScanMemWithCallback(buf []byte, flags ScanFlags, timeout time.Duration, cb Callback) (err error)

ScanMemWithCallback scans an in-memory buffer using the ruleset, calling methods on the ScanCallback object for the various events generated from libyara.

func (*Rules) ScanProc 

func (r *Rules) ScanProc(pid int, flags ScanFlags, timeout time.Duration) (matches []MatchRule, err error)

ScanProc scans a live process using the ruleset, returning matches via a list of MatchRule objects.

func (*Rules) ScanProcWithCallback 

func (r *Rules) ScanProcWithCallback(pid int, flags ScanFlags, timeout time.Duration, cb Callback) (err error)

ScanProcWithCallback scans a live process using the ruleset, calling methods on the ScanCallback object for the various events generated from libyara.

func (*Rules) Write 

func (r *Rules) Write(wr io.Writer) (err error)

Write writes a compiled ruleset to an io.Writer.

type ScanError 

type ScanError struct {
	Code             int
	Namespace        string
	RuleIdentifier   string
	StringIdentifier string
}

An ScanError is returning by all scan functions implemented by Scanner.

func (ScanError) Error 

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

type ScanFinishedCallback 

type ScanFinishedCallback interface {
	OnScanFinished() (bool, error)
}

ScanFinishedCallback is the interface that must satisfy the object passed to Scan*WithCallback in order to receive a message when the scan finishes.

type ScanFlags 

type ScanFlags int

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

type Scanner 

type Scanner struct {
	// contains filtered or unexported fields
}

A Scanner allows scanning files, in-memory data and processes using the compiled rules built with a Compiler.

func NewScanner 

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

NewScanner creates a scanner for scanning files, in-memory data or processes with the provided Rules.

func (*Scanner) DefineVariable 

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 (*Scanner) Destroy 

func (s *Scanner) Destroy()

Destroy destroys the YARA data structure representing a scanner. Since a Finalizer for the underlying YR_SCANNER structure is automatically set up on creation, it should not be necessary to explicitly call this method.

func (*Scanner) GetLastErrorRule 

func (s *Scanner) GetLastErrorRule() *Rule

GetLastErrorRule returns the rule that caused the last scanner error.

func (*Scanner) GetLastErrorString 

func (s *Scanner) GetLastErrorString() *String

GetLastErrorString returns the string that caused the last scanner error.

func (*Scanner) ScanMem 

func (s *Scanner) ScanMem(buf []byte, flags ScanFlags, timeout time.Duration) (matches []MatchRule, err error)

ScanMem scans an in-memory buffer using the scanner, returning matches via a list of MatchRule objects.

func (*Scanner) ScanMemWithCallback 

func (s *Scanner) ScanMemWithCallback(buf []byte, flags ScanFlags, timeout time.Duration, cb Callback) (err error)

ScanMemWithCallback scans an in-memory buffer using the scanner, calling methods on the ScanCallback object for the various events generated from libyara.

type String 

type String struct {
	// contains filtered or unexported fields
}

String represents a string as part of a rule

func (*String) Identifier 

func (s *String) Identifier() string

Identifier returns the string's name

func (*String) Matches 

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

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

Source Files

View all Source files

Directories

Path Synopsis
_examples
simple-yara

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.