Repository navigation
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
GuardConfigErrorgains theConfigvariant (the engine now runsSecurityConfig::validatebefore wiring) and theAgentvariant (an agent built from theagent_*fields that fails underagent_strict), so an exhaustivematchover it needs arms for both.- Trains with the engine: the
guard-core-engineandguard-core-rsfloors move to 4.4.0, and the optionalguard-agent-rsto 3.2.4.SecurityConfiggains public fields, so a struct literal needs..Default::default(); an invalid IP list entry is now reported asConfiginstead ofIpGate. - 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_whitelistorwhitelist_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 withinbody_read_timeoutis answered 408, androute_resolution_strictanswers 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 routeip_whitelist/ip_blacklistverdict is combined with the routeblocked_countries/whitelist_countriesverdict (a route whitelist match no longer overrides a blocked country,blocked_countriesis asked first, no loopback exemption on the route arm), the unknown client identity is denied by a routeip_whitelistorwhitelist_countries, and a globalwhitelistdenies 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-Forthroughtrusted_proxiesandtrusted_proxy_depth, IPv4-mapped peers canonicalized. A request with no peer and no resolvable client answers403 Client address could not be determinedunderfail_secure(check nameclient_address_unresolvedon theon_blockhook), after the exclusion decision.GuardFairing::with_client_policyandClientPolicyinstall the policy (a bare fairing keepsfail_secure = false), andWebSocketGuardConfig::with_client_policygives the upgrade guard the same resolution -
GuardExclusionScoped, the marker anexclude_pathsrequest carries (the referenceguard_exclusion_scoped, read it as anOption<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)andfrom_wiring(Wiring), with the telemetry agent injected through the facade'sTelemetryHandler.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.GuardConfigErrorgained theCloud,RedisandGeovariants -
The
security_bypassevent 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 underpassive_mode -
Body
return_patternrules now read the response body: the response body is buffered when a rule needs it, bounded in time bybody_read_timeout, re-emitted intact, and a read error or timeout answers the fail-secure500 -
Reference parity:
SecurityConfig::validateruns 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 withLiveContextandLiveStages),route_resolution_strictanswers500 Route resolution failedfor a request that matched no route (decided inon_response, log-only underpassive_mode, emitsroute_unresolvedand fireson_block,GuardFairing::with_route_resolution_strict),GuardBodyanswers408 Request body read timed outwhen the body does not arrive withinbody_read_timeout, and the cargo featuresredis(forwardsguard-core-rs/redis) andagent(builds the guard-agent-rs agent from theagent_*fields,GuardConfigError::Agent, degraded state inagent_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 exampleauto_ban_threshold = 0) are now refused byfrom_security_config;Wiring::build_unvalidatedis the unvalidated seam exclude_pathsuses the engine's reference matcher instead of an exact raw-path comparison:/staticcovers/static/app.js, percent-encoding and dot segments are resolved, andexclude_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 theX-Real-IPheader from any peer: it is the connecting peer, withX-Forwarded-Forhonored only through the trusted proxies from_security_configbuilds throughWiring, so the fields it used to drop now land: geo country rules andgeo_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 whenguard-core-rshas itsredisfeature. The response processor now shares the ban manager with the ban stage, so a return-rulebanis enforced by the next request. A config withfail_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_proxiesagainst the connecting peer instead of passing no client host, and the request scheme is the transport's own, so a forgedX-Forwarded-Protofrom an untrusted peer no longer skips the redirect - A route carrier's
auth_requiredandapi_key_requiredfall back to the config's globalauth_verifier GuardBodyskips its body scan for an excluded request and for a route that bypassesallorpenetration; 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