Struct Scanner 

pub struct Scanner<'r> { /* private fields */ }

Scans data with already compiled YARA rules.

The scanner receives a set of compiled Rules and scans data with those rules. The same scanner can be used for scanning multiple files or in-memory data sequentially, but you need multiple scanners for scanning in parallel.

Implementations

impl<'r> Scanner<'r>

pub fn new(rules: &'r Rules) -> Self

Creates a new scanner.

pub fn set_timeout(&mut self, timeout: Duration) -> &mut Self

Sets a timeout for scan operations.

The scan functions will return an ScanError::Timeout 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.

pub fn max_matches_per_pattern(&mut self, n: usize) -> &mut Self

Sets the maximum number of matches per pattern.

When some pattern reaches the maximum number of patterns it won’t produce more matches.

pub fn use_mmap(&mut self, yes: bool) -> &mut Self

Specifies whether Scanner::scan_file and Scanner::scan_file_with_options may use memory-mapped files to read input.

By default, the scanner uses memory mapping for very large files, as this is typically faster than copying file contents into memory. However, this approach has a drawback: if another process truncates the file during scanning, a SIGBUS signal may occur.

Setting this option disables memory mapping and forces the scanner to always read files into an in-memory buffer instead. This method is slower, but safer.

pub fn console_log<F>(&mut self, callback: F) -> &mut Self

where F: FnMut(String) + 'r,

Sets a callback that is invoked every time a YARA rule calls the console module.

The callback function is invoked with a string representing the message being logged. The function can print the message to stdout, append it to a file, etc. If no callback is set these messages are ignored.

pub fn scan<'a>( &'a mut self, data: &'a [u8], ) -> Result<ScanResults<'a, 'r>, ScanError>

Scans in-memory data.

pub fn scan_file<'a, P>( &'a mut self, target: P, ) -> Result<ScanResults<'a, 'r>, ScanError>

where P: AsRef<Path>,

Scans a file.

pub fn scan_with_options<'a, 'opts>( &'a mut self, data: &'a [u8], options: ScanOptions<'opts>, ) -> Result<ScanResults<'a, 'r>, ScanError>

Like Scanner::scan, but allows to specify additional scan options.

pub fn scan_file_with_options<'opts, P>( &mut self, target: P, options: ScanOptions<'opts>, ) -> Result<ScanResults<'_, 'r>, ScanError>

where P: AsRef<Path>,

Like Scanner::scan_file, but allows to specify additional scan options.

pub fn set_global<T: TryInto<Variable>>( &mut self, ident: &str, value: T, ) -> Result<&mut Self, VariableError>

where VariableError: From<<T as TryInto<Variable>>::Error>,

Sets the value of a global variable.

The variable must has been previously defined by calling crate::Compiler::define_global, and the type it has during the definition must match the type of the new value (T).

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

pub fn set_module_output( &mut self, data: Box<dyn MessageDyn>, ) -> Result<&mut Self, ScanError>

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 message. 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 Scanner::set_module_output 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.

pub fn set_module_output_raw( &mut self, name: &str, data: &[u8], ) -> Result<&mut Self, ScanError>

Similar to Scanner::set_module_output, but receives a module name and the protobuf message as raw data.

name can be either the YARA module name (i.e: “pe”, “elf”, “dotnet”, etc.) or the fully-qualified name for the protobuf message associated to the module (i.e: “pe.PE”, “elf.ELF”, “dotnet.Dotnet”, etc.).

pub fn slowest_rules(&self, n: usize) -> Vec<ProfilingData<'_>>

Available on crate feature rules-profiling only.

Returns profiling data for the slowest N rules.

The profiling data reflects the cumulative execution time of each rule across all scanned files. This information is useful for identifying performance bottlenecks. To reset the profiling data and start fresh for subsequent scans, use Scanner::clear_profiling_data.

pub fn clear_profiling_data(&mut self)

Available on crate feature rules-profiling only.

Clears all accumulated profiling data.

This method resets the profiling data collected during rule execution across scanned files. Use this to start a new profiling session, ensuring the results reflect only the data gathered after this method is called.

Trait Implementations

impl<'r> From<Scanner<'r>> for Scanner<'r>

fn from(scanner: Scanner<'r>) -> Self

Converts to this type from the input type.