You can deploy this model and start earning money today!

error077/
edr-rule-engine

Views

No views yet

🛡️ EDR Rule Engine — MITRE ATT&CK-Mapped Detection System

A production-ready, deterministic rule engine for Endpoint Detection and Response (EDR) systems. Processes real-time process, file, and network events against configurable JSON rules mapped to MITRE ATT&CK techniques.

Designed for integration into hybrid EDR pipelines alongside ML and threat-fusion components.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        RuleEngine                               │
│  ┌──────────────┐  ┌───────────────────┐  ┌──────────────────┐  │
│  │  Rule Loader  │  │ Condition Evaluator│  │  Time Window     │  │
│  │  (JSON→Rule)  │  │  (recursive tree)  │  │  Tracker (sliding│  │
│  └──────┬───────┘  └────────┬──────────┘  │  deque per key)  │  │
│         │                   │              └──────────────────┘  │
│  ┌──────┴───────────────────┴──────────────────────────────┐    │
│  │              Blacklist Manager (O(1) sets)               │    │
│  │          process_names │ ips │ file_hashes               │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
│  Event ──→ evaluate() ──→ Verdict {risk_score, rules, block}    │
└─────────────────────────────────────────────────────────────────┘

Files

File	Description
`rule_engine.py`	Core engine — all classes and evaluation logic
`rules.json`	15 MITRE ATT&CK-mapped detection rules + blacklists
`sample_test.py`	29 test scenarios with realistic attack simulations

Quick Start

python

from rule_engine import RuleEngine, make_event
import json

# Load rules and blacklists
config = json.load(open("rules.json"))
engine = RuleEngine.from_config("rules.json", blacklists=config["blacklists"])

# Evaluate an event
event = make_event("process", {
    "process_name": "mimikatz.exe",
    "command_line": "mimikatz.exe sekurlsa::logonpasswords",
    "parent_process": "cmd.exe",
})

verdict = engine.evaluate(event)
print(f"Risk: {verdict.risk_score}/100")
print(f"Block: {verdict.force_block}")
print(f"Rules: {[r.rule_id for r in verdict.triggered_rules]}")
# Risk: 100.0/100
# Block: True
# Rules: ['RULE-001', 'RULE-015']

Run Tests

bash

python sample_test.py
# 29/29 tests passed ✓

Rule Reference (15 rules)

Rule	MITRE	Event Type	Weight	Block	Description
RULE-001	T1003	process	1.00	✅	Credential dumping tool (blacklisted process)
RULE-002	T1059.001	process	0.80		PowerShell encoded command
RULE-003	T1003.001	process	0.95	✅	LSASS memory access from non-system process
RULE-004	T1071.001	network	1.00	✅	Connection to blacklisted C2 IP
RULE-005	T1071.004	network	0.60		DNS to suspicious TLD / DGA domain
RULE-006	T1105	file	1.00	✅	Blacklisted file hash on disk
RULE-007	T1486	file	0.90	✅	Ransomware file-creation burst (rate-based)
RULE-008	T1053.005	process	0.70		Scheduled task creation (persistence)
RULE-009	T1547.001	file	0.75		Registry Run key modification
RULE-010	T1059.003	network	0.85		Reverse shell indicator (shell→high port)
RULE-011	T1055.001	process	0.90		Process injection (CreateRemoteThread)
RULE-012	T1048.001	network	0.70		Large outbound data transfer (exfiltration)
RULE-013	T1070.001	process	0.85		Event log clearing (anti-forensics)
RULE-014	T1547.001	file	0.70		File dropped in startup folder
RULE-015	T1021.002	process	0.80		PsExec-style lateral movement

Condition Operators

Comparison

equals · not_equals · contains · not_contains · starts_with · ends_with · regex · in_list · greater_than · less_than · exists

Logical

and · or · not

Blacklist

blacklist_process · blacklist_ip · blacklist_hash

Time-based

rate_threshold — triggers when event count exceeds threshold within window

Special

parent_process · command_line_contains

Verdict Format

json

{
  "risk_score": 100.0,
  "triggered_rules": [
    {
      "rule_id": "RULE-001",
      "description": "Credential dumping tool detected",
      "mitre_technique": "T1003",
      "weight": 1.0,
      "force_block": true,
      "explanation": "Process 'mimikatz.exe' is blacklisted"
    }
  ],
  "force_block": true,
  "explanations": ["[RULE-001] Credential dumping tool detected: Process 'mimikatz.exe' is blacklisted"],
  "event_type": "process",
  "timestamp": 1745487396.955
}

Key Features

Thread-safe — BlacklistManager and TimeWindowTracker use locks
Hot-reload — engine.reload_rules() swaps rules without restart
Sliding window — configurable 2–5 min window for rate-based detection
Modular — separate classes for blacklists, time tracking, condition evaluation
Zero ML — fully deterministic, auditable rule matching
Extensible — add new operators by extending ConditionEvaluator

License

MIT

error077/edr-rule-engine