Skip to content

fix(route): route country rules and the unknown client identity follow the reference #85

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rennf93 merged 1 commit into from
Oct 15, 2026
Merged

fix(route): route country rules and the unknown client identity follow the reference #85

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ Unreleased

### 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 (the reference `handle_passthrough` and `extract_client_ip`): the connecting peer (`GuardClientIp`) is resolved through a `ClientPolicy` (`trusted_proxies`, `trusted_proxy_depth`, `fail_secure`, new builder `with_client_policy`) and the resolved identity replaces the peer for the gate, bans, rate limits, geo, cloud, events and the response pass; a request with no resolvable client address answers `403 Client address could not be determined` under `fail_secure` (the `from_security_config` default) and fires `on_block` under the `client_address_unresolved` check, builder layers default to `fail_secure = false`
- `from_security_config_with(config, WiringOptions)` and `from_wiring(Wiring)`: the telemetry agent is injected through the facade's `TelemetryHandler`, which wires the event bus, the request metrics, `agent_stats()` (now reporting `enabled` and `degraded` from the sink), `spawn_dynamic_rules()` (host-started poll loop) and the cloud refresh (per-request `refresh_if_due` at the cloud position plus `refresh_cloud_ip_ranges`)
- The `GuardExclusionScoped` request extension, the `security_bypass` event for all-checks-bypass routes, the global `auth_verifier` as the fallback verifier of a route that carries none (`with_auth_verifier`), and re-exports of `ResponseBits`, `RequestBits`, `SecurityMetric`, `SecurityEvent`, `CustomResponse`, `CloudRefreshScheduler`, `StoreError` and the wiring types
Expand Down
103 changes: 50 additions & 53 deletions src/service.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -304,71 +304,60 @@ where

// The reference `_check_route_ip_access` (inside the
// `ip_security` block, before the global lists): the route's
// `ip_whitelist` / `ip_blacklist` decide first - a configured
// whitelist takes over the route verdict (a match passes, a
// miss denies), then the blacklist denies. A configured
// whitelist also overrides the global IP lists for the request
// (`_route_overrides_ip_lists` / `skip_ip_lists`), so the
// global gate is skipped and the skip flags stay unset. An
// invalid list entry fails secure (the reference validates at
// decoration time; the carrier's invalid entry rides the
// family's fail-secure arm, like an invalid route tier).
// `ip_whitelist` / `ip_blacklist` and its country rules
// (`blocked_countries` / `whitelist_countries`, the reference
// `check_country_access`) decide together. A configured
// whitelist takes over the IP verdict (a match passes, a
// miss denies), then the blacklist denies; the country verdict
// is combined with it (false if either is false, true if either
// is true), so a whitelist match never overrides a blocked
// country. The unknown identity (no resolvable client address)
// is denied when the route configures an `ip_whitelist` or a
// `whitelist_countries`. A configured route whitelist also
// overrides the global IP lists for the request
// (`_route_overrides_ip_lists` / `skip_ip_lists`), and a
// matching route country whitelist skips the global geo stage
// (`skip_countries`). An invalid list entry fails secure (the
// reference validates at decoration time; the carrier's invalid
// entry rides the family's fail-secure arm, like an invalid
// route tier).
let mut skip_global_ip_lists = false;
let mut skip_global_countries = false;
if !bypassed("ip")
&& let Some(route) = route
&& (route.ip_whitelist.is_some() || route.ip_blacklist.is_some())
&& (route.ip_whitelist.is_some()
|| route.ip_blacklist.is_some()
|| route.blocked_countries.is_some()
|| route.whitelist_countries.is_some())
{
match guard_core_engine::ip_gate::RouteIpGate::new(
route.ip_whitelist.iter().flatten().map(String::as_str),
route.ip_blacklist.iter().flatten().map(String::as_str),
) {
Ok(gate) => {
let verdict = facts.ip.map_or(
guard_core_engine::ip_gate::RouteIpVerdict::Unrestricted,
|ip| gate.evaluate(ip),
let countries = guard_core_engine::geo::parse_country_lists(
route
.whitelist_countries
.iter()
.flatten()
.map(String::as_str),
route.blocked_countries.iter().flatten().map(String::as_str),
);
let access = gate.evaluate_access(
facts.ip,
&countries,
layer.geo_handler.as_deref(),
);
if verdict == guard_core_engine::ip_gate::RouteIpVerdict::Denied {
if access.verdict == guard_core_engine::ip_gate::RouteIpVerdict::Denied {
return Ok(block_response(&parts, &layer, 403, FORBIDDEN_MESSAGE));
}
skip_global_ip_lists = gate.whitelist_configured();
skip_global_countries = access.country_whitelist_matched;
}
Err(_) => return Ok(failure_response(&parts, &layer)),
}
}

// The route's country rules (`blocked_countries` /
// `whitelist_countries`, the reference `check_country_access`
// inside `_check_route_ip_access`): a route whitelist that
// passes also skips the global geo stage for the request
// (`skip_countries`). An unresolvable country blocks only
// under a restrictive route whitelist, exactly the engine's
// `check_countries` reading.
let mut skip_global_countries = false;
if !bypassed("ip")
&& let Some(route) = route
&& (route.blocked_countries.is_some() || route.whitelist_countries.is_some())
{
let route_gate = guard_core_engine::geo::parse_country_lists(
route
.whitelist_countries
.iter()
.flatten()
.map(String::as_str),
route.blocked_countries.iter().flatten().map(String::as_str),
);
if let (Some(ip), Some(handler)) = (facts.ip, layer.geo_handler.as_ref()) {
if let Some(_block) = guard_core_engine::geo::check_countries(
ip,
&route_gate,
handler.as_ref(),
false,
) {
return Ok(block_response(&parts, &layer, 403, FORBIDDEN_MESSAGE));
}
skip_global_countries = !route_gate.whitelist_countries.is_empty();
}
}

// The IP gate runs before anything else: a denied IP must not
// cost a body buffer, and detection still scans whatever passes.
// The reference `ip_security` bypass skips the gate (and the
Expand Down Expand Up @@ -1577,14 +1566,19 @@ fn stage_answer_body(answer: &guard_core_rs::tower::StageResponse) -> &str {
/// request extensions (the family-local skip state, the equivalent of the
/// reference engine's `state.is_whitelisted` / `state.is_exempt`) so
/// downstream handlers can read it. Without a gate or without a
/// [`GuardClientIp`] extension the request is not attributed: the gate does
/// not run, and nothing is inserted.
/// [`GuardClientIp`] extension the request is the unknown identity: a
/// configured whitelist denies it, otherwise nothing is inserted.
fn enforce_ip_gate(parts: &mut Parts, layer: &GuardLayer) -> Option<Response<Full<Bytes>>> {
let gate = layer.ip_gate()?;
let GuardClientIp(ip) = parts.extensions.get::<GuardClientIp>()?;
match gate.evaluate(*ip) {
let client = parts.extensions.get::<GuardClientIp>().map(|ip| ip.0);
// No client address is the reference `UNKNOWN_CLIENT_IDENTITY`: a
// configured whitelist denies it, otherwise it passes unattributed.
let verdict = client.map_or_else(|| gate.evaluate_unknown(), |ip| gate.evaluate(ip));
match verdict {
IpGateVerdict::Allowed(decision) => {
parts.extensions.insert(decision);
if client.is_some() {
parts.extensions.insert(decision);
}
None
}
IpGateVerdict::Denied(denial) => {
Expand All @@ -1597,7 +1591,10 @@ fn enforce_ip_gate(parts: &mut Parts, layer: &GuardLayer) -> Option<Response<Ful
if layer.passive_mode {
return None;
}
let ip_string = ip.to_string();
let ip_string = client.map_or_else(
|| guard_core_rs::geo::UNKNOWN_CLIENT_IP.to_owned(),
|ip| ip.to_string(),
);
let body = resolve_error_body(
layer.custom_error_responses(),
403,
Expand Down
68 changes: 68 additions & 0 deletions tests/data/route_country.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
{
"_note": "generated by running guard_core (check_route_ip_access, check_ip_access); rows enumerate the dimensions in itertools.product order, last varies fastest; N=no verdict T=true F=false",
"countries": {
"10.0.0.1": "US",
"10.0.0.2": "CN",
"192.168.1.5": null,
"127.0.0.1": null
},
"ips": [
"10.0.0.1",
"10.0.0.2",
"192.168.1.5",
"127.0.0.1",
"unknown"
],
"route_lists": [
[],
[
"10.0.0.1"
],
[
"10.0.0.2"
],
[
"192.168.1.5"
]
],
"blocked_countries": [
[],
[
"CN"
]
],
"whitelist_countries": [
[],
[
"US"
],
[
"CN"
],
[
"US",
"CN"
]
],
"global_lists": [
[],
[
"10.0.0.1"
],
[
"192.168.1.5"
]
],
"global_whitelist_countries": [
[],
[
"US"
],
[
"CN"
]
],
"route": "NNNNNTFFFFFTFFFTTFFFNFNNNTFFFFFFFFFTFFFFFNNNNFFFFFFTFFFFTFFFFFNNNFFFFFFFFFFFFFFFNFNNNTFFFFFFFFFTFFFFNFNNNTFFFFFFFFFTFFFFNNFNNTFFFFFTFFFTTFFFNFFNNTFFFFFFFFFTFFFFTFFFFTFFFFFFFFFTFFFFTFFFFTFFFFFFFFFTFFFFTFFFFTFFFFFFFFFTFFFFTFFFFTFFFFFFFFFTFFFFTFFFFTFFFFFFFFFTFFFFTFFFFTFFFFFFFFFTFFFFTFFFFTFFFFFFFFFTFFFFTFFFFTFFFFFFFFFTFFFFFTFFFFFFFFFTFFFFTFFFFFFFFFFFFFFFFFFFFFFFFTFFFFFFFFFTFFFFTFFFFFFFFFFFFFFFFFFFFFFFFTFFFFFFFFFTFFFFTFFFFFFFFFFFFFFFFFFFFFFFFTFFFFFFFFFTFFFFTFFFFFFFFFFFFFFFFFFFFFFFFFTFFFFFFFFFFFFFFFFFFFTFFFFFFFFFFFFFFFFFFFTFFFFFFFFFFFFFFFFFFFTFFFFFFFFFFFFFFFFFFFTFFFFFFFFFFFFFFFFFFFTFFFFFFFFFFFFFFFFFFFTFFFFFFFFFFFFFFFFFFFTFFFFFFFFFFFFFFFFF",
"global": "TTTTTTFFTFFTFTFTFFFFTFFFFTFFFFFFTFFFFTFFFFTFF",
"combined": "TTTTTTFFTFFTFTFTFFFFTFFFFTFFFFFFTFFFFTFFFFTFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFFFFFFFFFFFFFFFFFTFFFFTFFFFTFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFTTFFFTTFFFTTFFFTFFFFTFFFFTFFFFFFFFFFFFFFFFFFFTFTTTTFFTFFFFTFTFFFFTFFFFTFFFFFFTFFFFTFFFFTFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFFFFFFFFFFFFFFFFTFFFFTFFFFFFFFFTFFFFTFFFFFFFFFTFFFFTFFFFFFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFFFFFFTFFFFTFFFFFFFFFTFFFFTFFFFFFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFFTFFFFFFFFFTFFFFTFFFFFFFFFTFFFFTFFFFFFFFFTFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFTFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFTFFFFFFFFFFFFFFTFFFFFFFFFFFFFFTFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFTFFFFFFFFFFFFFFTFFFFFFFFFFFFFFTFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF"
}
Loading
Loading