## 🛡️ Bulwark
**Bulwark** is a lightweight, extensible security middleware framework for Rust APIs.
It provides a **deterministic inspection → decision → execution pipeline** that helps you analyze and control incoming requests **before** they reach your application logic.
Bulwark is designed to be:
- simple
- composable
- framework-agnostic
- explicit by default
> 🔒 **Status:** API Frozen (v0.3.0)
> Core APIs are considered stable. See **API Stability** below.
---
## ✨ Features
- 🔍 Request inspection via pluggable inspectors
- 🧠 Centralized, deterministic decision engine
- 🛡️ Severity-based escalation model
- 🦀 Written in pure Rust (no `unsafe`)
- ⚡ Lightweight with minimal dependencies
- 🧩 Easy to extend with custom inspectors
---
## 🔒 API Stability (v0.3.0)
Starting from **v0.3.0**, the following APIs are **frozen** and guaranteed stable:
### - `RequestContext`
### - `Inspector` trait
### - `InspectorFinding`
### - `FindingSeverity`
### - `DecisionEngine`
### - `Server` execution behavior
The meaning and behavior of these components will not change without a **major version bump**.
### Not part of the public API
The following are **explicitly not stable** and may change at any time:
- Error message strings
- Logging format and implementation
- Internal inspector heuristics
---
## 📦 Installation
Bulwark is **not published on crates.io yet**.
You can depend on it directly from GitHub:
```toml
[dependencies]
bulwark = { git = "https://github.com/haqqimuazzam1-hue/Bulwark", version = "0.3" }
```
## 🚀 Quick Example
```Rust
use bulwark::request::context::{RequestContext, Method};
fn main() {
let ctx = RequestContext::new(Method::POST, "/login");
println!("Method: {:?}", ctx.method);
println!("Path: {}", ctx.path);
}
```
## 🧠 Core Concepts
RequestContext
Represents a normalized incoming request:
• HTTP method
• request path
• headers, query parameters, body (optional)
Passed immutably to all inspectors and the decision engine.
## Inspector
Inspectors analyze requests and report findings.
• Inspectors do not make decisions
• Inspectors are side-effect free
• Each inspector reports a FindingSeverity
## FindingSeverity
Represents the severity of an inspector finding:
```
• High → request must be blocked
• Medium → request is allowed but logged
• Low → informational, no effect
```
## DecisionEngine
The central engine that:
• collects inspector findings
• evaluates severity deterministically
• produces a final decision (Allow, Log, Block)
## Server
The executor layer that:
• applies the final security decision
• contains no inspection logic
• acts as the enforcement boundary
It does not claim to protect against all attacks or vulnerabilities.
🧪 Development
Format code:
```bash
cargo fmt
```
Run lint checks:
```bash
cargo clippy
```
Run test:
```bash
cargo test
```
## 🤝 Contributing
Contributions are welcome 🎉
• Bug reports
• Feature requests
• Documentation improvements
• New Inspectors
Please read CONTRIBUTING.md before submitting a pull request.
## 🗺️ Roadmap
```
• [x] Stable core API (v0.3.0)
• [] More built-in inspectors
• [] Better documentation & examples
• [] Publish to creates.io
• [] v1.0.0 release
```
## 📄 License
MIT License © 2026 Bulwark Project