yara_x

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

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

Go to latest
Published: May 24, 2024 License: BSD-3-Clause Imports: 9 Imported by: 0

Documentation

Overview

Package yara_x provides Go bindings to the YARA-X library.

Example (Basic)
// Compile some YARA rules.
rules, _ := Compile(`
rule foo {
  strings:
    $foo = "foo"
  condition:
    $foo
}

rule bar {
  strings:
    $bar = "bar"
  condition:
    $bar
}`)

// Use the compiled rules for scanning some data.
matchingRules, _ := rules.Scan([]byte("foobar"))

// Iterate over the matching rules.
for _, r := range matchingRules {
	fmt.Printf("rule %s matched\n", r.Identifier())
}
Output:

rule foo matched
rule bar matched
Example (CompilerAndScanner)
// Create a new compiler.
compiler, _ := NewCompiler()

// Add some rules to the compiler.
err := compiler.AddSource(`rule foo {
		strings:
		  $foo = "foo"
		condition:
          $foo
	}

    rule bar {
		strings:
		$bar = "bar"
		condition:
		$bar
	}`)

if err != nil {
	panic(err)
}

// Get the compiled rules.
rules := compiler.Build()

// Pass the compiled rules to a scanner.
scanner := NewScanner(rules)

// Use the scanner for scanning some data.
matchingRules, _ := scanner.Scan([]byte("foobar"))

// Iterate over the matching rules.
for _, r := range matchingRules {
	fmt.Printf("rule %s matched\n", r.Identifier())
}
Output:

rule foo matched
rule bar matched

Index

Examples

Constants

This section is empty.

Variables

View Source
var ErrTimeout = errors.New("timeout")

Functions

This section is empty.

Types

type CompileOption

type CompileOption func(c *Compiler) error

A CompileOption represent an option passed to NewCompiler and Compile.

func Globals

func Globals(vars map[string]interface{}) CompileOption

The Globals option for NewCompiler and Compile allows you to define global variables.

Keys in the map represent variable names, and values are their initial values. Values associated with variables can be modified at scan time using Scanner.SetGlobal. If this option is used multiple times, global variables will be the union of all specified maps. If the same variable appears in multiple maps, the value from the last map will prevail.

Alternatively, you can use Compiler.DefineGlobal to define global variables. However, variables defined this way are not retained after Compiler.Build is called, unlike variables defined with the Globals option.

Valid value types include: int, int32, int64, bool, string, float32 and float64.

func IgnoreModule

func IgnoreModule(module string) CompileOption

IgnoreModule is an option for NewCompiler and Compile that allows ignoring a given module.

This option can be passed multiple times with different module names. Alternatively, you can use Compiler.IgnoreModule, but modules ignored this way are not retained after Compiler.Build is called, unlike modules ignored with the IgnoreModule option.

func RelaxedReSyntax

func RelaxedReSyntax(yes bool) CompileOption

RelaxedReSyntax is an option for NewCompiler and Compile that determines whether the compiler should adopt a more relaxed approach while parsing regular expressions.

YARA-X enforces stricter regular expression syntax compared to YARA. For instance, YARA accepts invalid escape sequences and treats them as literal characters (e.g., \R is interpreted as a literal 'R'). It also allows some special characters to appear unescaped, inferring their meaning from the context (e.g., `{` and `}` in `/foo{}bar/` are literal, but in `/foo{0,1}bar/` they form the repetition operator `{0,1}`).

When this option is set, YARA-X mimics YARA's behavior, allowing constructs that YARA-X doesn't accept by default.

type Compiler

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

Compiler represent a YARA compiler.

func NewCompiler

func NewCompiler(opts ...CompileOption) (*Compiler, error)

NewCompiler creates a new compiler.

func (*Compiler) AddSource

func (c *Compiler) AddSource(src string) error

AddSource adds some YARA source code to be compiled.

This function can be called multiple times.

Example:

c := NewCompiler()
c.AddSource("rule foo { condition: true }")
c.AddSource("rule bar { condition: true }")

func (*Compiler) Build

func (c *Compiler) Build() *Rules

Build creates a Rules object containing a compiled version of all the YARA rules previously added to the compiler.

Once this function is called the compiler is reset to its initial state (i.e: the state it had after NewCompiler returned).

func (*Compiler) DefineGlobal

func (c *Compiler) DefineGlobal(ident string, value interface{}) error

DefineGlobal defines a global variable and sets its initial value.

Global variables must be defined before using Compiler.AddSource for adding any YARA source code that uses those variables. The variable will retain its initial value when the compiled Rules are used for scanning data, however each scanner can change the variable's initial value by calling Scanner.SetGlobal.

Valid value types are: int, int32, int64, bool, string, float32 and float64.

func (*Compiler) Destroy

func (c *Compiler) Destroy()

Destroy destroys the compiler.

Calling Destroy is not required, but it's useful for explicitly freeing the memory used by the compiler.

func (*Compiler) IgnoreModule

func (c *Compiler) IgnoreModule(module string)

IgnoreModule tells the compiler to ignore the module with the given name.

Any YARA rule using the module will be ignored, as well as rules that depends on some other rule that uses the module. The compiler will issue warnings about the ignored rules, but otherwise the compilation will succeed.

func (*Compiler) NewNamespace

func (c *Compiler) NewNamespace(namespace string)

NewNamespace creates a new namespace.

Later calls to Compiler.AddSource will put the rules under the newly created namespace.

Examples:

c := NewCompiler()
// Add some rule named "foo" under the default namespace
c.AddSource("rule foo { condition: true }")

// Create a new namespace named "bar"
c.NewNamespace("bar")

// It's ok to add another rule named "foo", as it is in a different
// namespace than the previous one.
c.AddSource("rule foo { condition: true }")

type Match

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

Match contains information about the offset where a match occurred and the length of the match.

func (*Match) Length

func (m *Match) Length() uint

Length returns the length of a match in bytes.

func (*Match) Offset

func (m *Match) Offset() uint

Offset returns the offset within the scanned data where a match occurred.

type Pattern

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

Pattern represents a pattern in a Rule.

func (*Pattern) Identifier

func (p *Pattern) Identifier() string

Identifier returns the pattern's identifier (i.e: $a, $foo).

func (*Pattern) Matches

func (p *Pattern) Matches() []Match

Matches returns the matches found for this pattern.

type Rule

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

Rule represents a YARA rule.

func (*Rule) Identifier

func (r *Rule) Identifier() string

Identifier returns the rule's identifier.

func (*Rule) Namespace

func (r *Rule) Namespace() string

Namespace returns the rule's namespace.

func (*Rule) Patterns

func (r *Rule) Patterns() []Pattern

Patterns returns the patterns defined by this rule.

type Rules

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

Rules represents a set of compiled YARA rules.

func Compile

func Compile(src string, opts ...CompileOption) (*Rules, error)

Compile receives YARA source code and returns compiled Rules that can be used for scanning data.

func Deserialize

func Deserialize(data []byte) (*Rules, error)

Deserialize deserializes rules from a byte slice.

The counterpart is Rules.Serialize

func (*Rules) Destroy

func (r *Rules) Destroy()

Destroy destroys the compiled YARA rules represented by Rules.

Calling this method directly is not necessary, it will be invoked by the garbage collector when the rules are not used anymore.

func (*Rules) Scan

func (r *Rules) Scan(data []byte) ([]*Rule, error)

Scan some data with the compiled rules.

Returns a slice with the rules that matched.

func (*Rules) Serialize

func (r *Rules) Serialize() ([]byte, error)

Serialize converts the compiled rules into a byte slice.

type ScanResults

type ScanResults struct{}

type Scanner

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

Scanner scans data with a set of compiled YARA rules.

func NewScanner

func NewScanner(r *Rules) *Scanner

NewScanner creates a Scanner that will use the provided YARA rules.

It's safe to pass the same Rules to multiple scanners, and use each scanner on a separate goroutine for performing multiple scans in parallel with the same set of rules.

func (*Scanner) Destroy

func (s *Scanner) Destroy()

Destroy destroys the scanner.

Calling this method directly is not necessary, it will be invoked by the garbage collector when the scanner is not used anymore.

func (*Scanner) Scan

func (s *Scanner) Scan(buf []byte) ([]*Rule, error)

Scan scans the provided data with the Rules associated to the Scanner.

func (*Scanner) SetGlobal

func (s *Scanner) SetGlobal(ident string, value interface{}) error

SetGlobal sets the value of a global variable.

The variable must has been previously defined by calling Compiler.DefineGlobal and the type it has during the definition must match the type of the new value.

The variable will retain the new value in subsequent scans, unless this function is called again for setting a new value.

func (*Scanner) SetModuleOutput

func (s *Scanner) SetModuleOutput(data proto.Message) error

SetModuleOutput sets the output data for a YARA module.

Each YARA module generates an output consisting of a data structure that contains information about the scanned file. This data structure is represented by a Protocol Buffer. Typically, you won't need to provide this data yourself, as the YARA module automatically generates different outputs for each file it scans.

However, there are two scenarios in which you may want to provide the output for a module yourself:

1) When the module does not produce any output on its own. 2) When you already know the output of the module for the upcoming file to be scanned, and you prefer to reuse this data instead of generating it again.

Case 1) applies to certain modules lacking a main function, thus incapable of producing any output on their own. For such modules, you must set the output before scanning the associated data. Since the module's output typically varies with each scanned file, you need to call this function prior to each invocation of Scanner.Scan. Once Scanner.Scan is executed, the module's output is consumed and will be empty unless set again before the subsequent call.

Case 2) applies when you have previously stored the module's output for certain scanned data. In such cases, when rescanning the data, you can utilize this function to supply the module's output, thereby preventing redundant computation by the module. This optimization enhances performance by eliminating the need for the module to reparse the scanned data.

The data argument must be a Protocol Buffer message corresponding to any of the existing YARA modules.

func (*Scanner) SetTimeout

func (s *Scanner) SetTimeout(timeout time.Duration)

SetTimeout sets a timeout for scan operations.

The Scanner.Scan method will return a timeout error once the provided timeout duration has elapsed. The scanner will make every effort to stop promptly after the designated timeout duration. However, in some cases, particularly with rules containing only a few patterns, the scanner could potentially continue running for a longer period than the specified timeout.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL