guard_core_rs/
lib.rs

1// The suite's `assert!(x.is_empty())` idiom is pervasive (120+ sites) and several
2// subjects carry no `PartialEq`, so clippy 1.99's new `assert_is_empty` lint
3// (suggest `assert_eq!(x, [])` for the failure printout) is allowed crate-wide
4// rather than rewriting the assertion surface in a release train.
5#![allow(unknown_lints)] // the lint name below postdates the 1.92 MSRV clippy
6#![allow(clippy::assert_is_empty)]
7
8//! Framework-agnostic application-layer API security engine.
9//!
10//! Rust port of [guard-core](https://github.com/Guard-Core/guard-core)'s
11//! detection engine. **Work in progress:** the CPU-bound detection pipeline
12//! is the core, and the first pipeline stage has landed: the rate-limit and
13//! dynamic-ban [`tower`] layer for Axum/tonic-shaped stacks. Handlers,
14//! protocols, decorators, and other I/O layers are not yet ported.
15//!
16//! Re-exports the detection engine modules:
17//!
18//! - [`detection_exclusions`] - the per-route detection exclusion resolution
19//!   and the multi-surface request scan (`scan_request`): excluded
20//!   headers/params/body fields, enabled detection categories, and the
21//!   detection scan-body toggle, resolved from the global config and the
22//!   route config exactly as the reference's `_resolve_*` helpers do
23//! - [`compiler`] - regex pattern compilation with LRU caching and ReDoS safety validation
24//! - [`detect`] - the spec 4.0.2 detection pipeline entry point (`detect`, [`detect::DetectConfig`],
25//!   [`detect::DetectVerdict`])
26//! - [`preprocessor`] - unicode NFKC normalization, URL/HTML decoding, null byte removal,
27//!   whitespace collapsing, and attack-preserving truncation
28//! - [`semantic`] - token extraction, Shannon entropy, encoding layer detection, attack probability
29//!   scoring, obfuscation detection, code injection risk analysis, and aggregate threat scoring
30//! - [`cloud_provider`] - the cloud-provider blocking pipeline stage as a
31//!   `tower::Layer` (403 "Cloud provider IP not allowed", region
32//!   carve-outs, skip-state aware)
33//! - [`geo`] - the geo country blocking pipeline stage as a `tower::Layer`
34//!   (403 "Forbidden", loopback exemption, whitelist-skip only)
35//! - [`tower`] - the rate-limit and dynamic IP ban pipeline stage as a
36//!   `tower::Layer` (429 throttled shape, 403 banned shapes, exempt-IP
37//!   handling, the auto-ban feeds, and passive mode)
38//! - [`request_limits`] - the request size and content-type pipeline stage
39//!   as a `tower::Layer` (413 size shape, 415 content-type shape, fail-secure
40//!   500 on a junk content-length)
41//! - [`headers_auth`] - the required-headers and authentication pipeline
42//!   stage as a `tower::Layer` (dynamic 400 required-header shapes, fixed
43//!   401 authentication shape, route rules with a global verifier
44//!   fallback)
45//! - [`event_types`] / [`events`] - the reference `EVENT_*` constants and
46//!   the `SecurityEventBus` hook seam over the reference `SecurityEvent`
47//!   record
48//! - [`responses`] - the reference `custom_error_responses` map and the
49//!   `on_block` block hook with the reference payload and exclusion set
50//! - [`logging`] - the reference `log_activity` line shapes with the
51//!   `muted_check_logs` and `log_sensitive_*` redaction knobs
52//! - [`redact`] - the merged sensitive-name sets and the
53//!   `[REDACTED]` redaction the log lines run through
54//!
55//! # Usage
56//!
57//! ```
58//! use guard_core_rs::preprocessor;
59//! use guard_core_rs::semantic::AttackKeywords;
60//! use guard_core_rs::semantic::AttackStructures;
61//! use guard_core_rs::semantic::{self};
62//!
63//! let raw = "<scr\u{200B}ipt>alert(1)</script>";
64//! let clean = preprocessor::preprocess(raw, 10_000, true);
65//!
66//! let kw = AttackKeywords::default();
67//! let st = AttackStructures::default();
68//! let result = semantic::analyze(&clean, &kw, &st);
69//! let score = semantic::get_threat_score(&result);
70//!
71//! assert!(score > 0.0);
72//! ```
73
74pub mod cloud_fetch;
75pub mod cloud_provider;
76pub mod composite;
77pub mod custom_checks;
78pub mod dynamic_rules;
79pub mod emergency_mode;
80pub mod enrichment;
81pub mod event_types;
82pub mod events;
83pub mod geo;
84pub mod geo_lifecycle;
85pub mod headers_auth;
86pub mod https_enforcement;
87pub mod live;
88pub mod logging;
89pub mod metrics;
90pub mod mmdb;
91pub mod process_response;
92pub mod redact;
93#[cfg(feature = "redis")]
94pub mod redis_store;
95pub mod request_limits;
96pub mod request_logging;
97pub mod responses;
98pub mod route_gates;
99pub mod stage_events;
100pub mod sus_patterns;
101pub mod tower;
102pub mod user_agent;
103pub mod wiring;
104
105pub const VERSION: &str = env!("CARGO_PKG_VERSION");
106
107pub use guard_core_engine::compiler;
108pub use guard_core_engine::decorators;
109pub use guard_core_engine::detect;
110pub use guard_core_engine::detection_exclusions;
111pub use guard_core_engine::preprocessor;
112pub use guard_core_engine::referrer;
113pub use guard_core_engine::semantic;
114pub use guard_core_engine::time_window;
115
116#[cfg(test)]
117mod tests {
118    use super::VERSION;
119
120    #[test]
121    fn version_is_the_crate_package_version() {
122        assert_eq!(VERSION, "4.4.0");
123    }
124}
guard_core_rs/lib.rs

guard_core_rs/
lib.rs
