guard-core 2.2.0__tar.gz → 2.2.2__tar.gz

{guard_core-2.2.0/guard_core.egg-info → guard_core-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: guard-core
-Version: 2.2.0
+Version: 2.2.2
 Summary: Framework-agnostic security engine for the Guard ecosystem.
 Author-email: Renzo Franceschini <rennf93@users.noreply.github.com>
 License: MIT
@@ -65,7 +65,7 @@ Dynamic: license-file
 ___
 
 <p align="center">
-    <strong>guard-core is the framework-agnostic security engine that powers the Guard ecosystem. It provides IP control, rate limiting, penetration detection, security headers, and behavioral analysis through a protocol-based architecture. Framework-specific adapters (fastapi-guard, flaskapi-guard, djapi-guard) consume this library.</strong>
+    <strong>guard-core is the framework-agnostic security engine that powers the Guard ecosystem. It provides IP control, rate limiting, signature-based attack-pattern detection, security headers, and threshold-based behavior tracking through a protocol-based architecture. Framework-specific adapters (fastapi-guard, flaskapi-guard, djapi-guard) consume this library.</strong>
 </p>
 
 <p align="center">
@@ -178,7 +178,7 @@ Features
 - **HTTP Security Headers**: CSP, HSTS, X-Frame-Options, and OWASP best practices.
 - **Cloud Provider IP Blocking**: Block requests from AWS, GCP, Azure IP ranges.
 - **IP Geolocation**: Country-based access control via GeoIP databases.
-- **Behavioral Analysis**: Usage monitoring, return pattern detection, frequency analysis.
+- **Threshold-Based Behavior Tracking**: Per-IP request counting, response-pattern matching, suspicious-frequency triggers (deterministic threshold matching, not learning-based).
 - **Security Decorators**: Route-level security with composable decorator mixins.
 - **Detection Engine**: Multi-layered threat detection with regex, semantic analysis, and performance monitoring.
 - **Distributed State Management**: Redis integration for shared state across instances.
@@ -186,6 +186,18 @@ Features
 
 ___
 
+How Detection Works
+-------------------
+
+1. Request inputs (query, headers, body) are decoded through up to 7 layers covering URL, HTML entities, base64, hex, Unicode escapes, and SQL comments.
+2. Decoded content is matched against ~64 regex patterns across 16 attack categories, with patterns context-filtered to relevant input zones.
+3. Matched payloads receive a multi-metric semantic score combining keyword overlap, Shannon entropy, encoding-layer count, and obfuscation indicators.
+4. ReDoS protection enforces a 0.1s pattern-validation timeout and a 2-5s match timeout per pattern.
+
+The engine is signature-based with multi-metric semantic scoring on top. It is not machine-learning-based and does not learn from traffic.
+
+___
+
 Installation
 ------------
 
@@ -304,7 +316,7 @@ Multi-layered threat detection:
 - **PatternCompiler**: ReDoS-safe regex compilation with LRU caching and timeout protection.
 - **ContentPreprocessor**: Unicode normalization, encoding detection, attack-region-aware truncation.
 - **SemanticAnalyzer**: Attack probability scoring, entropy analysis, obfuscation detection.
-- **PerformanceMonitor**: Anomaly detection, slow pattern tracking, statistical analysis.
+- **PerformanceMonitor**: Slow-pattern detection via execution-time statistics (mean/stddev thresholds), not anomaly learning.
 
 See the [Detection Engine Internals](https://rennf93.github.io/guard-core/latest/internals/detection-engine/) for details.
 

{guard_core-2.2.0 → guard_core-2.2.2}/README.md

@@ -7,7 +7,7 @@
 ___
 
 <p align="center">
-    <strong>guard-core is the framework-agnostic security engine that powers the Guard ecosystem. It provides IP control, rate limiting, penetration detection, security headers, and behavioral analysis through a protocol-based architecture. Framework-specific adapters (fastapi-guard, flaskapi-guard, djapi-guard) consume this library.</strong>
+    <strong>guard-core is the framework-agnostic security engine that powers the Guard ecosystem. It provides IP control, rate limiting, signature-based attack-pattern detection, security headers, and threshold-based behavior tracking through a protocol-based architecture. Framework-specific adapters (fastapi-guard, flaskapi-guard, djapi-guard) consume this library.</strong>
 </p>
 
 <p align="center">
@@ -120,7 +120,7 @@ Features
 - **HTTP Security Headers**: CSP, HSTS, X-Frame-Options, and OWASP best practices.
 - **Cloud Provider IP Blocking**: Block requests from AWS, GCP, Azure IP ranges.
 - **IP Geolocation**: Country-based access control via GeoIP databases.
-- **Behavioral Analysis**: Usage monitoring, return pattern detection, frequency analysis.
+- **Threshold-Based Behavior Tracking**: Per-IP request counting, response-pattern matching, suspicious-frequency triggers (deterministic threshold matching, not learning-based).
 - **Security Decorators**: Route-level security with composable decorator mixins.
 - **Detection Engine**: Multi-layered threat detection with regex, semantic analysis, and performance monitoring.
 - **Distributed State Management**: Redis integration for shared state across instances.
@@ -128,6 +128,18 @@ Features
 
 ___
 
+How Detection Works
+-------------------
+
+1. Request inputs (query, headers, body) are decoded through up to 7 layers covering URL, HTML entities, base64, hex, Unicode escapes, and SQL comments.
+2. Decoded content is matched against ~64 regex patterns across 16 attack categories, with patterns context-filtered to relevant input zones.
+3. Matched payloads receive a multi-metric semantic score combining keyword overlap, Shannon entropy, encoding-layer count, and obfuscation indicators.
+4. ReDoS protection enforces a 0.1s pattern-validation timeout and a 2-5s match timeout per pattern.
+
+The engine is signature-based with multi-metric semantic scoring on top. It is not machine-learning-based and does not learn from traffic.
+
+___
+
 Installation
 ------------
 
@@ -246,7 +258,7 @@ Multi-layered threat detection:
 - **PatternCompiler**: ReDoS-safe regex compilation with LRU caching and timeout protection.
 - **ContentPreprocessor**: Unicode normalization, encoding detection, attack-region-aware truncation.
 - **SemanticAnalyzer**: Attack probability scoring, entropy analysis, obfuscation detection.
-- **PerformanceMonitor**: Anomaly detection, slow pattern tracking, statistical analysis.
+- **PerformanceMonitor**: Slow-pattern detection via execution-time statistics (mean/stddev thresholds), not anomaly learning.
 
 See the [Detection Engine Internals](https://rennf93.github.io/guard-core/latest/internals/detection-engine/) for details.
 

{guard_core-2.2.0 → guard_core-2.2.2}/guard_core/core/initialization/handler_initializer.py

@@ -184,7 +184,14 @@ class HandlerInitializer:
             await self.geo_ip_handler.initialize_agent(telemetry)
 
     async def initialize_dynamic_rule_manager(self) -> None:
-        if not (self.agent_handler and self.config.enable_dynamic_rules):
+        if not self.config.enable_dynamic_rules:
+            return
+        if not self.agent_handler:
+            self.logger.warning(
+                "Dynamic rules enabled but agent unavailable; falling back to "
+                "static config. Dashboard rule updates will not propagate until "
+                "agent connectivity is restored."
+            )
             return
 
         from guard_core.handlers.dynamic_rule_handler import DynamicRuleManager

{guard_core-2.2.0 → guard_core-2.2.2}/guard_core/core/responses/factory.py

@@ -1,3 +1,4 @@
+import logging
 from collections.abc import Awaitable, Callable
 
 from guard_core.core.responses.context import ResponseContext
@@ -12,6 +13,7 @@ from guard_core.utils import extract_client_ip
 class ErrorResponseFactory:
     def __init__(self, context: ResponseContext):
         self.context = context
+        self.logger = logging.getLogger("guard_core.core.responses.factory")
 
     async def create_error_response(
         self, status_code: int, default_message: str
@@ -61,10 +63,16 @@ class ErrorResponseFactory:
 
     async def apply_modifier(self, response: GuardResponse) -> GuardResponse:
         if self.context.config.custom_response_modifier:
-            result: GuardResponse = await self.context.config.custom_response_modifier(
-                response
-            )
-            return result
+            try:
+                result: GuardResponse = (
+                    await self.context.config.custom_response_modifier(response)
+                )
+                return result
+            except Exception as exc:
+                self.logger.exception(
+                    "custom_response_modifier raised %s; returning unmodified response",
+                    exc,
+                )
         return response
 
     async def process_response(

{guard_core-2.2.0 → guard_core-2.2.2}/guard_core/detection_engine/preprocessor.py

@@ -284,7 +284,7 @@ class ContentPreprocessor:
         return content
 
     async def decode_common_encodings(self, content: str) -> str:
-        max_decode_iterations = 3
+        max_decode_iterations = 7
         iterations = 0
 
         while iterations < max_decode_iterations:

{guard_core-2.2.0 → guard_core-2.2.2}/guard_core/handlers/ipban_handler.py

@@ -1,6 +1,7 @@
 import ipaddress
 import logging
 import time
+from collections.abc import Callable
 from datetime import datetime, timezone
 from typing import Any
 
@@ -9,12 +10,31 @@ from cachetools import TTLCache
 _Network = ipaddress.IPv4Network | ipaddress.IPv6Network
 
 
+class _ObservableTTLCache(TTLCache):
+    def __init__(
+        self,
+        maxsize: int,
+        ttl: float,
+        on_evict: Callable[[], None],
+    ) -> None:
+        super().__init__(maxsize=maxsize, ttl=ttl)
+        self._on_evict = on_evict
+
+    def popitem(self) -> tuple[Any, Any]:
+        item = super().popitem()
+        self._on_evict()
+        return item
+
+
 class IPBanManager:
     LOCAL_CACHE_TTL_CAP_SECONDS = 3600
+    _EVICTION_LOG_EVERY = 100
 
     _instance: "IPBanManager | None" = None
     banned_ips: TTLCache
     banned_networks: list[tuple[_Network, float]]
+    evictions_count: int
+    logger: logging.Logger
     config: Any = None
     redis_handler: Any = None
     agent_handler: Any = None
@@ -22,14 +42,26 @@ class IPBanManager:
     def __new__(cls: type["IPBanManager"]) -> "IPBanManager":
         if cls._instance is None:
             cls._instance = super().__new__(cls)
-            cls._instance.banned_ips = TTLCache(
-                maxsize=10000, ttl=cls.LOCAL_CACHE_TTL_CAP_SECONDS
+            cls._instance.evictions_count = 0
+            cls._instance.logger = logging.getLogger("guard_core.handlers.ipban")
+            cls._instance.banned_ips = _ObservableTTLCache(
+                maxsize=10000,
+                ttl=cls.LOCAL_CACHE_TTL_CAP_SECONDS,
+                on_evict=cls._instance._on_eviction,
             )
             cls._instance.banned_networks = []
             cls._instance.redis_handler = None
             cls._instance.agent_handler = None
         return cls._instance
 
+    def _on_eviction(self) -> None:
+        self.evictions_count += 1
+        if self.evictions_count % self._EVICTION_LOG_EVERY == 0:
+            self.logger.warning(
+                "IP ban cache full; %d entries evicted (silent overflow)",
+                self.evictions_count,
+            )
+
     async def initialize_redis(self, redis_handler: Any) -> None:
         self.redis_handler = redis_handler
 
@@ -115,9 +147,7 @@ class IPBanManager:
             )
             await self.agent_handler.send_event(event)
         except Exception as e:
-            logging.getLogger("guard_core.handlers.ipban").error(
-                f"Failed to send ban event to agent: {e}"
-            )
+            self.logger.error("Failed to send ban event to agent: %s", e)
 
     async def unban_ip(self, ip: str) -> None:
         if ip in self.banned_ips:
@@ -145,9 +175,7 @@ class IPBanManager:
             )
             await self.agent_handler.send_event(event)
         except Exception as e:
-            logging.getLogger("guard_core.handlers.ipban").error(
-                f"Failed to send unban event to agent: {e}"
-            )
+            self.logger.error("Failed to send unban event to agent: %s", e)
 
     def _check_network_cache(
         self, addr: ipaddress.IPv4Address | ipaddress.IPv6Address, now: float

{guard_core-2.2.0 → guard_core-2.2.2}/guard_core/handlers/ipinfo_handler.py

@@ -158,7 +158,10 @@ class IPInfoManager:
 
     def get_country(self, ip: str) -> str | None:
         if not self.reader:
-            raise RuntimeError("Database not initialized")
+            self.logger.warning(
+                "Geo-IP reader uninitialized; returning None for %s", ip
+            )
+            return None
 
         try:
             result = self.reader.get(ip)

{guard_core-2.2.0 → guard_core-2.2.2}/guard_core/handlers/redis_handler.py

@@ -22,11 +22,12 @@ class RedisManager:
     agent_handler: Any = None
 
     def __new__(cls: type["RedisManager"], config: SecurityConfig) -> "RedisManager":
-        cls._instance = super().__new__(cls)
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance.logger = logging.getLogger("guard_core.handlers.redis")
+            cls._instance.agent_handler = None
         cls._instance.config = config
-        cls._instance.logger = logging.getLogger("guard_core.handlers.redis")
         cls._instance._closed = False
-        cls._instance.agent_handler = None
         return cls._instance
 
     async def initialize_agent(self, agent_handler: Any) -> None:
@@ -54,10 +55,12 @@ class RedisManager:
             self.logger.error(f"Failed to send Redis event to agent: {e}")
 
     async def initialize(self) -> None:
-        if self._closed or not self.config.enable_redis:
+        if not self.config.enable_redis:
             self._redis = None
             return
 
+        self._closed = False
+
         async with self._connection_lock:
             try:
                 if self.config.redis_url is not None:

{guard_core-2.2.0 → guard_core-2.2.2}/guard_core/sync/core/initialization/handler_initializer.py

@@ -190,7 +190,14 @@ class HandlerInitializer:
             self.geo_ip_handler.initialize_agent(telemetry)
 
     def initialize_dynamic_rule_manager(self) -> None:
-        if not (self.agent_handler and self.config.enable_dynamic_rules):
+        if not self.config.enable_dynamic_rules:
+            return
+        if not self.agent_handler:
+            self.logger.warning(
+                "Dynamic rules enabled but agent unavailable; falling back to "
+                "static config. Dashboard rule updates will not propagate until "
+                "agent connectivity is restored."
+            )
             return
 
         from guard_core.sync.handlers.dynamic_rule_handler import DynamicRuleManager

{guard_core-2.2.0 → guard_core-2.2.2}/guard_core/sync/core/responses/factory.py

@@ -1,3 +1,4 @@
+import logging
 from collections.abc import Callable
 
 from guard_core.protocols.response_protocol import GuardResponse
@@ -12,6 +13,7 @@ from guard_core.sync.utils import extract_client_ip
 class ErrorResponseFactory:
     def __init__(self, context: ResponseContext):
         self.context = context
+        self.logger = logging.getLogger("guard_core.sync.core.responses.factory")
 
     def create_error_response(
         self, status_code: int, default_message: str
@@ -59,10 +61,16 @@ class ErrorResponseFactory:
 
     def apply_modifier(self, response: GuardResponse) -> GuardResponse:
         if self.context.config.custom_response_modifier:
-            result: GuardResponse = self.context.config.custom_response_modifier(
-                response
-            )
-            return result
+            try:
+                result: GuardResponse = self.context.config.custom_response_modifier(
+                    response
+                )
+                return result
+            except Exception as exc:
+                self.logger.exception(
+                    "custom_response_modifier raised %s; returning unmodified response",
+                    exc,
+                )
         return response
 
     def process_response(

{guard_core-2.2.0 → guard_core-2.2.2}/guard_core/sync/detection_engine/preprocessor.py

@@ -284,7 +284,7 @@ class ContentPreprocessor:
         return content
 
     def decode_common_encodings(self, content: str) -> str:
-        max_decode_iterations = 3
+        max_decode_iterations = 7
         iterations = 0
 
         while iterations < max_decode_iterations:

{guard_core-2.2.0 → guard_core-2.2.2}/guard_core/sync/handlers/ipban_handler.py

@@ -1,6 +1,7 @@
 import ipaddress
 import logging
 import time
+from collections.abc import Callable
 from datetime import datetime, timezone
 from typing import Any
 
@@ -9,12 +10,31 @@ from cachetools import TTLCache
 _Network = ipaddress.IPv4Network | ipaddress.IPv6Network
 
 
+class _ObservableTTLCache(TTLCache):
+    def __init__(
+        self,
+        maxsize: int,
+        ttl: float,
+        on_evict: Callable[[], None],
+    ) -> None:
+        super().__init__(maxsize=maxsize, ttl=ttl)
+        self._on_evict = on_evict
+
+    def popitem(self) -> tuple[Any, Any]:
+        item = super().popitem()
+        self._on_evict()
+        return item
+
+
 class IPBanManager:
     LOCAL_CACHE_TTL_CAP_SECONDS = 3600
+    _EVICTION_LOG_EVERY = 100
 
     _instance: "IPBanManager | None" = None
     banned_ips: TTLCache
     banned_networks: list[tuple[_Network, float]]
+    evictions_count: int
+    logger: logging.Logger
     config: Any = None
     redis_handler: Any = None
     agent_handler: Any = None
@@ -22,14 +42,26 @@ class IPBanManager:
     def __new__(cls: type["IPBanManager"]) -> "IPBanManager":
         if cls._instance is None:
             cls._instance = super().__new__(cls)
-            cls._instance.banned_ips = TTLCache(
-                maxsize=10000, ttl=cls.LOCAL_CACHE_TTL_CAP_SECONDS
+            cls._instance.evictions_count = 0
+            cls._instance.logger = logging.getLogger("guard_core.sync.handlers.ipban")
+            cls._instance.banned_ips = _ObservableTTLCache(
+                maxsize=10000,
+                ttl=cls.LOCAL_CACHE_TTL_CAP_SECONDS,
+                on_evict=cls._instance._on_eviction,
             )
             cls._instance.banned_networks = []
             cls._instance.redis_handler = None
             cls._instance.agent_handler = None
         return cls._instance
 
+    def _on_eviction(self) -> None:
+        self.evictions_count += 1
+        if self.evictions_count % self._EVICTION_LOG_EVERY == 0:
+            self.logger.warning(
+                "IP ban cache full; %d entries evicted (silent overflow)",
+                self.evictions_count,
+            )
+
     def initialize_redis(self, redis_handler: Any) -> None:
         self.redis_handler = redis_handler
 
@@ -113,9 +145,7 @@ class IPBanManager:
             )
             self.agent_handler.send_event(event)
         except Exception as e:
-            logging.getLogger("guard_core.sync.handlers.ipban").error(
-                f"Failed to send ban event to agent: {e}"
-            )
+            self.logger.error("Failed to send ban event to agent: %s", e)
 
     def unban_ip(self, ip: str) -> None:
         if ip in self.banned_ips:
@@ -143,9 +173,7 @@ class IPBanManager:
             )
             self.agent_handler.send_event(event)
         except Exception as e:
-            logging.getLogger("guard_core.sync.handlers.ipban").error(
-                f"Failed to send unban event to agent: {e}"
-            )
+            self.logger.error("Failed to send unban event to agent: %s", e)
 
     def _check_network_cache(
         self, addr: ipaddress.IPv4Address | ipaddress.IPv6Address, now: float

{guard_core-2.2.0 → guard_core-2.2.2}/guard_core/sync/handlers/ipinfo_handler.py

@@ -157,7 +157,10 @@ class IPInfoManager:
 
     def get_country(self, ip: str) -> str | None:
         if not self.reader:
-            raise RuntimeError("Database not initialized")
+            self.logger.warning(
+                "Geo-IP reader uninitialized; returning None for %s", ip
+            )
+            return None
 
         try:
             result = self.reader.get(ip)

{guard_core-2.2.0 → guard_core-2.2.2}/guard_core/sync/handlers/redis_handler.py

@@ -22,11 +22,12 @@ class RedisManager:
     agent_handler: Any = None
 
     def __new__(cls: type["RedisManager"], config: SecurityConfig) -> "RedisManager":
-        cls._instance = super().__new__(cls)
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance.logger = logging.getLogger("guard_core.sync.handlers.redis")
+            cls._instance.agent_handler = None
         cls._instance.config = config
-        cls._instance.logger = logging.getLogger("guard_core.sync.handlers.redis")
         cls._instance._closed = False
-        cls._instance.agent_handler = None
         return cls._instance
 
     def initialize_agent(self, agent_handler: Any) -> None:
@@ -54,10 +55,12 @@ class RedisManager:
             self.logger.error(f"Failed to send Redis event to agent: {e}")
 
     def initialize(self) -> None:
-        if self._closed or not self.config.enable_redis:
+        if not self.config.enable_redis:
             self._redis = None
             return
 
+        self._closed = False
+
         with self._connection_lock:
             try:
                 if self.config.redis_url is not None:

{guard_core-2.2.0 → guard_core-2.2.2/guard_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: guard-core
-Version: 2.2.0
+Version: 2.2.2
 Summary: Framework-agnostic security engine for the Guard ecosystem.
 Author-email: Renzo Franceschini <rennf93@users.noreply.github.com>
 License: MIT
@@ -65,7 +65,7 @@ Dynamic: license-file
 ___
 
 <p align="center">
-    <strong>guard-core is the framework-agnostic security engine that powers the Guard ecosystem. It provides IP control, rate limiting, penetration detection, security headers, and behavioral analysis through a protocol-based architecture. Framework-specific adapters (fastapi-guard, flaskapi-guard, djapi-guard) consume this library.</strong>
+    <strong>guard-core is the framework-agnostic security engine that powers the Guard ecosystem. It provides IP control, rate limiting, signature-based attack-pattern detection, security headers, and threshold-based behavior tracking through a protocol-based architecture. Framework-specific adapters (fastapi-guard, flaskapi-guard, djapi-guard) consume this library.</strong>
 </p>
 
 <p align="center">
@@ -178,7 +178,7 @@ Features
 - **HTTP Security Headers**: CSP, HSTS, X-Frame-Options, and OWASP best practices.
 - **Cloud Provider IP Blocking**: Block requests from AWS, GCP, Azure IP ranges.
 - **IP Geolocation**: Country-based access control via GeoIP databases.
-- **Behavioral Analysis**: Usage monitoring, return pattern detection, frequency analysis.
+- **Threshold-Based Behavior Tracking**: Per-IP request counting, response-pattern matching, suspicious-frequency triggers (deterministic threshold matching, not learning-based).
 - **Security Decorators**: Route-level security with composable decorator mixins.
 - **Detection Engine**: Multi-layered threat detection with regex, semantic analysis, and performance monitoring.
 - **Distributed State Management**: Redis integration for shared state across instances.
@@ -186,6 +186,18 @@ Features
 
 ___
 
+How Detection Works
+-------------------
+
+1. Request inputs (query, headers, body) are decoded through up to 7 layers covering URL, HTML entities, base64, hex, Unicode escapes, and SQL comments.
+2. Decoded content is matched against ~64 regex patterns across 16 attack categories, with patterns context-filtered to relevant input zones.
+3. Matched payloads receive a multi-metric semantic score combining keyword overlap, Shannon entropy, encoding-layer count, and obfuscation indicators.
+4. ReDoS protection enforces a 0.1s pattern-validation timeout and a 2-5s match timeout per pattern.
+
+The engine is signature-based with multi-metric semantic scoring on top. It is not machine-learning-based and does not learn from traffic.
+
+___
+
 Installation
 ------------
 
@@ -304,7 +316,7 @@ Multi-layered threat detection:
 - **PatternCompiler**: ReDoS-safe regex compilation with LRU caching and timeout protection.
 - **ContentPreprocessor**: Unicode normalization, encoding detection, attack-region-aware truncation.
 - **SemanticAnalyzer**: Attack probability scoring, entropy analysis, obfuscation detection.
-- **PerformanceMonitor**: Anomaly detection, slow pattern tracking, statistical analysis.
+- **PerformanceMonitor**: Slow-pattern detection via execution-time statistics (mean/stddev thresholds), not anomaly learning.
 
 See the [Detection Engine Internals](https://rennf93.github.io/guard-core/latest/internals/detection-engine/) for details.
 

{guard_core-2.2.0 → guard_core-2.2.2}/guard_core.egg-info/SOURCES.txt

@@ -215,6 +215,8 @@ tests/test_handler_initializer_factories.py
 tests/test_handler_initializer_lazy_init.py
 tests/test_handlers_integration.py
 tests/test_ipban_cidr.py
+tests/test_ipban_eviction.py
+tests/test_ipban_lifecycle.py
 tests/test_ipban_ttl.py
 tests/test_ipinfo_lifecycle.py
 tests/test_logfire_handler.py

{guard_core-2.2.0 → guard_core-2.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "guard-core"
-version = "2.2.0"
+version = "2.2.2"
 description = "Framework-agnostic security engine for the Guard ecosystem."
 authors = [
     {name = "Renzo Franceschini", email = "rennf93@users.noreply.github.com"}

guard_core-2.2.2/tests/test_ipban_eviction.py

@@ -0,0 +1,85 @@
+import logging
+import time
+from collections.abc import Generator
+
+import pytest
+
+from guard_core.handlers.ipban_handler import (
+    IPBanManager,
+    _ObservableTTLCache,
+)
+
+
+@pytest.fixture(autouse=True)
+def reset_singleton() -> Generator[None, None, None]:
+    IPBanManager._instance = None
+    yield
+    IPBanManager._instance = None
+
+
+def _swap_in_small_cache(manager: IPBanManager, maxsize: int) -> None:
+    manager.banned_ips = _ObservableTTLCache(
+        maxsize=maxsize,
+        ttl=manager.LOCAL_CACHE_TTL_CAP_SECONDS,
+        on_evict=manager._on_eviction,
+    )
+
+
+@pytest.mark.asyncio
+async def test_banned_ips_overflow_increments_eviction_counter_and_logs_at_threshold(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    manager = IPBanManager()
+    manager.redis_handler = None
+    _swap_in_small_cache(manager, maxsize=2)
+
+    caplog.set_level(logging.WARNING, logger="guard_core.handlers.ipban")
+
+    await manager.ban_ip("10.0.0.1", duration=300, reason="t")
+    await manager.ban_ip("10.0.0.2", duration=300, reason="t")
+    await manager.ban_ip("10.0.0.3", duration=300, reason="t")
+
+    assert manager.evictions_count == 1
+    assert not [r for r in caplog.records if r.levelno == logging.WARNING]
+
+    for i in range(4, 103):
+        await manager.ban_ip(f"10.0.{i // 256}.{i % 256}", duration=300, reason="t")
+
+    assert manager.evictions_count == 100
+    warnings = [r for r in caplog.records if r.levelno == logging.WARNING]
+    assert len(warnings) == 1
+    assert "100" in warnings[0].getMessage()
+    assert "silent overflow" in warnings[0].getMessage()
+
+
+@pytest.mark.asyncio
+async def test_ttl_expiry_does_not_increment_eviction_counter() -> None:
+    manager = IPBanManager()
+    manager.redis_handler = None
+    manager.banned_ips = _ObservableTTLCache(
+        maxsize=10, ttl=1, on_evict=manager._on_eviction
+    )
+
+    await manager.ban_ip("10.0.0.1", duration=1, reason="t")
+    await manager.ban_ip("10.0.0.2", duration=1, reason="t")
+
+    time.sleep(1.1)
+
+    await manager.ban_ip("10.0.0.3", duration=1, reason="t")
+
+    assert manager.evictions_count == 0
+
+
+@pytest.mark.asyncio
+async def test_eviction_counter_persists_across_singleton_calls() -> None:
+    manager = IPBanManager()
+    manager.redis_handler = None
+    _swap_in_small_cache(manager, maxsize=1)
+
+    await manager.ban_ip("10.0.0.1", duration=300, reason="t")
+    await manager.ban_ip("10.0.0.2", duration=300, reason="t")
+    assert manager.evictions_count == 1
+
+    second = IPBanManager()
+    assert second is manager
+    assert second.evictions_count == 1