Repository navigation
Releases
v2.0.0
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
v1.5.0
v1.5.0 (2026-10-09)
The consumption release: the unified config, the route-config carrier knobs, the response-pass funnels, and the behavioral lanes land, training with the 4.3.2 route-config engine (v1.5.0)
Note
- Trains with the engine: the
guard-core-engineandguard-core-rsfloors move to 4.3.2 (the route-config train)
Added
- The
get_cloud_providers_to_checkroute-over-global resolution (the RC2 rocket leg, over guard-core-rs#105'sdecide_route): the carrier route'sblock_cloud_providerslist replaces the global one for the request (an empty route list falls back to the global config), an invalid route selector fails secure (the reference validates at decoration time), the global lane stays untouched off-route, and thecloudsbypass skips the whole arm; six end-to-end twins drive the override, the route block, the off-route hold, the fallback, the fail-secure arm, and the bypass - The carrier's stage knobs at the per-stage seams (the RC1 rocket leg): the
(method, path)carrier's remaining reference knobs consume at their pipeline positions through the engine's decision cores -ip_whitelist/ip_blacklist(theRouteIpGatearm before the global gate: a configured whitelist takes over the route verdict and skips the global lists,skip_ip_lists; the blacklist denies the reference403 Forbidden; an invalid entry fails secure), per-route countries (blocked_countries/whitelist_countriesthroughgeo::check_countries, a passing route whitelist skipping the global geo stage,skip_countries; no geo handler leaves the request alone),required_headersplus the auth group and the api-key group (headers_auth::decideover the carrier rules with the route verifiers, therequiredsentinel, the fixed401shape),custom_validators(decide_custom_validatorsunder the referenceanonymousname, the validator's own status, the truthy non-response and the declining validator passing through),require_referrer(the referrer core's403shapes),time_restrictions(thestart/end/timezonedict through the time-window core, missing bounds fail-open), andenable_suspicious_detection = falseskipping the scan for its route (detection_enabled); thirteen end-to-end twins drive every knob on a matching route and its off-route silence - The
security_headers_appliedfunnel (the H6 rocket leg, over guard-core-rs#103's composer and #104's accessor): when the security-header set lands on a forwarded response and the bus is installed, the fairing'son_responsepass composessecurity_headers_applied_eventand dispatches it over the bus - actionheaders_addedover thesecurity_headershandler, metadatapath(display-redacted),headers_count(the rendered set, before the CORS verdict and the response modifier touch the view),has_csp,has_hsts; only the forwarded lane fires (the pipeline passed,Verdict::Clean, and no route guard refused - the referenceprocess_responseshape that carries the request path), guard-generated answers (blocks, the redirect, the fail-secure500) apply the headers without firing (the reference'screate_error_responselane), and a disabled set renders nothing and dispatches nothing - The CORS preflight short-circuit and the behavioral usage rules in the pipeline (the GAP-R10 rocket leg, over guard-core-rs#95's engine surface): an OPTIONS request carrying
access-control-request-methodhas its preflight answer computed inon_request(the referenceis_preflight+build_preflight_response;cors::is_preflight+build_preflight_responsefrom the resolved CORS config) andon_responsereplaces whatever Rocket composed with it - a preflight answer is200/400, statuses the fairing decides (Rocket's fairings cannot answer mid-flight, so the answer rides a request-local slot and the handler's output is never observed); CORS disabled or no response processor leaves OPTIONS to the pipeline. The route carrier's usage/frequencybehavior_rulestrack per request through the response processor's shared tracker with a crossedbanrendering the activity-banned shape (the referenceprocess_usage_rules, dispatched from the request pass before the check pipeline) - The maintenance trio and the full status payload (the GAP-R9 rocket leg):
GuardFairing::reset(the referencereset(): the rate-limit windows drop, bans and violation counts untouched),refresh_cloud_ip_ranges+with_cloud_refresh_scheduler(the referencerefresh_cloud_ip_ranges: one single-flight background refresh through the facade'sCloudRefreshScheduler- the refreshed ranges land in the shared table, each provider's row restamped,falsewith no scheduler installed or while one is in flight, the reference's concurrent-caller gate), andagent_statsanswering the reference property's no-agent shape ({"enabled": false, "degraded": false}, theAgentStatstype re-exported); the status payload's provider rows carry the referenceget_statusshape -ready,last_refreshed(the unix-second stamp of the last range load,nullbefore one, fromCloudIpTable::provider_status), andentries- with the geo-ip component rendering theIpInfoManagerhealth snapshot ({ready, last_refreshed, entries}) when the lifecycle manager is wired (the bareconfiguredflag andnullstay for the trait-only and absent arms) - The WebSocket guard for Rocket's official
rocket_wssurface (fastapi-guardguard/websocket.py'smake_guard_websocket, the GAP-A9 rocket leg):.manage(make_guard_websocket(WebSocketGuardConfig))+ theWebSocketGuardrequest guard onrocket_wsroutes runs the reference check sequence before the handshake completes - fail-secure unknown address, the ban arm, theis_ip_allowedgate + country arms (a whitelist match skips countries), thewsrate limit (skipped for whitelisted IPs), then the path/query/header penetration scan - and a blocked handshake answers403 Forbiddenpre-accept with the close shape onx-guard-websocket-close/x-guard-websocket-close-reason(1008 Policy Violationpolicy denials,1013 Try Again Latermalfunctions, the panic in the check sequence contained). The guard also covers frames after the upgrade:WebSocketGuard::scan_framescans one text/binary message through the engine (control frames pass), answers the reference close shape (close_frame+stream_error), and feeds the shared violation store installed bywith_violation_feed(the reference's sharedsuspicious_request_counts): a crossed threshold bans the address through the sharedIpBanManager, and the next handshake's ban arm rejects it;rocket_wsrides in as a dependency - The reference route-config carrier consumption (
GuardFairing::with_route_configs+set_route_config, the GAP-R2 rocket leg): the engine'sRouteConfigResolver((method, path) -> Option<Arc<RouteConfig>>) resolves the route'sRouteConfigonce peron_requestpass - a carrier stashed withset_route_configwins over the resolver (the referencerequest.state.route_configidiom) - and the pipeline consumes it with the reference semantics:bypassed_checks(and the"all"wildcard) skip the named reference checks at their pipeline positions (the fused stages map as documented:required_headers/authenticationskip the headers-auth stage,ip_securityskips the gate, ban, and geo arms,suspicious_activityskips the scan and its violation feed,rate_limitskips the whole tiers pass),require_httpsrides the HTTPS stage's carrier lane (decide_route; with no stage installed the route arm still composes the reference301),max_request_sizereplaces the body cap the data guard enforces,blocked_user_agentsruns additively before the global filter through the trusted-compile lane (a non-compilable route pattern fails secure500), the rate-limit group becomes the route's tier (an invalid tier fails secure), and the detection-exclusion group resolves through the engine's detection view;RouteConfig/RouteConfigResolverre-exported - The unified-config consumption (
GuardFairing::from_security_config, the GAP-R1 rocket leg): the 129-fieldSecurityConfig(the fieldized reference surface in guard-core-engine) builds the wired pipeline in one call - the detection budgets ontoDetectConfig, the IP lists onto the gate, the rate-limit knobs onto the limiter, the ban group ontoIpBanManager+IpBanConfig,enforce_https/trust_x_forwarded_protoonto the HTTPS stage,emergency_mode+ its whitelist onto the emergency stage,custom_error_responses/on_blockonto the response surface, the detection-exclusion group (with the reference's empty-set-disables-all-categories semantics) onto the scan, the observability group onto the log/redaction knobs, ReDoS-validatedblocked_user_agents, and the security-headers/CORS/behavior response pass; invalid values fail closed through the new typedGuardConfigError; the referenceexclude_pathscarve-out lands as a first-class builder consumed first in the pipeline (an excluded path bypasses every request-side check, gate included, the response pass still renders);SecurityConfig,SecurityConfigError,GuardConfigError, and theLogLevel/LogFormat/BufferOverflowPolicyknob enums re-exported
Changed
- The bypass consumption now uses the reference's coarse query vocabulary (the ip gate, the route IP restrictions, and the country arms query
ip; the ban armip_ban; the cloud-provider checkclouds; the rate limiterrate_limit; the penetration scanpenetration; the"all"wildcard matches every query) - the previous wave keyed the bypass on the 17 stage names, a vocabulary the reference never queries (the stages it named are not route-bypassable in the re...
v1.4.0
v1.4.0 (2026-10-07)
The reference-surface release: the status route lands in managed state, training with the 4.3.1 parity-completion engine (v1.4.0)
Note
- Trains with the engine: the
guard-core-engineandguard-core-rsfloors move to 4.3.1 (the parity-completion release)
Added
- The reference status route (fastapi-guard
add_status_route+HandlerInitializer.get_initialization_status):GuardStatusin managed state plus theguard_statusroute handler mounted at/_guard/status, serving the cloud-provider readiness table and the geo-ip component from the handles the app already holds (#38). The WebSocket upgrade guard has no surface here: rocket has no stable 0.5 WS surface to guard
v1.3.0
v1.3.0 (2026-10-01)
The 4.3.0 engine train: the guard-core-engine and guard-core-rs floors move to 4.3.0, no adapter logic changes (v1.3.0)
Note
- Trains with the engine: the
guard-core-engineandguard-core-rsfloors move to 4.3.0 (the safety-chain release). The adapter ships no logic changes of its own
Changed
v1.2.0
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-engineandguard-core-rsfloors 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 inon_igniteand carried in the managed engine state; every stateful decision and emission goes through it):with_route_tiers(resolver)(path -> Option<RouteRateLimits>) andwith_geo_handler(Arc<dyn GeoIpHandler>): the reference's endpoint/route/geo rate-limit tiers; the first tier that crosses answers the same429 + Retry-Aftershape and feeds the auto-ban engine; the request-localset_route_rate_limits(&request, tiers)setter covers the per-route decorator idiomwith_detection_exclusions(DetectionExclusionConfig)+with_route_detection_exclusions(resolver)(+ theset_route_detection_exclusionssetter): the reference per-route detection-exclusion surface, resolved per request through the engine'sdetection_exclusions::resolve+scan_requestwith_event_bus(Arc<SecurityEventBus>): thepenetration_attempt/rate_limited/ip_bannedevents with the reference fields, metadata, and redactionwith_observability(ObservabilityConfig):log_suspicious_level,muted_check_logs, and thelog_sensitive_headers/params/body_fieldsredaction setswith_on_block(OnBlockHook)andwith_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 the404rewritewith_distributed_store(window_store, redis_prefix, redis_fail_open)+with_distributed_ban_store(store): the reference distributed mode (fail-closed backend errors answer the new503 "Redis rate limiting unavailable"shape,fail_open = truedegrades 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 theset_route_rate_limits/set_route_detection_exclusionssetters
Changed
guard-core-rs(the engine facade) joinsguard-core-engineas a pinned 4.1.0 dependency with the sibling-checkout path fallback; the stage delegation keeps the existingwith_rate_limiting/with_ip_banningshared-handle semantics (out-of-band bans and custom clocks honored) through the stage builder'slimiter/ban_managerinjection seams- Two-phase flow (documented framework mismatch, reference-matching order): Rocket's
on_requestnever sees the body, so the fairing runs bans + rate-limit tiers + the metadata finding there (the request's single rate-window hit records aton_request), and theGuardBodydata guard feeds the body finding through the engine stage's splitfeed_findingseam - 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 (ssrffor 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_limitandip_banmodules, mirroring the tower reference implementation:GuardFairing::with_rate_limiting(RateLimiter): the sliding-window limiter runs inon_requestafter the IP gate and the ban check, before the metadata scan - a crossing answers429 Too Many RequestswithRetry-After: <window seconds>, the references' rate-limit shape. With the limiter'senable_rate_limit_auto_banon, every crossing counts onerate_limitviolation toward the auto-ban engine (threat_ban_config["rate_limit"]first, then the flat threshold), the reference pipeline's_record_rate_limit_autobanGuardFairing::with_ip_banning(IpBanManager, IpBanConfig): a live ban answers403 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 crossedthreat_ban_configentry or the flatauto_ban_thresholdbans on the spot, answering403 Forbidden(IP has been banned);config.enable_ip_banning = falsecounts violations but never bans; the plain detection block keeps the reference suspicious-activity stage's400 Bad Request(Suspicious activity detected) shape- both stages honor the
exempt_ipscontract: whitelisted and exempt IPs are never rate limited, never banned (ban stage), and never have violations counted - which makesexempt_ipsobservable 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, andViolationCountersare 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 of403 Forbidden, matching the reference suspicious-activity stage's status and the rest of the Rust family (the IP gate's403 Forbiddenand the fail-secure500are unchanged); the registered catchers and the fairing's unrouted-path404rewrite carry the family's five-shape contract
v1.1.0
v1.1.0 (2026-09-26)
The optional global IP gate
Added
- Optional global IP gate (
GuardFairing::with_ip_gateover the new engineIpGateConfig):whitelist,blacklist, andexempt_ipslists parsed once at startup (invalid entry is a config error, fail closed), evaluated inon_requestbefore the metadata scan on the request's client IP - a blacklisted client IP, or one a non-emptywhitelistmatches neither directly nor throughexempt_ips, is refused with403 Forbidden, including the unrouted-path404rewrite so probe traffic never reveals route inventory.exempt_ipsis the skip-list for known-friendly automation: it sets the same skip state a whitelist match sets but never adds a deny path and never opens the whitelist gate; the blacklist and detection still apply to exempt IPs. Requests without a client IP (Rocket's local test client) are not attributed and still screened by detection
Changed
guard-core-enginedependency pinned to the published 4.1.0 release (path dep kept for local builds and CI against a siblingguard-core-rscheckout), carrying the stateful sliding-window rate limiter and dynamic IP ban engine, the tower stage with a reusabledecide(), and the new detection stages (request size/content, user-agent, headers/auth, cloud provider blocking, geo blocking)- The request body is no longer scanned as one lossy blob: it is routed by content type through the engine's body-value extraction (guard-core 4.0.4 parity, upstream commit 5f399234), and every extracted value is scanned through the normal detect path with its reference context - urlencoded field values under
request_body:form_field, multipart part entries (label scan,filename="..."entry with RFC 2231 handling, raw part headers, payload) underrequest_body:multipart_field, embedded JSON leaves under the:embedded_jsonsuffix, JSON mongo operator keys ($where,$ne, ...) as directnosqlhits, and the whole-body blob only as the fallback for plain or unparseable bodies - Binary-dense multipart file-part payloads are reduced to printable runs of at least
detection_binary_min_run_length(default 16) before pattern scanning, so compressed upload bytes stop producing attack-shaped matches while text embedded in uploads still scans in full; text uploads, text parts without a filename, and whole-body fallback scans keep their full scan - 403/413/500 short-circuit responses now carry the bare message (
Suspicious activity detected,Payload too large,Security check failed) astext/plain; charset=utf-8, matching the Python family's block-response convention, instead of the JSON{"detail":"..."}shape
v1.0.0
[1.0.0] - 2026-09-24
Added
- First stable release of
rocket-guard-rs1.0.0: application-layer security Fairing for Rocket 0.5, powered byguard-core-engine4.0.4 (17/17 checks parity with guard-core 4.0.4, binary-noise gates) - Guard Fairing: one engine call per request view (path, query string, headers, buffered body), 403/413/500 fail-secure responses with the ecosystem JSON
detailshape, configurable body cap (default: engine full-scan cap),catch_unwindpanic recovery - Example apps:
examples/simple_appandexamples/advanced_appwith Dockerfiles and docker-compose smoke stacks - Dockerized live smoke workflow (
.github/workflows/live-smoke.yml): compose run ofsimple_appwith curl assertions of real engine behavior (XSS block, traversal block, 413 body cap, passthrough) - Upstream drift guard (
.github/workflows/upstream-drift.yml): daily test suite run againstguard-core-rs@master - Security audit workflow (
cargo deny), release gate (fmt/clippy/test at tag on stable and MSRV 1.92, tag/version consistency), automated crates.io publish on GitHub release viaCARGO_REGISTRY_TOKEN Makefile(install,test,lint,fix,bump-version,clean) and.github/scripts/bump_version.py(stdlib-only version bump across the crate, example pins,Cargo.lock, and a CHANGELOG scaffold)
Changed
guard-core-enginedependency pinned to the published 4.0.4 release (path dep kept for local builds and CI against a siblingguard-core-rscheckout)