shapash 0.1.15

A deterministic, auditable forward-chaining rule engine with pluggable scoring
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
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147

# Shapash — Deterministic Rule Engine

[![Crates.io](https://img.shields.io/crates/v/shapash.svg)](https://crates.io/crates/shapash)
[![Documentation](https://docs.rs/shapash/badge.svg)](https://docs.rs/shapash)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

Shapash is a deterministic, auditable forward-chaining rule engine designed for security analysis, compliance workflows, and intelligent automation.

## Features

- **Deterministic Evaluation**: Stable rule ordering and reproducible results
- **HEL Integration**: Uses [HEL (Heuristics Expression Language)](https://crates.io/crates/hel) for rule conditions
- **Pluggable Scoring**: Trait-based scoring models for custom risk calculations
- **TOML Rule Format**: Clean `.rule` files with inline or external HEL conditions
- **ONNX Model Support**: Optional ML model integration for advanced scoring
- **Audit Trails**: Per-rule evaluation traces for compliance

## Quick Start

### Define Rules (TOML)

Create a `.rule` file:

```toml
[[rule]]
id = "high-risk-taint"
description = "Dangerous taint flow detected"
condition = 'TaintFlow.sink == "strcpy"'  # Inline HEL
score = 75
justification = "strcpy is unsafe with untrusted input"

[[rule]]
id = "security-check"
description = "Complex security validation"
condition_file = "conditions/nx-check.hel"  # External HEL script
score = 85
justification = "NX protection should be enabled"
```

### Evaluate Rules

```rust
use shapash::{HeuristicEngine, Fact, TaintFlow};
use std::collections::HashSet;

// Load rules from .rule files
let engine = HeuristicEngine::from_paths("rules/", None)?;

// Provide facts for evaluation
let mut facts = HashSet::new();
facts.insert(Fact::TaintFlow(TaintFlow {
    source: "network".into(),
    sink: "strcpy".into(),
}));

// Execute rule engine
let report = engine.execute(facts);

println!("Final Score: {}", report.final_score);
for rule in &report.triggered_rules {
    println!("  ✓ {}: {}", rule.rule_id, rule.description);
}
```

### Custom Scoring Models

Implement your own scoring logic:

```rust
use shapash::{ScoringModel, TriggeredRuleInfo};

struct CustomScorer;

impl ScoringModel for CustomScorer {
    fn score(&self, triggered: &[TriggeredRuleInfo]) -> u32 {
        // Custom scoring algorithm
        triggered.iter().map(|r| r.score).max().unwrap_or(0)
    }
}

let report = engine.execute_with_scorer(facts, &CustomScorer)?;
```

## Rule File Format

Rules support both inline and external HEL conditions:

### Inline Condition

```toml
[[rule]]
id = "example"
condition = 'binary.arch == "x86_64" AND security.nx == false'
score = 50
justification = "..."
description = "..."
```

### External Condition File

```toml
[[rule]]
id = "example"
condition_file = "conditions/android-malware.hel"
score = 90
justification = "..."
description = "..."
```

File: `conditions/android-malware.hel`

```hel
let has_sms = manifest.permissions CONTAINS "READ_SMS"
let obfuscated = binary.entropy > 7.5

has_sms AND obfuscated
```

## Architecture

```
┌─────────────────────────────────────────────┐
│ Shapash                                     │
│ • Rule orchestration                        │
│ • Fact management                           │
│ • Scoring coordination                      │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│ HEL (external crate)                        │
│ • Expression evaluation                     │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│ Products                                     │
│ • Inject domain-specific facts              │
│ • Custom scoring models                     │
└─────────────────────────────────────────────┘
```

## Example

See `examples/c01-simple-pipeline.rs` for a complete working example.

## License

Apache-2.0. See LICENSE for details.