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 ¶
var ErrTimeout = errors.New("timeout")
Functions ¶
This section is empty.
Types ¶
type CompileOption ¶
A CompileOption represent an option passed to NewCompiler and Compile.
func ErrorOnSlowPattern ¶ added in v0.4.0
func ErrorOnSlowPattern(yes bool) CompileOption
ErrorOnSlowPattern is an option for NewCompiler and Compile that tells the compiler to treat slow patterns as errors instead of warnings.
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 ¶ added in v0.3.0
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
type Metadata ¶ added in v0.4.0
type Metadata struct {
Identifier string
Value interface{}
}
Metadata represents a metadata in a Rule.
type Pattern ¶
type Pattern struct {
// contains filtered or unexported fields
}
Pattern represents a pattern in a Rule.
func (*Pattern) Identifier ¶
Identifier returns the pattern's identifier (i.e: $a, $foo).
type Rule ¶
type Rule struct {
// contains filtered or unexported fields
}
Rule represents a YARA rule.
func (*Rule) Identifier ¶
Identifier returns the rule's identifier.
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 ¶
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.
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 ¶
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) SetGlobal ¶
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 ¶
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 ¶
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.
Source Files