wafrift_evolution/
custom_rules.rs

1//! Community-configurable WAF detection and evasion rules.
2
3use serde::Deserialize;
4
5/// A complete custom rules file containing multiple WAF definitions.
6#[derive(Debug, Clone, Deserialize)]
7pub struct CustomRulesFile {
8    /// WAF detection rules.
9    #[serde(default)]
10    pub waf: Vec<CustomWafRule>,
11}
12
13/// A single WAF detection and evasion rule.
14#[derive(Debug, Clone, Deserialize)]
15pub struct CustomWafRule {
16    /// Human-readable WAF name.
17    pub name: String,
18    /// Vendor or product family.
19    #[serde(default)]
20    pub vendor: String,
21    /// HTTP response header signatures.
22    #[serde(default)]
23    pub header_signatures: Vec<HeaderSignature>,
24    /// HTTP response body patterns.
25    #[serde(default)]
26    pub body_signatures: Vec<BodySignature>,
27    /// HTTP status codes that indicate blocking.
28    #[serde(default)]
29    pub block_status_codes: Vec<u16>,
30    /// Recommended evasion strategy names.
31    #[serde(default)]
32    pub evasion_strategies: Vec<String>,
33}
34
35/// A header-based WAF detection signature.
36#[derive(Debug, Clone, Deserialize)]
37pub struct HeaderSignature {
38    /// Header name to check (case-insensitive).
39    pub name: String,
40    /// If present, the header value must contain this substring.
41    #[serde(default)]
42    pub value_contains: Option<String>,
43    /// Detection confidence when this signature matches (0.0–1.0).
44    #[serde(default = "default_confidence")]
45    pub confidence: f64,
46}
47
48/// A body-based WAF detection signature.
49#[derive(Debug, Clone, Deserialize)]
50pub struct BodySignature {
51    /// Substring to search for in the response body (case-insensitive).
52    pub pattern: String,
53    /// Detection confidence when this signature matches (0.0–1.0).
54    #[serde(default = "default_confidence")]
55    pub confidence: f64,
56}
57
58fn default_confidence() -> f64 {
59    0.5
60}
61
62/// Result of matching a custom rule against a response.
63#[derive(Debug, Clone)]
64pub struct CustomDetection {
65    pub rule_name: String,
66    pub vendor: String,
67    pub confidence: f64,
68    pub evasion_strategies: Vec<String>,
69}
70
71/// Build the valid evasion strategy set dynamically from the gene pool.
72fn valid_evasion_strategies() -> Vec<String> {
73    let pool = crate::evolution::GenePool::default_wafrift();
74    // Include encoding values and content-type values as valid strategies
75    let mut values = Vec::new();
76    if let Some(encoding_values) = pool.values_for("encoding") {
77        for v in encoding_values {
78            if v != "None" {
79                values.push(v.clone());
80            }
81        }
82    }
83    if let Some(content_values) = pool.values_for("content_type") {
84        for v in content_values {
85            if v != "None" {
86                values.push(v.clone());
87            }
88        }
89    }
90    if let Some(header_values) = pool.values_for("header_obfuscation") {
91        for v in header_values {
92            if v != "None" {
93                values.push(v.clone());
94            }
95        }
96    }
97    if let Some(grammar_values) = pool.values_for("grammar_rule") {
98        for v in grammar_values {
99            if v != "None" {
100                values.push(v.clone());
101            }
102        }
103    }
104    // Also include common aliases used in TOML rules
105    values.push("Base64Encode".into());
106    values.push("HexEncode".into());
107    values.push("Utf7Encode".into());
108    values.push("Multipart".into());
109    values.push("JsonNested".into());
110    values.push("XmlCdata".into());
111    values
112}
113
114/// Maximum byte length of an accepted custom-rules TOML payload.
115/// Prevents OOM / stack overflow on malicious deeply-nested input
116/// (`toml::from_str` does not enforce a built-in size or depth limit).
117/// 1 MiB is generous for any realistic ruleset.
118const MAX_CUSTOM_RULES_BYTES: usize = 1024 * 1024;
119
120/// Load custom rules from a TOML string. Inputs larger than 1 MiB are
121/// rejected before parsing to bound memory + parse time.
122pub fn load_rules(toml_str: &str) -> std::result::Result<CustomRulesFile, String> {
123    if toml_str.len() > MAX_CUSTOM_RULES_BYTES {
124        return Err(format!(
125            "custom rules TOML rejected: {} bytes exceeds maximum of {} bytes",
126            toml_str.len(),
127            MAX_CUSTOM_RULES_BYTES
128        ));
129    }
130    let rules: CustomRulesFile =
131        toml::from_str(toml_str).map_err(|e| format!("failed to parse custom rules TOML: {e}"))?;
132    validate_rules(&rules)?;
133    validate_evasion_strategies(&rules)?;
134    Ok(rules)
135}
136
137fn validate_rules(rules: &CustomRulesFile) -> std::result::Result<(), String> {
138    for (idx, waf) in rules.waf.iter().enumerate() {
139        if waf.name.trim().is_empty() {
140            return Err(format!(
141                "validation error: waf[{idx}] missing required field 'name'"
142            ));
143        }
144        for (sig_idx, sig) in waf.header_signatures.iter().enumerate() {
145            if sig.name.trim().is_empty() {
146                return Err(format!(
147                    "validation error: waf[{idx}].header_signatures[{sig_idx}] missing required field 'name'"
148                ));
149            }
150            if !(0.0..=1.0).contains(&sig.confidence) {
151                return Err(format!(
152                    "validation error: waf[{}].header_signatures[{}] confidence must be between 0.0 and 1.0, got {}",
153                    idx, sig_idx, sig.confidence
154                ));
155            }
156        }
157        for (sig_idx, sig) in waf.body_signatures.iter().enumerate() {
158            if sig.pattern.trim().is_empty() {
159                return Err(format!(
160                    "validation error: waf[{idx}].body_signatures[{sig_idx}] missing required field 'pattern'"
161                ));
162            }
163            if !(0.0..=1.0).contains(&sig.confidence) {
164                return Err(format!(
165                    "validation error: waf[{}].body_signatures[{}] confidence must be between 0.0 and 1.0, got {}",
166                    idx, sig_idx, sig.confidence
167                ));
168            }
169        }
170        for code in &waf.block_status_codes {
171            if *code == 0 || *code > 999 {
172                return Err(format!(
173                    "validation error: waf[{idx}] invalid status code {code} (must be 1-999)"
174                ));
175            }
176        }
177    }
178    Ok(())
179}
180
181fn validate_evasion_strategies(rules: &CustomRulesFile) -> std::result::Result<(), String> {
182    let valid = valid_evasion_strategies();
183    let mut unknown_strategies: Vec<(usize, String)> = Vec::new();
184    for (waf_idx, waf) in rules.waf.iter().enumerate() {
185        for strategy in &waf.evasion_strategies {
186            if !valid.contains(strategy) {
187                unknown_strategies.push((waf_idx, strategy.clone()));
188            }
189        }
190    }
191    if !unknown_strategies.is_empty() {
192        let errors: Vec<String> = unknown_strategies
193            .into_iter()
194            .map(|(idx, s)| format!("waf[{idx}]: unknown evasion_strategy '{s}'"))
195            .collect();
196        return Err(format!(
197            "validation error: invalid evasion_strategies found:\n  - {}",
198            errors.join("\n  - ")
199        ));
200    }
201    Ok(())
202}
203
204/// Load custom rules from a file path.
205pub fn load_rules_from_file(
206    path: &std::path::Path,
207) -> std::result::Result<CustomRulesFile, String> {
208    let content = std::fs::read_to_string(path)
209        .map_err(|e| format!("failed to read rules file {}: {}", path.display(), e))?;
210    load_rules(&content)
211}
212
213/// Match custom rules against an HTTP response.
214#[must_use]
215pub fn detect(
216    rules: &CustomRulesFile,
217    status: u16,
218    headers: &[(String, String)],
219    body: &[u8],
220) -> Option<CustomDetection> {
221    let body_str = String::from_utf8_lossy(&body[..body.len().min(4096)]).to_ascii_lowercase();
222    let mut best: Option<CustomDetection> = None;
223    for rule in &rules.waf {
224        let mut max_confidence: f64 = 0.0;
225        let mut matched = false;
226        if rule.block_status_codes.contains(&status) {
227            max_confidence = max_confidence.max(0.3);
228            matched = true;
229        }
230        for sig in &rule.header_signatures {
231            let header_match = headers.iter().any(|(name, value)| {
232                if !name.eq_ignore_ascii_case(&sig.name) {
233                    return false;
234                }
235                match &sig.value_contains {
236                    Some(substring) => value
237                        .to_ascii_lowercase()
238                        .contains(&substring.to_ascii_lowercase()),
239                    None => true,
240                }
241            });
242            if header_match {
243                max_confidence = max_confidence.max(sig.confidence);
244                matched = true;
245            }
246        }
247        for sig in &rule.body_signatures {
248            if body_str.contains(&sig.pattern.to_ascii_lowercase()) {
249                max_confidence = max_confidence.max(sig.confidence);
250                matched = true;
251            }
252        }
253        if matched && max_confidence > best.as_ref().map_or(0.0, |b| b.confidence) {
254            best = Some(CustomDetection {
255                rule_name: rule.name.clone(),
256                vendor: rule.vendor.clone(),
257                confidence: max_confidence,
258                evasion_strategies: rule.evasion_strategies.clone(),
259            });
260        }
261    }
262    best
263}
264
265#[cfg(test)]
266mod tests {
267    use super::*;
268
269    const SAMPLE_TOML: &str = r#"
270[[waf]]
271name = "TestWAF"
272vendor = "test-vendor"
273block_status_codes = [403, 406]
274evasion_strategies = ["DoubleUrlEncode", "SqlCommentInsertion"]
275
276[[waf.header_signatures]]
277name = "x-test-waf"
278confidence = 0.9
279
280[[waf.header_signatures]]
281name = "server"
282value_contains = "TestWAF"
283confidence = 0.8
284
285[[waf.body_signatures]]
286pattern = "Blocked by TestWAF"
287confidence = 0.95
288
289[[waf]]
290name = "AnotherWAF"
291vendor = "another"
292block_status_codes = [429]
293evasion_strategies = ["CaseAlternation"]
294
295[[waf.header_signatures]]
296name = "x-another-waf"
297confidence = 0.7
298"#;
299
300    #[test]
301    fn load_rules_basic() {
302        let rules = load_rules(SAMPLE_TOML).expect("should parse");
303        assert_eq!(rules.waf.len(), 2);
304        assert_eq!(rules.waf[0].name, "TestWAF");
305        assert_eq!(rules.waf[0].header_signatures.len(), 2);
306        assert_eq!(rules.waf[0].body_signatures.len(), 1);
307        assert_eq!(rules.waf[0].block_status_codes, vec![403, 406]);
308        assert_eq!(rules.waf[0].evasion_strategies.len(), 2);
309    }
310
311    #[test]
312    fn load_rules_empty() {
313        let rules = load_rules("").expect("empty should parse");
314        assert!(rules.waf.is_empty());
315    }
316
317    #[test]
318    fn load_rules_invalid_toml() {
319        let result = load_rules("this is not { valid toml");
320        assert!(result.is_err());
321    }
322
323    #[test]
324    fn detect_by_header() {
325        let rules = load_rules(SAMPLE_TOML).expect("should parse");
326        let headers = vec![("x-test-waf".into(), "active".into())];
327        let result = detect(&rules, 200, &headers, b"OK");
328        assert!(result.is_some());
329        let det = result.unwrap();
330        assert_eq!(det.rule_name, "TestWAF");
331        assert!((det.confidence - 0.9).abs() < 0.01);
332    }
333
334    #[test]
335    fn detect_by_body() {
336        let rules = load_rules(SAMPLE_TOML).expect("should parse");
337        let headers: Vec<(String, String)> = vec![];
338        let body = b"Error: Blocked by TestWAF engine";
339        let result = detect(&rules, 200, &headers, body);
340        assert!(result.is_some());
341        let det = result.unwrap();
342        assert_eq!(det.rule_name, "TestWAF");
343        assert!((det.confidence - 0.95).abs() < 0.01);
344    }
345
346    #[test]
347    fn detect_by_status() {
348        let rules = load_rules(SAMPLE_TOML).expect("should parse");
349        let headers: Vec<(String, String)> = vec![];
350        let result = detect(&rules, 403, &headers, b"");
351        assert!(result.is_some());
352        assert_eq!(result.unwrap().rule_name, "TestWAF");
353    }
354
355    #[test]
356    fn detect_no_match() {
357        let rules = load_rules(SAMPLE_TOML).expect("should parse");
358        let headers = vec![("server".into(), "nginx".into())];
359        let result = detect(&rules, 200, &headers, b"Welcome");
360        assert!(result.is_none());
361    }
362
363    #[test]
364    fn dynamic_strategy_validation_accepts_content_type_genes() {
365        let toml = r#"
366[[waf]]
367name = "Test"
368evasion_strategies = ["Multipart", "JsonNested"]
369"#;
370        let rules = load_rules(toml);
371        assert!(
372            rules.is_ok(),
373            "Multipart and JsonNested should be valid strategies"
374        );
375    }
376
377    #[test]
378    fn dynamic_strategy_validation_accepts_grammar_genes() {
379        let toml = r#"
380[[waf]]
381name = "Test"
382evasion_strategies = ["tautology_swap", "comment_swap"]
383"#;
384        let rules = load_rules(toml);
385        assert!(rules.is_ok(), "Grammar genes should be valid strategies");
386    }
387
388    #[test]
389    fn load_rules_rejects_oversized_payload() {
390        let huge = "x".repeat(1024 * 1024 + 1);
391        let result = load_rules(&huge);
392        assert!(result.is_err(), "should reject >1 MiB input");
393        let msg = result.unwrap_err();
394        assert!(msg.contains("exceeds maximum"), "error should mention size limit: {msg}");
395    }
396
397    #[test]
398    fn load_rules_rejects_empty_waf_name() {
399        let toml = r#"
400[[waf]]
401name = "   "
402"#;
403        let result = load_rules(toml);
404        assert!(result.is_err(), "should reject empty/whitespace name");
405    }
406
407    #[test]
408    fn load_rules_rejects_invalid_confidence_high() {
409        let toml = r#"
410[[waf]]
411name = "Test"
412[[waf.header_signatures]]
413name = "X-Block"
414confidence = 1.5
415"#;
416        let result = load_rules(toml);
417        assert!(result.is_err(), "should reject confidence > 1.0");
418    }
419
420    #[test]
421    fn load_rules_rejects_invalid_confidence_negative() {
422        let toml = r#"
423[[waf]]
424name = "Test"
425[[waf.header_signatures]]
426name = "X-Block"
427confidence = -0.1
428"#;
429        let result = load_rules(toml);
430        assert!(result.is_err(), "should reject negative confidence");
431    }
432
433    #[test]
434    fn load_rules_rejects_invalid_status_code_zero() {
435        let toml = r#"
436[[waf]]
437name = "Test"
438block_status_codes = [0]
439"#;
440        let result = load_rules(toml);
441        assert!(result.is_err(), "should reject status code 0");
442    }
443
444    #[test]
445    fn load_rules_rejects_invalid_status_code_too_high() {
446        let toml = r#"
447[[waf]]
448name = "Test"
449block_status_codes = [1000]
450"#;
451        let result = load_rules(toml);
452        assert!(result.is_err(), "should reject status code > 999");
453    }
454
455    #[test]
456    fn load_rules_rejects_unknown_evasion_strategy() {
457        let toml = r#"
458[[waf]]
459name = "Test"
460evasion_strategies = ["DefinitelyNotRealStrategy123"]
461"#;
462        let result = load_rules(toml);
463        assert!(result.is_err(), "should reject unknown evasion strategy");
464        let msg = result.unwrap_err();
465        assert!(msg.contains("unknown evasion_strategy"), "error should name the strategy: {msg}");
466    }
467
468    #[test]
469    fn load_rules_rejects_empty_body_pattern() {
470        let toml = r#"
471[[waf]]
472name = "Test"
473[[waf.body_signatures]]
474pattern = "   "
475"#;
476        let result = load_rules(toml);
477        assert!(result.is_err(), "should reject empty/whitespace body pattern");
478    }
479
480    #[test]
481    fn load_rules_rejects_empty_header_name() {
482        let toml = r#"
483[[waf]]
484name = "Test"
485[[waf.header_signatures]]
486name = "   "
487"#;
488        let result = load_rules(toml);
489        assert!(result.is_err(), "should reject empty/whitespace header name");
490    }
491}
wafrift_evolution/custom_rules.rs

wafrift_evolution/
custom_rules.rs
