yara

README

Repackaged go-yara

This package is a repackaged version of https://github.com/hillu/go-yara which focuses on making it easier to use.

Instead of requiring users to install the yara library on the build system, this package already includes the library within it. This makes it very easy to use - simply add the dependency and build normally.

The resulting binary will also be statically built and have no external shared object dependencies. No need to mess with build flags:

~/go/src/github.com/Velocidex/go-yara$ go build _examples/simple-yara/simple-yara.go
~/go/src/github.com/Velocidex/go-yara$ ldd simple-yara
        linux-vdso.so.1 (0x00007ffd4085a000)
        libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x00007fcd9867c000)
        libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007fcd9828b000)
        /lib64/ld-linux-x86-64.so.2 (0x00007fcd9889b000)

To build for windows, there is no need to build the yara library first, just build your project with the usual steps:

~/go/src/github.com/Velocidex/go-yara$ GOOS=windows GOARCH=amd64 \
      CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc \
      go build _examples/simple-yara/simple-yara.go

go-yara

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. You also need to pass the tag when you build your own project.

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 -tags no_pkg_config github.com/hillu/go-yara

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
• func Finalize()
• func GetConfiguration(name ConfigName) (interface{}, error)
• func SetConfiguration(name ConfigName, src interface{}) error
• type Compiler
  • func NewCompiler() (*Compiler, error)
  • 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 Match
  • func (m *Match) Data() []byte
  • func (m *Match) Offset() int64
• type MatchRule
• type MatchRules
  • func (mr *MatchRules) RuleMatching(r *Rule) (abort bool, err error)
• type MatchString
• type Object
• type Rule
  • func (r *Rule) Disable()
  • func (r *Rule) Enable()
  • func (r *Rule) Identifier() string
  • func (r *Rule) Metas() (metas map[string]interface{})
  • func (r *Rule) Namespace() string
  • func (r *Rule) Strings() (strs []String)
  • func (r *Rule) Tags() (tags []string)
• type Rules
  • func Compile(rules string, variables map[string]interface{}) (r *Rules, err error)
  • func LoadRules(filename string) (*Rules, error)
  • func MustCompile(rules string, variables map[string]interface{}) (r *Rules)
  • func ReadRules(rd io.Reader) (*Rules, error)
  • func (r *Rules) DefineVariable(identifier string, value interface{}) (err error)
  • func (r *Rules) Destroy()
  • func (r *Rules) GetRules() (rv []Rule)
  • func (r *Rules) Save(filename string) (err error)
  • func (r *Rules) ScanFile(filename string, flags ScanFlags, timeout time.Duration) (matches []MatchRule, err error)
  • func (r *Rules) ScanFileDescriptor(fd uintptr, flags ScanFlags, timeout time.Duration) (matches []MatchRule, err error)
  • func (r *Rules) ScanFileDescriptorWithCallback(fd uintptr, flags ScanFlags, timeout time.Duration, cb ScanCallback) (err error)
  • func (r *Rules) ScanFileWithCallback(filename string, flags ScanFlags, timeout time.Duration, cb ScanCallback) (err error)
  • func (r *Rules) ScanMem(buf []byte, flags ScanFlags, timeout time.Duration) (matches []MatchRule, err error)
  • func (r *Rules) ScanMemWithCallback(buf []byte, flags ScanFlags, timeout time.Duration, cb ScanCallback) (err error)
  • func (r *Rules) ScanProc(pid int, flags ScanFlags, timeout time.Duration) (matches []MatchRule, err error)
  • func (r *Rules) ScanProcWithCallback(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 ScanFlags
• type String
  • func (s *String) Identifier() string
  • func (s *String) Matches() (matches []Match)

Constants

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
)

Functions

func Finalize

func Finalize()

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

SetCnofiguration 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.

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.

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

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.

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

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) 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 ConfigName

type ConfigName uint32

const (
	ConfigStackSize         ConfigName = C.YR_CONFIG_STACK_SIZE
	ConfigMaxStringsPerRule            = C.YR_CONFIG_MAX_STRINGS_PER_RULE
)

const ConfigMaxMatchData ConfigName = C.YR_CONFIG_MAX_MATCH_DATA

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 string 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 is used to collect matches that are returned by the simple (*Rules).Scan* methods.

func (*MatchRules) RuleMatching

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

RuleMatching implements the ScanCallbackMatch interface for MatchRules.

type MatchString

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

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

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 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) GetRules

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

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

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 ScanCallback) (err error)

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

func (*Rules) ScanFileWithCallback

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

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

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 ScanCallback) (err error)

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

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 ScanCallback) (err error)

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

func (*Rules) Write

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

Write writes a compiled ruleset to an io.Writer.

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).Scan*WithCallback methods.

type ScanCallbackFinished

type ScanCallbackFinished interface {
	ScanFinished() (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(*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(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(*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(*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 ScanFlags

type ScanFlags int

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

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.