yara

README

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.

YARA 3.4.0 or higher is required for full functionality. If you need to build with YARA 3.3.0, please build with the yara3.3 build tag. (The compat-yara-3.3 branch has been removed.)

Installation

Unix

On a Unix system with libyara properly installed, this should work, provided that GOPATH is set:

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

Depending on what location libyara and its headers have been installed, proper CFLAGS and LDFLAGS may have to be added to cgo.go or be specified via environment variables (CGO_CFLAGS and CGO_LDFLAGS).

Linker errors buried in the CGO output such as

undefined reference to `yr_compiler_add_file'

probably mean that the linker is looking at an old version of the YARA library.

Cross-building for Windows

YARA and go-yara can be cross-built on a Debian system as long as the Go compiler contains Windows runtime libraries with CGO support (cf.).

The YARA library is built from the source tree with the MinGW compiler using the usual ./configure && make && make install. Then go-yara is built and installed to GOPATH using go install. Some environment variables need to be passed to the go tool:

• 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).
• The C compiler in turn needs to know where to find headers and libraries, these locations are specified via the CGO_CFLAGS and CGO_LDFLAGS variables.

32bit:

cd ${YARA_SRC}
./configure --host=i686-w64-mingw32 --disable-magic --disable-cuckoo --without-crypto
make
make install prefix=./i686-w64-mingw32
cd ${GO_YARA_SRC}
GOOS=windows GOARCH=386 CGO_ENABLED=1 CC=i686-w64-mingw32-gcc \
  CGO_CFLAGS=-I${YARA_SRC}/i686-w64-mingw32/include \
  CGO_LDFLAGS=-L${YARA_SRC}/i686-w64-mingw32/lib \
  go install --ldflags '-extldflags "-static"' github.com/hillu/go-yara

64bit:

cd ${YARA_SRC}
./configure --host=x86_64-w64-mingw32 --disable-magic --disable-cuckoo --without-crypto
make
make install prefix=./x86_64-w64-mingw32
cd ${GO_YARA_SRC}
GOOS=windows GOARCH=amd64 CGO_ENABLED=1 CC=x86_64-w64-mingw32-gcc \
  CGO_CFLAGS=-I${YARA_SRC}/x86_64-w64-mingw32/include \
  CGO_LDFLAGS=-L${YARA_SRC}/x86_64-w64-mingw32/lib \
  go install --ldflags '-extldflags "-static"' 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
• 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(name string, value interface{}) (err error)
  • func (c *Compiler) Destroy()
  • func (c *Compiler) GetRules() (*Rules, error)
• type CompilerMessage
• type MatchRule
• type MatchString
• 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(name string, value interface{}) (err error)
  • func (r *Rules) Destroy()
  • 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) ScanMem(buf []byte, flags ScanFlags, timeout time.Duration) (matches []MatchRule, err error)
  • func (r *Rules) ScanProc(pid int, flags int, timeout time.Duration) (matches []MatchRule, err error)
  • func (r *Rules) Write(wr io.Writer) (err error)
• type ScanFlags

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
)

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.

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

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

GetRules returns the compiled ruleset.

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 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 MatchString

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

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

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(name 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) 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.

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.

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.

func (*Rules) ScanProc

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

ScanProc scans a live process using the ruleset.

func (*Rules) Write

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

Write writes a compiled ruleset to an io.Writer.

type ScanFlags

type ScanFlags int

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