boreal 0.1.0

A library to evaluate YARA rules, used to scan bytes for textual and binary pattern
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

//! Parameters applicable to a scan.

/// Parameters used to configure a scan.
#[derive(Clone, Debug)]
pub struct ScanParams {
    /// Compute full matches on matching rules.
    pub(crate) compute_full_matches: bool,

    /// Max length of the matches returned in matching rules.
    pub(crate) match_max_length: usize,

    /// Max number of matches for a given string.
    pub(crate) string_max_nb_matches: usize,
}

impl Default for ScanParams {
    fn default() -> Self {
        Self {
            compute_full_matches: false,
            match_max_length: 512,
            string_max_nb_matches: 1_000,
        }
    }
}

impl ScanParams {
    /// Compute full matches on matching rules.
    ///
    /// By default, matching rules may not report all of the string matches:
    /// - a rule may match when a variable is found, without needing to find all its matches
    /// - finding out if a regex matches is cheaper than computing the offset and length of its
    ///   matches
    /// - etc
    /// Therefore, the [`crate::scanner::ScanResult`] object may not contain what a user would
    /// expect.
    ///
    /// Setting this parameter to true ensures that for every matching rules, all of the
    /// variable matches are computed and reported.
    #[must_use]
    pub fn compute_full_matches(mut self, compute_full_matches: bool) -> Self {
        self.compute_full_matches = compute_full_matches;
        self
    }

    /// Max length of the matches returned in matching rules.
    ///
    /// This is the max length of [`crate::scanner::StringMatch::data`].
    ///
    /// The default value is `512`.
    #[must_use]
    pub fn match_max_length(mut self, match_max_length: usize) -> Self {
        self.match_max_length = match_max_length;
        self
    }

    /// Max number of matches for a given string.
    ///
    /// Matches that would occur after this value are not reported. This means that `#a` can never
    /// be greater than this value, and `!a[i]` or `@a[i]` where `i` is greater than this value is
    /// always undefined.
    ///
    /// The default value is `1_000`.
    #[must_use]
    pub fn string_max_nb_matches(mut self, string_max_nb_matches: usize) -> Self {
        self.string_max_nb_matches = string_max_nb_matches;
        self
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::test_helpers::test_type_traits;

    #[test]
    fn test_types_traits() {
        test_type_traits(ScanParams::default());
    }
}