Merge pull request #32 from Quad9DNS/feature/cidr-rule

Add CIDR rule

Author: esensar

Cargo.lock

@@ -24,6 +24,7 @@ criterion = { version = "0.5.1" }
 exitcode = { version = "1.1.2" }
 futures = { version = "0.3.31" }
 hashbrown = { version = "0.16.1" }
+ipnet = { version = "2.12.0" }
 lazy_static = { version = "1.5.0" }
 metrics = { version = "0.24.2" }
 metrics-exporter-prometheus = { version = "0.17.0" }

Cargo.toml

@@ -47,6 +47,7 @@ Stringsimile supports different inputs, outputs and rules to use when comparing
 - Match Rating
 - Bitflip
 - Regex
+- CIDR
 
 Check out the [example rules file](./distribution/rules/example.json) to see how they can be defined. You can also check out the included man pages (`man 5 stringsimile-rule-config`).
 

README.md

@@ -23,7 +23,7 @@ const INPUT_DATA: &[u8] =
 "#;
 
 const RULES_DATA: &[u8] = br#"
-{ "name": "Example string group", "rule_sets": [ { "name": "Test rule set", "string_match": "test", "preprocessors": [ { "preprocessor_type": "split_target", "ignore_tld": true } ], "match_rules": [ { "rule_type": "levenshtein", "values": { "maximum_distance": 3 } }, { "rule_type": "hamming", "values": { "maximum_distance": 3 } }, { "rule_type": "soundex", "values": { "minimum_similarity": 3 } }, { "rule_type": "metaphone", "values": { "max_code_length": 3 } }, { "rule_type": "nysiis", "values": { "strict": true } }, { "rule_type": "jaro", "values": { "match_percent_threshold": 0.85 } }, { "rule_type": "jaro_winkler", "values": { "match_percent_threshold": 0.85 } }, { "rule_type": "confusables" }, { "rule_type": "match_rating" }, { "rule_type": "damerau_levenshtein", "values": { "maximum_distance": 3 } } ] }, { "name": "Example rule set", "split_target": true, "ignore_tld": true, "string_match": "example", "match_rules": [ { "rule_type": "levenshtein", "values": { "maximum_distance": 3 } }, { "rule_type": "jaro", "values": { "match_percent_threshold": 0.85 } }, { "rule_type": "bitflip" }, { "rule_type": "regex", "values": { "pattern": "test" } } ] } ] }
+{ "name": "Example string group", "rule_sets": [ { "name": "Test rule set", "string_match": "test", "preprocessors": [ { "preprocessor_type": "split_target", "ignore_tld": true } ], "match_rules": [ { "rule_type": "levenshtein", "values": { "maximum_distance": 3 } }, { "rule_type": "hamming", "values": { "maximum_distance": 3 } }, { "rule_type": "soundex", "values": { "minimum_similarity": 3 } }, { "rule_type": "metaphone", "values": { "max_code_length": 3 } }, { "rule_type": "nysiis", "values": { "strict": true } }, { "rule_type": "jaro", "values": { "match_percent_threshold": 0.85 } }, { "rule_type": "jaro_winkler", "values": { "match_percent_threshold": 0.85 } }, { "rule_type": "confusables" }, { "rule_type": "match_rating" }, { "rule_type": "damerau_levenshtein", "values": { "maximum_distance": 3 } } ] }, { "name": "Example rule set", "split_target": true, "ignore_tld": true, "string_match": "example", "match_rules": [ { "rule_type": "levenshtein", "values": { "maximum_distance": 3 } }, { "rule_type": "jaro", "values": { "match_percent_threshold": 0.85 } }, { "rule_type": "bitflip" }, { "rule_type": "regex", "values": { "pattern": "test" } }, { "rule_type": "cidr", "values": { "address": "192.168.0.0/24" } } ] } ] }
 "#;
 
 #[test]

bin/stringsimile-service/tests/basic_file_test.rs

@@ -9,6 +9,7 @@ version.workspace = true
 stringsimile-matcher.workspace = true
 
 hashbrown.workspace = true
+ipnet.workspace = true
 regex.workspace = true
 serde = { workspace = true, features = ["derive"] }
 serde_json.workspace = true

crates/stringsimile-config/Cargo.toml

@@ -7,6 +7,7 @@ use stringsimile_matcher::{
     rule::{GenericMatcherRule, IntoGenericMatcherRule},
     rules::{
         bitflip::BitflipRule,
+        cidr::CidrRule,
         confusables::ConfusablesRule,
         damerau_levenshtein::DamerauLevenshteinRule,
         hamming::HammingRule,
@@ -49,6 +50,8 @@ pub enum RuleConfig {
     Bitflip(Option<BitflipConfig>),
     /// Configuration for Regex rule
     Regex(RegexConfig),
+    /// Configuration for CIDR rule
+    Cidr(CidrConfig),
 }
 
 /// Errors for rule configuration
@@ -109,6 +112,13 @@ pub enum RuleConfigError {
         /// Regex error.
         source: regex::Error,
     },
+
+    /// CIDR rule configuration error
+    #[snafu(display("Invalid address for CIDR rule: {}", source))]
+    CidrInvalidAddress {
+        /// Address parse error.
+        source: ipnet::AddrParseError,
+    },
 }
 
 impl RuleConfig {
@@ -160,6 +170,7 @@ impl RuleConfig {
             RuleConfig::Regex(regex_config) => {
                 Box::new(regex_config.build()?.into_generic_matcher())
             }
+            RuleConfig::Cidr(cidr_config) => Box::new(cidr_config.build()?.into_generic_matcher()),
         })
     }
 }
@@ -450,6 +461,21 @@ impl RegexConfig {
     }
 }
 
+/// Configuration for CIDR rule
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CidrConfig {
+    /// CIDR notation address to match against.
+    pub address: String,
+}
+
+impl CidrConfig {
+    fn build(&self) -> Result<CidrRule, Error> {
+        Ok(CidrRule::new(
+            self.address.parse().context(CidrInvalidAddressSnafu)?,
+        ))
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -871,4 +897,44 @@ mod tests {
         let res = config.build();
         assert!(res.is_err());
     }
+
+    #[test]
+    fn test_parse_cidr() {
+        let json = r#"
+        {
+            "rule_type": "cidr",
+            "values": {
+                "address": "192.168.0.0/24"
+            }
+        }
+            "#;
+
+        let RuleConfig::Cidr(config) = serde_json::from_str(json).unwrap() else {
+            panic!("Expected CIDR config");
+        };
+        assert_eq!(config.address, "192.168.0.0/24");
+
+        let res = config.build();
+        assert!(res.is_ok());
+    }
+
+    #[test]
+    fn test_parse_cidr_invalid_address() {
+        let json = r#"
+        {
+            "rule_type": "cidr",
+            "values": {
+                "address": "test"
+            }
+        }
+            "#;
+
+        let RuleConfig::Cidr(config) = serde_json::from_str(json).unwrap() else {
+            panic!("Expected CIDR config");
+        };
+        assert_eq!(config.address, "test");
+
+        let res = config.build();
+        assert!(res.is_err());
+    }
 }

crates/stringsimile-config/src/rules.rs

@@ -7,8 +7,9 @@ version.workspace = true
 
 [features]
 default = ["all"]
-all = ["rules-levenshtein", "rules-hamming", "rules-jaro", "rules-jaro-winkler", "rules-confusables", "rules-damerau-levenshtein", "rules-soundex", "rules-metaphone", "rules-nysiis", "rules-match-rating", "rules-bitflip", "rules-regex"]
+all = ["rules-levenshtein", "rules-hamming", "rules-jaro", "rules-jaro-winkler", "rules-confusables", "rules-damerau-levenshtein", "rules-soundex", "rules-metaphone", "rules-nysiis", "rules-match-rating", "rules-bitflip", "rules-regex", "rules-cidr"]
 rules-bitflip = ["dep:lazy_static"]
+rules-cidr = ["dep:ipnet"]
 rules-confusables = ["dep:confusables"]
 rules-damerau-levenshtein = ["dep:triple_accel"]
 rules-hamming = ["dep:triple_accel"]
@@ -24,6 +25,7 @@ rules-soundex = ["dep:rphonetic"]
 [dependencies]
 confusables = { workspace = true, optional = true }
 hashbrown.workspace = true
+ipnet = { workspace = true, optional = true }
 lazy_static = { workspace = true, optional = true }
 metrics.workspace = true
 regex = { workspace = true, optional = true }

crates/stringsimile-matcher/Cargo.toml

@@ -4,6 +4,7 @@ use stringsimile_matcher::{
     rule::MatcherRule,
     rules::{
         bitflip::BitflipRule,
+        cidr::CidrRule,
         confusables::ConfusablesRule,
         damerau_levenshtein::DamerauLevenshteinRule,
         hamming::HammingRule,
@@ -350,6 +351,15 @@ bench_rule! {
     }
 }
 
+bench_rule! {
+    name = cidr;
+    single_match = "192.168.0.1";
+    single_mismatch = "192.168.1.1";
+    builder {
+        CidrRule::new("192.168.0.0/24".parse().unwrap())
+    }
+}
+
 criterion_group!(
     benches,
     confusables,
@@ -373,5 +383,6 @@ criterion_group!(
     bitflip_ascii_printable_case_insensitive,
     regex_exact_match,
     regex_complex_pattern,
+    cidr,
 );
 criterion_main!(benches);

crates/stringsimile-matcher/benches/rules.rs

@@ -5,6 +5,7 @@ use stringsimile_matcher::{
     rule::IntoGenericMatcherRule,
     rules::{
         bitflip::BitflipRule,
+        cidr::CidrRule,
         confusables::ConfusablesRule,
         damerau_levenshtein::DamerauLevenshteinRule,
         hamming::HammingRule,
@@ -204,6 +205,7 @@ bench_ruleset! {
                     Box::new(SoundexRule::new(SoundexRuleType::Refined, 5, target_str).into_generic_matcher()),
                     Box::new(BitflipRule::new_dns(target_str, true)),
                     Box::new(RegexRule::new(Regex::new(target_str).unwrap())),
+                    Box::new(CidrRule::new("192.168.0.0/24".parse().unwrap())),
                 ]
             }])
         }
@@ -237,6 +239,7 @@ bench_ruleset! {
                     Box::new(SoundexRule::new(SoundexRuleType::Refined, 5, target_str).into_generic_matcher()),
                     Box::new(BitflipRule::new_dns(target_str, true)),
                     Box::new(RegexRule::new(Regex::new(target_str).unwrap())),
+                    Box::new(CidrRule::new("192.168.0.0/24".parse().unwrap())),
                 ]
             }])
         }
@@ -270,6 +273,7 @@ bench_ruleset! {
                     Box::new(SoundexRule::new(SoundexRuleType::Refined, 5, target_str).into_generic_matcher()),
                     Box::new(BitflipRule::new_dns(target_str, true)),
                     Box::new(RegexRule::new(Regex::new(target_str).unwrap())),
+                    Box::new(CidrRule::new("192.168.0.0/24".parse().unwrap())),
                 ]
             }])
         }

crates/stringsimile-matcher/benches/rulesets.rs

@@ -0,0 +1,71 @@
+//! CIDR rule implementation
+
+use ipnet::IpNet;
+use std::{fmt::Debug, io::Error, net::IpAddr};
+
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    MatcherResult,
+    rule::{MatcherResultRuleMetadataExt, MatcherRule, RuleMetadata},
+};
+
+/// Rule
+#[derive(Debug, Clone)]
+pub struct CidrRule {
+    net: IpNet,
+}
+
+impl CidrRule {
+    /// Creates a new instance of [`CidrRule`], with the provided address/network.
+    pub fn new(net: IpNet) -> Self {
+        Self { net }
+    }
+}
+
+/// metadata
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CidrMetadata;
+
+impl MatcherRule for CidrRule {
+    type OutputMetadata = CidrMetadata;
+    type Error = Error;
+
+    fn match_rule(
+        &self,
+        input_str: &str,
+        _target_str: &str,
+    ) -> MatcherResult<Self::OutputMetadata, Self::Error> {
+        let Ok(addr) = input_str.parse::<IpAddr>() else {
+            return MatcherResult::new_no_match(CidrMetadata);
+        };
+        if self.net.contains(&addr) {
+            MatcherResult::new_match(CidrMetadata)
+        } else {
+            MatcherResult::new_no_match(CidrMetadata)
+        }
+    }
+}
+
+impl RuleMetadata for CidrMetadata {
+    const RULE_NAME: &str = "cidr";
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::rule::MatcherResultExt;
+
+    use super::*;
+
+    #[test]
+    fn simple_example() {
+        let rule = CidrRule::new("192.168.0.0/24".parse().unwrap());
+
+        let result = rule.match_rule("192.168.0.1", "whatever");
+        assert!(result.is_match());
+        let result = rule.match_rule("192.168.0.30", "whatever");
+        assert!(result.is_match());
+        let result = rule.match_rule("192.168.1.30", "whatever");
+        assert!(!result.is_match());
+    }
+}