Behavior anomaly guard for applications.
Pattern-Guard is a Rust-native behavior anomaly guard that detects unusual application behavior and recommends allow/warn/delay/block decisions—a signal generator, not a gatekeeper.
- Repository:
pattern-guard
- Problem Statement
- Solution Overview
- Core Concept
- Event Model
- Responsibilities & Scope
- System Architecture
- Integration Model
- Configuration Philosophy
- Why Rust
- Who it's for
- Long-Term Vision
- More docs
- Quick start
- One-Sentence Definition
Modern backends, scripts, and services are protected mostly by rate limiters and static rules.
These protections fail when:
- Abuse happens under rate limits
- Bots mimic human-like request counts
- Internal scripts or cron jobs misbehave
- Bugs cause repeated or looping behavior
- Systems waste CPU, DB, or money before alarms trigger
Today, developers repeatedly re-implement:
- Burst checks
- Strange pattern detection
- Ad-hoc guards in handlers
- Custom logic per project
There isn’t a general, reusable behavior-level guard in the Rust ecosystem yet. I built this as a small contribution, hoping it might help someone or spark further ideas. If even one person finds it useful, I’d consider that a success.
Pattern-Guard is a behavior anomaly detection and decision engine that sits inside or in front of application logic and answers:
Is this behavior normal right now?
It does not inspect payloads, authenticate users, or replace firewalls. You feed it events; it returns a decision (allow, warn, delay, block). Your code decides what to do with that.
Event → Observe → Analyze Pattern → Risk Score → Decision (allow / warn / delay / block)
- Pattern-Guard is stateless from the outside, but stateful internally.
- It maintains short-lived behavioral memory, not permanent logs at least for now.
- It recommends a decision; it does not enforce. Callers act on the decision.
An Event is a normalized description of something happening.
| Field | Required | Description |
|---|---|---|
actor | Yes | Who caused it (user, IP, service, script) |
action | Yes | What was done (GET, POST, run, query) |
target | Yes | What was affected (endpoint, command, resource) |
timestamp | Yes | When it happened |
weight | No | Cost/impact of the event |
metadata | No | Tags or context |
Pattern-Guard is framework-agnostic because everything becomes an event.
| It does | It does not |
|---|---|
| Observe events, model behavior, score risk, map to decisions (allow / warn / delay / block) | Authenticate, authorize, inspect payloads, enforce blocks, coordinate across nodes |
| Time-bounded in-memory patterns, config-driven | Persistent storage, distributed coordination, WAF/firewall replacement |
High-level modules:
pattern-guard
├── Event Tracker
├── Pattern Analyzer
├── Decision Engine
├── Policy & Config
└── Output / Enforcement
- Stores recent events in memory
- Organizes by actor and target
- Uses sliding time windows
- Automatically expires old data (TTL)
- Computes statistics over windows
- Detects: bursts, repetition, intervals, switching patterns
- Produces a risk score (e.g. 0.0 → 1.0), not a verdict
- Converts risk into decisions
- Applies configured thresholds
- Supports escalation (warn → delay → block)
- Declarative rules (TOML)
- Global defaults
- Per-actor overrides
- Returns a recommended decision to the caller
- CLI: can control execution (e.g. wrap a command)
- Library: caller enforces (HTTP 429, sleep, etc.). Pattern-Guard does not enforce.
Request arrives
↓
Create Event
↓
Pattern-Guard.check(event)
↓
Decision
↓
Either: continue | delay | block
Pattern-Guard never touches business logic.
pattern-guard --config guard.toml -- my_script.sh
# equivalent: pattern-guard --config guard.toml my_script.shUnknown flags (other than --config, --repeat, and --) cause a non-zero exit with an error message.
- Observes command behavior
- Helps prevent runaway scripts
- Logs suspicious execution
- Human-readable (TOML)
- Explicit (no hidden magic)
- Safe defaults
- Override-friendly
Example concepts: time windows, thresholds, risk-to-decision mapping, pattern definitions.
Pattern-Guard requires:
- High-frequency event handling
- Shared mutable state
- Precise timing
- Long-running safety
Rust provides:
- Thread safety without runtime overhead
- Predictable memory usage
- Deterministic performance
- Strong ecosystem for systems tooling
This project would be harder and less reliable in GC-based runtimes.
Backend and platform teams, CLI authors, anyone who’s wired up burst checks or “too many requests” logic by hand. Rust didn’t have a shared behavior-level guard; this is one.
The core design (event → observe → risk score → decision) stays. Future work could add:
- Optional ML or richer scoring models (same risk interface)
- Persistent storage or distributed coordination
- Metrics, dashboards, alerting
- WASM / plugin system
The engine remains a signal generator, not a gatekeeper.
- Config schema — TOML keys and defaults.
- Use cases — when to use it; mapping requests to events.
Example configs: guard.toml.example, guard.toml.demo. API: cargo doc --open.
Load a config, build an event, call the guard. You get back a decision and (optionally) a risk score.
use pattern_guard::{Guard,Event};use std::time::SystemTime;let guard = Guard::from_config_path("guard.toml")?;let event = Event::new("user:123","GET","/api/foo",SystemTime::now());let(decision, risk) = guard.check_with_risk(&event);// decision: Allow | Warn | Delay(_) | BlockFrom the repo you can run the CLI or the examples:
# One run, one event
cargo run -- --config guard.toml.demo -- true# Same process, N runs (burst accumulates)
cargo run -- --config guard.toml.demo --repeat 5 -- true# Burst demo: one process, 8 events → Allow → Warn → Delay → Block
cargo run --example burst_demo
# Repetition demo: same action/target repeated
cargo run --example repetition_demoRUST_LOG=info turns on log output for warn/delay/block.