Merge master (PR #39) into release/v3.5.0-hardening

Author: rennf93

CHANGELOG.md

@@ -125,6 +125,20 @@ Cloud-IP region scoping, IP allow-list correctness, bounded body inspection, asy
 
 ___
 
+v3.1.2 (2026-06-08)
+-------------------
+
+Configurable country-check logging (v3.1.2)
+-------------------------------------------
+
+### Changed
+
+- **Per-request country verdicts are now configurable and routed through the `guard_core` logger.** `_log_country_check_result` previously logged whitelisted / not-affected results at `INFO` straight to the root logger (`logging.info`), so it was unreachable by named-logger levels and by `log_suspicious_level` / `log_request_level`. It now logs via `logging.getLogger("guard_core")` and honours the new `SecurityConfig.log_country_check_level` (default `"INFO"`, preserving prior behaviour). Set it to `None` to silence the routine whitelisted / not-affected chatter while keeping the genuine signal. Continuing the noise reduction from v3.1.0: blocked-country hits still log at `WARNING`, and no-rules / no-geolocation cases still log at `DEBUG`. Sync mirror updated identically.
+- **Penetration-detection hits now honour `log_suspicious_level`.** The per-component "Potential attack detected from …" line in `_check_request_component` was a second suspicious-log path that logged at a hardcoded `WARNING` on the root logger, bypassing config and duplicating the authoritative `SuspiciousActivityCheck` log. It now routes through the `guard_core` logger at `log_suspicious_level` (threaded down from `detect_penetration_attempt`); setting `log_suspicious_level=None` silences it.
+- **All remaining bare root-logger calls in `utils.py` and `cloud_handler.py` moved onto named `guard_core` loggers** (`Error processing client IP`, `Error checking IP`, `Enhanced detection failed`, and the cloud-provider `Failed to fetch … IP ranges` errors). No behavioural change at default levels — `logging.getLogger("guard_core").setLevel(...)` now governs the whole library. Sync mirror updated identically.
+
+___
+
 v3.1.1 (2026-05-27)
 -------------------
 

docs/architecture/pipeline.md

@@ -259,7 +259,7 @@ This check runs first because all subsequent checks depend on `request.state.cli
 | **Module** | `guard_core.core.checks.implementations.cloud_ip_refresh` |
 | **Purpose** | Periodically refreshes cloud provider IP ranges based on `config.cloud_ip_refresh_interval` |
 | **Blocks?** | Never. Always returns `None` |
-| **Side Effects** | Triggers `middleware.refresh_cloud_ip_ranges()` when the interval has elapsed |
+| **Side Effects** | Schedules a single-flight background refresh (running `middleware.refresh_cloud_ip_ranges()` off the request path) when the interval has elapsed |
 
 ### 12. IpSecurityCheck
 

docs/configuration/security-config.md

@@ -283,11 +283,17 @@ ___
 Redis
 -----
 
-| Field          | Type          | Default                   | Description                           |
-|----------------|---------------|---------------------------|---------------------------------------|
-| `enable_redis` | `bool`        | `True`                    | Master switch for Redis.              |
-| `redis_url`    | `str \| None` | `"redis://localhost:6379"`| Redis connection URL.                 |
-| `redis_prefix` | `str`         | `"guard_core:"`           | Key prefix for namespace isolation.   |
+| Field                            | Type          | Default                   | Description                                             |
+|----------------------------------|---------------|---------------------------|----------------------------------------------------------|
+| `enable_redis`                   | `bool`        | `True`                    | Master switch for Redis.                                |
+| `redis_url`                      | `str \| None` | `"redis://localhost:6379"`| Redis connection URL.                                   |
+| `redis_prefix`                   | `str`         | `"guard_core:"`           | Key prefix for namespace isolation.                      |
+| `redis_socket_connect_timeout`   | `float \| None`| `2.0`                    | Seconds to wait establishing a TCP connection. Must be positive; `None` disables (blocks indefinitely on a partitioned Redis). |
+| `redis_socket_timeout`           | `float \| None`| `2.0`                    | Seconds to wait on a read/write before raising. Must be positive; `None` means no timeout. |
+| `redis_health_check_interval`    | `int`         | `30`                      | Seconds between pooled-connection health checks. `0` disables. |
+| `redis_max_connections`          | `int \| None` | `None`                    | Cap on the connection pool size. `None` uses redis-py's default. |
+| `redis_retries`                  | `int`         | `1`                       | Retries (with exponential backoff) on transient connection/timeout errors. `0` disables. |
+| `redis_fail_open`                | `bool`        | `False`                   | On Redis outage, `fail_secure` governs by default. Set `True` to skip the failing check and let the request through, treating Redis outages as an availability concern distinct from other check failures. |
 
 ___
 
@@ -318,6 +324,7 @@ Logging
 |-----------------------|-------------------------------------------------|------------|------------------------------------------|
 | `log_suspicious_level`| `"INFO" \| "DEBUG" \| "WARNING" \| "ERROR" \| "CRITICAL" \| None` | `"WARNING"` | Log level for suspicious requests. `None` disables. |
 | `log_request_level`   | Same as above                                   | `None`     | Log level for all requests. `None` disables. |
+| `log_country_check_level` | Same as above (default `"INFO"`)            | `"INFO"`   | Log level for non-block country verdicts (whitelisted / not-affected). `None` disables. Blocked-country hits always log at `WARNING`; no-rules / no-geolocation always log at `DEBUG`. |
 | `log_format`          | `"text" \| "json"`                              | `"text"`   | Log output format.                       |
 | `custom_log_file`     | `str \| None`                                   | `None`     | Path to a custom log file.               |
 

docs/internals/check-implementations.md

@@ -199,9 +199,9 @@ ___
 
 **Purpose**: Periodically refreshes cloud provider IP ranges.
 
-**Blocks**: Never.
+**Blocks**: Never. The refresh runs as a single-flight background task (via `cloud_handler.schedule_refresh`, which invokes the middleware's `refresh_cloud_ip_ranges()`), so the request that crosses the interval is never delayed by provider fetches.
 
-**Triggers when**: `config.block_cloud_providers` is set and `cloud_ip_refresh_interval` seconds have elapsed since the last refresh.
+**Triggers when**: `config.block_cloud_providers` is set and `cloud_ip_refresh_interval` seconds have elapsed since the last refresh. If scheduling fails, the debounce timestamp is restored so the next request retries.
 
 ___
 

docs/internals/cloud-providers.md

@@ -214,17 +214,27 @@ cloud_ip_refresh_interval: int = Field(
 )
 ```
 
-The `CloudIpRefreshCheck` pipeline check triggers a refresh when enough time has elapsed:
+The `CloudIpRefreshCheck` pipeline check schedules a refresh when enough time has elapsed:
 
 ```python
 class CloudIpRefreshCheck(SecurityCheck):
     async def check(self, request: GuardRequest) -> GuardResponse | None:
+        if not self.config.block_cloud_providers:
+            return None
+
         if (
-            self.config.block_cloud_providers
-            and time.time() - self.middleware.last_cloud_ip_refresh
+            time.time() - self.middleware.last_cloud_ip_refresh
             > self.config.cloud_ip_refresh_interval
         ):
-            await self.middleware.refresh_cloud_ip_ranges()
+            previous_refresh = self.middleware.last_cloud_ip_refresh
+            self.middleware.last_cloud_ip_refresh = int(time.time())
+            scheduled = await cloud_handler.schedule_refresh(
+                {str(provider) for provider in self.config.block_cloud_providers},
+                ttl=self.config.cloud_ip_refresh_interval,
+                refresh=self.middleware.refresh_cloud_ip_ranges,
+            )
+            if not scheduled:
+                self.middleware.last_cloud_ip_refresh = previous_refresh
         return None
 ```
 
@@ -233,6 +243,20 @@ This check runs on every request but only performs work when:
 - `block_cloud_providers` is configured.
 - The elapsed time since the last refresh exceeds `cloud_ip_refresh_interval`.
 
+The refresh itself never runs on the request path. `schedule_refresh` fires the
+middleware's `refresh_cloud_ip_ranges()` as a single-flight background task:
+while one refresh is in flight, further calls are no-ops, so a slow provider
+fetch cannot block or stampede request handling. The debounce timestamp is
+bumped up front so concurrent requests don't all try to schedule, and restored
+if scheduling fails so the next request retries instead of waiting a full
+interval. Because the background task calls the middleware protocol method,
+adapter overrides of `refresh_cloud_ip_ranges` stay on the periodic path.
+
+The in-memory cloud-IP store honors the `ttl` passed at refresh time (the
+Redis-backed store always did), so cached ranges expire after
+`cloud_ip_refresh_interval` and the next refresh fetches fresh data in
+non-Redis deployments too.
+
 The default interval is **3600 seconds (1 hour)**. The minimum allowed value is **60 seconds**.
 
 ### Range Change Logging

docs/internals/redis.md

@@ -36,7 +36,9 @@ redis_manager = RedisManager(config)
 await redis_manager.initialize()
 ```
 
-Creates a `redis.asyncio.Redis` connection from `config.redis_url` with `decode_responses=True`. Pings to verify connectivity. Raises `GuardRedisError(503)` on failure.
+Creates a `redis.asyncio.Redis` connection from `config.redis_url` with `decode_responses=True`, applying the configured socket timeouts (`redis_socket_timeout`, `redis_socket_connect_timeout`), pool cap (`redis_max_connections`), health-check interval (`redis_health_check_interval`), and — when `redis_retries > 0` — a client-level `Retry` with exponential backoff on connection/timeout errors. Pings to verify connectivity. Raises `GuardRedisError(503)` on failure.
+
+Note that the client-level retry re-sends non-idempotent commands: a lost reply after the server already committed an `INCR` over-counts by one. For guard-core's rate-limit counters that fails closed (mildly over-restrictive, self-heals next window); callers needing exactly-once semantics should not build on `incr()`.
 
 **Close**:
 
@@ -134,16 +136,24 @@ class GuardRedisError(GuardCoreError):
 
 Adapters should catch `GuardRedisError` during initialization and handle it according to their framework's error model.
 
+When a `GuardRedisError` escapes a security check at request time (a Redis outage mid-request), the pipeline honors `fail_secure` by default: the request is blocked with a 500. Setting `redis_fail_open=True` opts into skipping the failing check and letting the request through, treating Redis outages as an availability concern distinct from other check failures.
+
 ___
 
 Configuration
 -------------
 
-| Field          | Type          | Default                   | Description                              |
-|----------------|---------------|---------------------------|------------------------------------------|
-| `enable_redis` | `bool`        | `True`                    | Master switch for Redis integration      |
-| `redis_url`    | `str \| None` | `"redis://localhost:6379"`| Redis connection URL                     |
-| `redis_prefix` | `str`         | `"guard_core:"`           | Key prefix for namespace isolation       |
+| Field                            | Type           | Default                   | Description                              |
+|----------------------------------|----------------|---------------------------|------------------------------------------|
+| `enable_redis`                   | `bool`         | `True`                    | Master switch for Redis integration      |
+| `redis_url`                      | `str \| None`  | `"redis://localhost:6379"`| Redis connection URL                     |
+| `redis_prefix`                   | `str`          | `"guard_core:"`           | Key prefix for namespace isolation       |
+| `redis_socket_connect_timeout`   | `float \| None`| `2.0`                     | Seconds to wait establishing a TCP connection (must be positive; `None` disables) |
+| `redis_socket_timeout`           | `float \| None`| `2.0`                     | Seconds to wait on a read/write (must be positive; `None` disables) |
+| `redis_health_check_interval`    | `int`          | `30`                      | Seconds between pooled-connection health checks (`0` disables) |
+| `redis_max_connections`          | `int \| None`  | `None`                    | Connection-pool cap (`None` uses redis-py's default) |
+| `redis_retries`                  | `int`          | `1`                       | Client-level retries with exponential backoff (`0` disables) |
+| `redis_fail_open`                | `bool`         | `False`                   | On Redis outage, skip the failing check instead of honoring `fail_secure` |
 
 ### Adapter Considerations