Skip to content

v2.0.0

Latest

Choose a tag to compare

@rennf93 rennf93 released this 16 Oct 02:44
· 20 commits to master since this release
Immutable release. Only release title and notes can be modified.
9100597

v2.0.0 (2026-10-16)

The reference-parity release, training with the 4.4.0 engine: route country rules and the unknown client identity, live dynamic rules, validated config, strict routes, the body read timeout and the agent from config (v2.0.0)

Breaking

  • GuardConfigError gains the Config variant (the engine now runs SecurityConfig::validate before wiring) and the Agent variant (an agent built from the agent_* fields that fails under agent_strict), so an exhaustive match over it needs arms for both.
  • Trains with the engine: the guard-core-engine and guard-core-rs floors move to 4.4.0, and the optional guard-agent-rs to 3.2.4. SecurityConfig gains public fields, so a struct literal needs ..Default::default(); an invalid IP list entry is now reported as Config instead of IpGate.
  • Behavior to know before upgrading: a route whitelist match no longer overrides a blocked country, the unknown client identity is denied on a route with an ip_whitelist or whitelist_countries, route usage rules run after the security pipeline, each dynamic rule version applies over the base config instead of stacking, a request body that does not arrive within body_read_timeout is answered 408, and route_resolution_strict answers an unresolved route with 500.

The parity release: the reference exclude_paths, client and response-pass semantics, and the whole SecurityConfig through the facade's Wiring.

Added

  • Route country rules and the unknown client identity follow the reference check_route_ip_access: the route ip_whitelist / ip_blacklist verdict is combined with the route blocked_countries / whitelist_countries verdict (a route whitelist match no longer overrides a blocked country, blocked_countries is asked first, no loopback exemption on the route arm), the unknown client identity is denied by a route ip_whitelist or whitelist_countries, and a global whitelist denies it (it passed before). Verified against 2125 rows generated by running the reference (tests/route_country.rs)

  • Client resolution with the reference rules: the connecting peer plus X-Forwarded-For through trusted_proxies and trusted_proxy_depth, IPv4-mapped peers canonicalized. A request with no peer and no resolvable client answers 403 Client address could not be determined under fail_secure (check name client_address_unresolved on the on_block hook), after the exclusion decision. GuardFairing::with_client_policy and ClientPolicy install the policy (a bare fairing keeps fail_secure = false), and WebSocketGuardConfig::with_client_policy gives the upgrade guard the same resolution

  • GuardExclusionScoped, the marker an exclude_paths request carries (the reference guard_exclusion_scoped, read it as an Option<GuardExclusionScoped> request guard), and the scoped pipeline it runs: route resolution, bans, the global IP, country and cloud rules, and the rate limit. The response pass runs scoped (metrics, security headers, CORS and the modifier, no return rules)

  • GuardFairing::from_security_config_with(config, &WiringOptions) and from_wiring(Wiring), with the telemetry agent injected through the facade's TelemetryHandler. agent_stats() now reports the wired sink and its degraded state, telemetry() exposes the fan-out, spawn_dynamic_rules() starts the dynamic-rule poll loop on request, and the cloud-range refresh runs per request at the cloud check position. New builders: with_telemetry, with_dynamic_rules, with_cloud_refresh, with_auth_verifier, with_body_read_timeout, with_path_exclusions. GuardConfigError gained the Cloud, Redis and Geo variants

  • The security_bypass event for an all-checks-bypass route (all_checks_bypassed), whose request forwards with only the response modifier applied (no metrics, headers or return rules) and continues through the pipeline under passive_mode

  • Body return_pattern rules now read the response body: the response body is buffered when a rule needs it, bounded in time by body_read_timeout, re-emitted intact, and a read error or timeout answers the fail-secure 500

  • Reference parity: SecurityConfig::validate runs at construction (GuardConfigError::Config), the stages a dynamic rule can change (geo, cloud, user agent, emergency mode, the penetration toggle, the rate limit and ban knobs) are read from the live config on every request (LiveCell, re-exported with LiveContext and LiveStages), route_resolution_strict answers 500 Route resolution failed for a request that matched no route (decided in on_response, log-only under passive_mode, emits route_unresolved and fires on_block, GuardFairing::with_route_resolution_strict), GuardBody answers 408 Request body read timed out when the body does not arrive within body_read_timeout, and the cargo features redis (forwards guard-core-rs/redis) and agent (builds the guard-agent-rs agent from the agent_* fields, GuardConfigError::Agent, degraded state in agent_stats())

Changed

  • The route usage rules (process_usage_rules) run after the whole pipeline passed instead of before it: a request the pipeline or a guard refuses is no longer counted, and neither is a request with no client ip. Configs that were invalid but accepted before (for example auto_ban_threshold = 0) are now refused by from_security_config; Wiring::build_unvalidated is the unvalidated seam
  • exclude_paths uses the engine's reference matcher instead of an exact raw-path comparison: /static covers /static/app.js, percent-encoding and dot segments are resolved, and exclude_paths() reports the normalized entries. An excluded request is no longer exempt from the pipeline: bans, the global IP lists, country and cloud rules and the rate limit apply, and the request is counted in the metrics. Tests that encoded the old exact-match bypass were updated
  • The client identity no longer comes from Rocket's client_ip(), which honors the X-Real-IP header from any peer: it is the connecting peer, with X-Forwarded-For honored only through the trusted proxies
  • from_security_config builds through Wiring, so the fields it used to drop now land: geo country rules and geo_ip_handler, block_cloud_providers, endpoint_rate_limits, enable_rate_limit_auto_ban, custom_request_check, auth_verifier, custom_response_modifier, on_error, cors_expose_headers, trusted_proxies, the telemetry and event bus, dynamic rules, and the redis stores when guard-core-rs has its redis feature. The response processor now shares the ban manager with the ban stage, so a return-rule ban is enforced by the next request. A config with fail_secure = true (the default) rejects a request that carries no peer address
  • The custom response modifier runs even when no response processor is installed, and exactly once when the processor already carries it
  • The HTTPS stage matches trusted_proxies against the connecting peer instead of passing no client host, and the request scheme is the transport's own, so a forged X-Forwarded-Proto from an untrusted peer no longer skips the redirect
  • A route carrier's auth_required and api_key_required fall back to the config's global auth_verifier
  • GuardBody skips its body scan for an excluded request and for a route that bypasses all or penetration; the size cap stays as the memory bound
  • Documentation: the skill file no longer describes the crate as a scaffold, the README engine-dependency and status statements are corrected, and the new config surface, client policy, scoped exclusions and agent injection are documented