Skip to content

v1.2.0

Choose a tag to compare

@rennf93 rennf93 released this 27 Sep 19:11
· 91 commits to master since this release
v1.2.0
afcbe92

v1.2.0 (2026-09-27)

Trains with guard-core-rs 4.2.0: the 4.2.0 floors restore public registry resolution

Note

  • Trains with the engine: guard-core-engine and guard-core-rs floors move to 4.2.0 (the 4.1.0 engine dists were yanked; this release restores registry resolution)

Added

  • The wave surfaces are publicly configurable on GuardFairing, each wired to the engine facade's rate-limit stage (guard_core_rs::tower::RateLimitStage, built in on_ignite and carried in the managed engine state; every stateful decision and emission goes through it):
    • with_route_tiers(resolver) (path -> Option<RouteRateLimits>) and with_geo_handler(Arc<dyn GeoIpHandler>): the reference's endpoint/route/geo rate-limit tiers; the first tier that crosses answers the same 429 + Retry-After shape and feeds the auto-ban engine; the request-local set_route_rate_limits(&request, tiers) setter covers the per-route decorator idiom
    • with_detection_exclusions(DetectionExclusionConfig) + with_route_detection_exclusions(resolver) (+ the set_route_detection_exclusions setter): the reference per-route detection-exclusion surface, resolved per request through the engine's detection_exclusions::resolve + scan_request
    • with_event_bus(Arc<SecurityEventBus>): the penetration_attempt/rate_limited/ip_banned events with the reference fields, metadata, and redaction
    • with_observability(ObservabilityConfig): log_suspicious_level, muted_check_logs, and the log_sensitive_headers/params/body_fields redaction sets
    • with_on_block(OnBlockHook) and with_custom_error_responses(CustomErrorResponses): the hook fires exactly once per blocked request (and per passive-flagged detection with no status); the status-to-body map overrides every block body, honored by the catchers and the 404 rewrite
    • with_distributed_store(window_store, redis_prefix, redis_fail_open) + with_distributed_ban_store(store): the reference distributed mode (fail-closed backend errors answer the new 503 "Redis rate limiting unavailable" shape, fail_open = true degrades to the in-memory window)
    • with_passive_mode(bool): the reference passive mode - windows and counters record, log lines and events fire, no block ever renders
  • New re-exports: DetectionExclusionConfig, RouteDetectionExclusions, GeoIpHandler, BanStore, SlidingWindowStore, ViolationCounters, RouteRateLimits, RateLimitEntry, RateLimitTier, TierDecision, SecurityEventBus, ObservabilityConfig, RequestObservation, StageResponse, BlockPayload, OnBlockHook, CustomErrorResponses, and the set_route_rate_limits/set_route_detection_exclusions setters

Changed

  • guard-core-rs (the engine facade) joins guard-core-engine as a pinned 4.1.0 dependency with the sibling-checkout path fallback; the stage delegation keeps the existing with_rate_limiting/with_ip_banning shared-handle semantics (out-of-band bans and custom clocks honored) through the stage builder's limiter/ban_manager injection seams
  • Two-phase flow (documented framework mismatch, reference-matching order): Rocket's on_request never sees the body, so the fairing runs bans + rate-limit tiers + the metadata finding there (the request's single rate-window hit records at on_request), and the GuardBody data guard feeds the body finding through the engine stage's split feed_finding seam - no window double-recording, and rate limiting still precedes body processing exactly as the reference pipeline orders it
  • Scan semantics move onto the engine's reference surface: the query string is scanned as parse_qsl-decoded per-parameter pairs (previously one raw encoded blob), and the headers the exclusion resolution marks are scanned with their known false-positive categories suppressed (ssrf for address-chain values) instead of an adapter-level blanket skip. Exempt IPs now feed the violation counters (the reference suspicious-activity stage skips a whitelisted IP only; detection still scans and blocks them), so a crossed threshold bans even an exempt attacker

Added

  • Stateful stage (rate limiting, dynamic bans, auto-ban) over the engine's rate_limit and ip_ban modules, mirroring the tower reference implementation:
    • GuardFairing::with_rate_limiting(RateLimiter): the sliding-window limiter runs in on_request after the IP gate and the ban check, before the metadata scan - a crossing answers 429 Too Many Requests with Retry-After: <window seconds>, the references' rate-limit shape. With the limiter's enable_rate_limit_auto_ban on, every crossing counts one rate_limit violation toward the auto-ban engine (threat_ban_config["rate_limit"] first, then the flat threshold), the reference pipeline's _record_rate_limit_autoban
    • GuardFairing::with_ip_banning(IpBanManager, IpBanConfig): a live ban answers 403 Forbidden (IP address banned) before the limiter, so banned traffic never consumes rate budget; every detected threat counts its categories per client IP (the reference pipeline's suspicious-activity stage) and a crossed threat_ban_config entry or the flat auto_ban_threshold bans on the spot, answering 403 Forbidden (IP has been banned); config.enable_ip_banning = false counts violations but never bans; the plain detection block keeps the reference suspicious-activity stage's 400 Bad Request (Suspicious activity detected) shape
    • both stages honor the exempt_ips contract: whitelisted and exempt IPs are never rate limited, never banned (ban stage), and never have violations counted - which makes exempt_ips observable under load; unattributed requests (no client IP) cannot be held responsible and skip the stage, detection still screens them
    • the limiter and the ban store pair are shared with the managed engine state, and RateLimiter, IpBanManager, and ViolationCounters are cheaply clonable and clone-share their stores, so out-of-band handles (admin unban endpoints, stats) work alongside the installed fairing

Changed

  • Detection blocks answer 400 Bad Request (Suspicious activity detected) instead of 403 Forbidden, matching the reference suspicious-activity stage's status and the rest of the Rust family (the IP gate's 403 Forbidden and the fail-secure 500 are unchanged); the registered catchers and the fairing's unrouted-path 404 rewrite carry the family's five-shape contract