Struct Scanner 

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

Scans data in blocks

This scanner is designed for scenarios where the data to be scanned is not available as a single contiguous block of memory, but rather arrives in smaller, discrete blocks, allowing for incremental scanning.

Examples

let rules = compile(r#"rule test { strings: $a = "abc" condition: $a }"#).unwrap();

let mut scanner = blocks::Scanner::new(&rules);

// Scan the first block of data.
scanner.scan(0, b"xabcy").unwrap();

// Scan a second block of data, which can overlap with the first.
scanner.scan(3, b"cyz").unwrap();

// Finish the scan and get the results.
let results = scanner.finish().unwrap();

assert_eq!(results.matching_rules().len(), 1);

Limitations of Block Scanning

Block scanning works by analyzing data in chunks rather than as a whole file. This makes it useful for streaming or memory-constrained scenarios, but it comes with important limitations compared to standard scanning:

1. Modules won’t work. Parsers for structured formats (e.g., PE, ELF) require access to the entire file and cannot be applied in block scanning mode.
2. Other modules like hash won’t work either, as they require access to all the scanned data during the evaluation of the rule’s condition, something that can’t be guaranteed in block scanning mode. The hash functions will return undefined when used in a multi-block context.
3. Built-in functions like uint8, uint16, uint32, etc., have the same limitation. They also return undefined in block scanning mode.
4. The filesize keyword returns undefined in block scanning mode.
5. Patterns won’t match across block boundaries. Every match will be completely contained within one of the blocks.

All these limitations imply that in block scanning mode you should only use rules that rely on text, hex or regex patterns.

Data Consistency in Overlapping Blocks

When Scanner::scan is invoked multiple times with different blocks that may overlap, the user is responsible for ensuring data consistency. This means that if the same region of the original data is present in two or more overlapping blocks, the content of that region must be identical across all calls to this function.

Generally speaking, the scanner does not verify this consistency and assumes the user provides accurate and consistent data. In debug releases the scanner may try to verify this consistency, but only when some pattern matches in the overlapping region.

Implementations

impl<'r> Scanner<'r>

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

Creates a new block scanner.

pub fn match_context_size(&mut self, size: usize) -> &mut Self

Sets the context size for matches.

This specifies how many bytes at the left and right of each match will be reported by crate::Match::data_with_context. By default, the match context size is 0, which means that crate::Match::data_with_context will return exactly the same data as crate::Match::data.

impl<'r> Scanner<'r>

pub fn scan(&mut self, base: usize, data: &[u8]) -> Result<&mut Self, ScanError>

Scans a block of data.

This method processes a given block of data, searching for patterns defined in the YARA rules. The base argument specifies the offset of the current block within the overall data being scanned. In most cases you will want to call this method multiple times, providing a different block on each call.

Arguments

• base - The starting offset of the data block within overall data being scanned.
• data - The byte slice representing the current block of data to scan.

Returns

A Result indicating success or a ScanError if the scan operation fails.

pub fn finish(&mut self) -> Result<ScanResults<'_, 'r>, ScanError>

Finalizes the scanning process.

After all data blocks have been scanned, this method evaluates the conditions of the YARA rules and produces the final scan results.

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_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 fast_scan(&mut self, yes: bool) -> &mut Self

Enables or disables fast scan mode.

In fast scan mode, the scanner avoids tracking matches for patterns when it is not necessary (e.g. when a rule condition only performs a simple boolean check $a).

Note that using fast scan mode implies that not all matches will be reported. For instance, when iterating matches using ScanResults, you won’t get all occurrences of the pattern in the file, only the first one.

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 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 crate::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.