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 YARA version.

Windows

I have not yet built go-yara on Windows, only used the MinGW-w64 provided on Debian. The YARA library was built like this:

$ ./configure --host=i686-w64-mingw32 --disable-magic --disable-cuckoo --without-crypto
[...]
$ make
$ make install prefix=/path/to/i686-w64-mingw32

Compiling and linking go-yara against this library was achieved like this:

$ CC=i686-w64-mingw32-gcc \
  CGO_ENABLED=1 \
  GOOS=windows GOARCH=386 \
  CGO_CFLAGS=-I/path/to/i686-w64-mingw32/include \
  CGO_LDFLAGS=-L/path/to/i686-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.