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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: guard-core
-Version: 2.2.2
+Version: 3.1.0
 Summary: Framework-agnostic security engine for the Guard ecosystem.
 Author-email: Renzo Franceschini <rennf93@users.noreply.github.com>
 License: MIT
@@ -308,6 +308,23 @@ See the [SecurityConfig Reference](https://rennf93.github.io/guard-core/latest/c
 
 ___
 
+Migration: fail_secure default flipped
+--------------------------------------
+
+`SecurityConfig.fail_secure` now defaults to `True`. When a security check raises an unexpected exception, the request is blocked with HTTP 500 instead of falling through.
+
+**Why**: the old fail-open default silently masked check bugs. The new default surfaces them so they can be fixed instead of leaking past the security layer.
+
+**Migration**: to restore the previous fail-open behavior, opt in explicitly:
+
+```python
+config = SecurityConfig(fail_secure=False)
+```
+
+Recommended path: keep the new default and fix any check exceptions that surface. The old default could mask genuine bugs.
+
+___
+
 Detection Engine
 ----------------
 

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

@@ -250,6 +250,23 @@ See the [SecurityConfig Reference](https://rennf93.github.io/guard-core/latest/c
 
 ___
 
+Migration: fail_secure default flipped
+--------------------------------------
+
+`SecurityConfig.fail_secure` now defaults to `True`. When a security check raises an unexpected exception, the request is blocked with HTTP 500 instead of falling through.
+
+**Why**: the old fail-open default silently masked check bugs. The new default surfaces them so they can be fixed instead of leaking past the security layer.
+
+**Migration**: to restore the previous fail-open behavior, opt in explicitly:
+
+```python
+config = SecurityConfig(fail_secure=False)
+```
+
+Recommended path: keep the new default and fix any check exceptions that surface. The old default could mask genuine bugs.
+
+___
+
 Detection Engine
 ----------------
 

{guard_core-2.2.2/guard_core/sync → guard_core-3.1.0/guard_core}/core/events/event_types.py

@@ -28,6 +28,7 @@ EVENT_PATH_EXCLUDED = "path_excluded"
 EVENT_PATTERN_ADDED = "pattern_added"
 EVENT_PATTERN_REMOVED = "pattern_removed"
 EVENT_RATE_LIMITED = "rate_limited"
+EVENT_RATE_LIMIT_SCRIPT_RELOADED = "rate_limit_script_reloaded"
 EVENT_REDIS_CONNECTION = "redis_connection"
 EVENT_REDIS_ERROR = "redis_error"
 EVENT_SECURITY_BYPASS = "security_bypass"
@@ -61,6 +62,7 @@ EVENT_TYPE_VALUES: frozenset[str] = frozenset(
         EVENT_PATTERN_ADDED,
         EVENT_PATTERN_REMOVED,
         EVENT_RATE_LIMITED,
+        EVENT_RATE_LIMIT_SCRIPT_RELOADED,
         EVENT_REDIS_CONNECTION,
         EVENT_REDIS_ERROR,
         EVENT_SECURITY_BYPASS,

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

@@ -1,6 +1,8 @@
 import asyncio
 import logging
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
+
+from guard_core.protocols.cloud_ip_store_protocol import CloudIpStoreProtocol
 
 if TYPE_CHECKING:
     from guard_core.core.events.metrics import MetricsCollector
@@ -116,21 +118,37 @@ class HandlerInitializer:
         )
 
     async def _run_lazy_init(self) -> None:
-        try:
-            from guard_core.handlers.cloud_handler import cloud_handler
+        from guard_core.handlers.cloud_handler import cloud_handler
 
-            if self.config.block_cloud_providers:
+        if self.config.block_cloud_providers:
+            try:
                 await cloud_handler.initialize_redis(
                     self.redis_handler,
-                    self.config.block_cloud_providers,
+                    cast(set[str], self.config.block_cloud_providers),
                     ttl=self.config.cloud_ip_refresh_interval,
                 )
-            if self.geo_ip_handler is not None:
+            except Exception as e:
+                self.logger.warning(
+                    "Lazy cloud-IP initialization failed: %s", e, exc_info=True
+                )
+
+        if self.geo_ip_handler is not None:
+            try:
                 await self.geo_ip_handler.initialize_redis(self.redis_handler)
-        except Exception as e:
-            self.logger.warning(
-                "Lazy background initialization failed: %s", e, exc_info=True
-            )
+            except Exception as e:
+                self.logger.warning(
+                    "Lazy geo-IP initialization failed: %s", e, exc_info=True
+                )
+
+    def _resolve_cloud_ip_store(self) -> CloudIpStoreProtocol:
+        store = self.config.cloud_ip_store
+        needs_invocation = isinstance(store, type) or (
+            callable(store) and not isinstance(store, CloudIpStoreProtocol)
+        )
+        if needs_invocation:
+            factory = cast(Any, store)
+            return cast(CloudIpStoreProtocol, factory(self.redis_handler))
+        return cast(CloudIpStoreProtocol, store)
 
     async def initialize_redis_handlers(self) -> None:
         if not (self.config.enable_redis and self.redis_handler):
@@ -143,7 +161,7 @@ class HandlerInitializer:
         from guard_core.handlers.suspatterns_handler import sus_patterns_handler
 
         if self.config.cloud_ip_store is not None:
-            cloud_handler.set_store(self.config.cloud_ip_store)
+            cloud_handler.set_store(self._resolve_cloud_ip_store())
 
         if self.config.lazy_init:
             self._lazy_init_task = asyncio.create_task(self._run_lazy_init())
@@ -151,7 +169,7 @@ class HandlerInitializer:
             if self.config.block_cloud_providers:
                 await cloud_handler.initialize_redis(
                     self.redis_handler,
-                    self.config.block_cloud_providers,
+                    cast(set[str], self.config.block_cloud_providers),
                     ttl=self.config.cloud_ip_refresh_interval,
                 )
             if self.geo_ip_handler is not None:

{guard_core-2.2.2 → guard_core-3.1.0}/guard_core/decorators/access_control.py

@@ -1,7 +1,9 @@
+import logging
 from collections.abc import Callable
-from typing import Any
+from typing import Any, cast
 
 from guard_core.decorators.base import BaseSecurityMixin, DecoratedFunction
+from guard_core.models import VALID_CLOUD_PROVIDERS, CloudProvider
 
 
 class AccessControlMixin(BaseSecurityMixin):
@@ -25,7 +27,7 @@ class AccessControlMixin(BaseSecurityMixin):
     ) -> Callable[[Callable[..., Any]], DecoratedFunction]:
         def decorator(func: Callable[..., Any]) -> DecoratedFunction:
             route_config = self._ensure_route_config(func)
-            route_config.blocked_countries = countries
+            route_config.blocked_countries = [c.upper() for c in countries]
             return self._apply_route_config(func)
 
         return decorator
@@ -35,7 +37,7 @@ class AccessControlMixin(BaseSecurityMixin):
     ) -> Callable[[Callable[..., Any]], DecoratedFunction]:
         def decorator(func: Callable[..., Any]) -> DecoratedFunction:
             route_config = self._ensure_route_config(func)
-            route_config.whitelist_countries = countries
+            route_config.whitelist_countries = [c.upper() for c in countries]
             return self._apply_route_config(func)
 
         return decorator
@@ -46,9 +48,18 @@ class AccessControlMixin(BaseSecurityMixin):
         def decorator(func: Callable[..., Any]) -> DecoratedFunction:
             route_config = self._ensure_route_config(func)
             if providers is None:
-                route_config.block_cloud_providers = {"AWS", "GCP", "Azure"}
+                route_config.block_cloud_providers = cast(
+                    set[CloudProvider], {"AWS", "GCP", "Azure"}
+                )
             else:
-                route_config.block_cloud_providers = set(providers)
+                valid = {p for p in providers if p in VALID_CLOUD_PROVIDERS}
+                route_config.block_cloud_providers = cast(set[CloudProvider], valid)
+                invalid = set(providers) - valid
+                if invalid:
+                    logging.getLogger("guard_core.decorators").warning(
+                        "@block_clouds: ignored unknown cloud providers %s",
+                        sorted(invalid),
+                    )
             return self._apply_route_config(func)
 
         return decorator

{guard_core-2.2.2 → guard_core-3.1.0}/guard_core/decorators/base.py

@@ -3,7 +3,7 @@ from datetime import datetime, timezone
 from typing import Any, Protocol, cast, runtime_checkable
 
 from guard_core.handlers.behavior_handler import BehaviorRule, BehaviorTracker
-from guard_core.models import SecurityConfig
+from guard_core.models import CloudProvider, SecurityConfig
 from guard_core.protocols.request_protocol import GuardRequest
 
 
@@ -29,7 +29,7 @@ class RouteConfig:
         self.blocked_user_agents: list[str] = []
         self.required_headers: dict[str, str] = {}
         self.behavior_rules: list[BehaviorRule] = []
-        self.block_cloud_providers: set[str] = set()
+        self.block_cloud_providers: set[CloudProvider] = set()
         self.max_request_size: int | None = None
         self.allowed_content_types: list[str] | None = None
         self.time_restrictions: dict[str, str] | None = None

{guard_core-2.2.2 → guard_core-3.1.0}/guard_core/handlers/cloud_handler.py

@@ -94,7 +94,92 @@ async def fetch_azure_ip_ranges() -> set[ipaddress.IPv4Network | ipaddress.IPv6N
         return set()
 
 
-_ALL_PROVIDERS = set({"AWS", "GCP", "Azure"})
+async def fetch_digitalocean_ip_ranges() -> set[
+    ipaddress.IPv4Network | ipaddress.IPv6Network
+]:
+    try:
+        async with aiohttp.ClientSession() as session:
+            response = await session.get(
+                "https://www.digitalocean.com/geo/google.csv",
+                timeout=aiohttp.ClientTimeout(total=10),
+            )
+            response.raise_for_status()
+            body = await response.text()
+
+        networks: set[ipaddress.IPv4Network | ipaddress.IPv6Network] = set()
+        for raw_line in body.splitlines():
+            line = raw_line.strip()
+            if not line or line.startswith("#"):
+                continue
+            prefix = line.split(",", 1)[0].strip()
+            if not prefix:
+                continue
+            try:
+                networks.add(ipaddress.ip_network(prefix))
+            except ValueError:
+                continue
+        return networks
+    except Exception as e:
+        logging.error(f"Failed to fetch DigitalOcean IP ranges: {str(e)}")
+        return set()
+
+
+async def fetch_linode_ip_ranges() -> set[
+    ipaddress.IPv4Network | ipaddress.IPv6Network
+]:
+    try:
+        async with aiohttp.ClientSession() as session:
+            response = await session.get(
+                "https://geoip.linode.com/",
+                timeout=aiohttp.ClientTimeout(total=10),
+            )
+            response.raise_for_status()
+            body = await response.text()
+
+        networks: set[ipaddress.IPv4Network | ipaddress.IPv6Network] = set()
+        for raw_line in body.splitlines():
+            line = raw_line.strip()
+            if not line or line.startswith("#"):
+                continue
+            prefix = line.split(",", 1)[0].strip()
+            if not prefix:
+                continue
+            try:
+                networks.add(ipaddress.ip_network(prefix))
+            except ValueError:
+                continue
+        return networks
+    except Exception as e:
+        logging.error(f"Failed to fetch Linode IP ranges: {str(e)}")
+        return set()
+
+
+async def fetch_vultr_ip_ranges() -> set[ipaddress.IPv4Network | ipaddress.IPv6Network]:
+    try:
+        async with aiohttp.ClientSession() as session:
+            response = await session.get(
+                "https://geofeed.constant.com/?json",
+                timeout=aiohttp.ClientTimeout(total=10),
+            )
+            response.raise_for_status()
+            data = await response.json(content_type=None)
+
+        networks: set[ipaddress.IPv4Network | ipaddress.IPv6Network] = set()
+        for entry in data.get("subnets", []):
+            prefix = entry.get("ip_prefix")
+            if not prefix:
+                continue
+            try:
+                networks.add(ipaddress.ip_network(prefix))
+            except ValueError:
+                continue
+        return networks
+    except Exception as e:
+        logging.error(f"Failed to fetch Vultr IP ranges: {str(e)}")
+        return set()
+
+
+_ALL_PROVIDERS = set({"AWS", "GCP", "Azure", "DigitalOcean", "Linode", "Vultr"})
 
 
 class CloudManager:
@@ -113,6 +198,9 @@ class CloudManager:
                 "AWS": set(),
                 "GCP": set(),
                 "Azure": set(),
+                "DigitalOcean": set(),
+                "Linode": set(),
+                "Vultr": set(),
             }
             cls._instance.last_updated = {provider: None for provider in _ALL_PROVIDERS}
             cls._instance.redis_handler = None
@@ -146,6 +234,9 @@ class CloudManager:
                     "AWS": fetch_aws_ip_ranges,
                     "GCP": fetch_gcp_ip_ranges,
                     "Azure": fetch_azure_ip_ranges,
+                    "DigitalOcean": fetch_digitalocean_ip_ranges,
+                    "Linode": fetch_linode_ip_ranges,
+                    "Vultr": fetch_vultr_ip_ranges,
                 }[provider]()
                 if ranges:
                     old_ranges = self.ip_ranges.get(provider, set())
@@ -195,6 +286,9 @@ class CloudManager:
                     "AWS": fetch_aws_ip_ranges,
                     "GCP": fetch_gcp_ip_ranges,
                     "Azure": fetch_azure_ip_ranges,
+                    "DigitalOcean": fetch_digitalocean_ip_ranges,
+                    "Linode": fetch_linode_ip_ranges,
+                    "Vultr": fetch_vultr_ip_ranges,
                 }[provider]
 
                 ranges = await fetch_func()
@@ -233,6 +327,9 @@ class CloudManager:
                     "AWS": fetch_aws_ip_ranges,
                     "GCP": fetch_gcp_ip_ranges,
                     "Azure": fetch_azure_ip_ranges,
+                    "DigitalOcean": fetch_digitalocean_ip_ranges,
+                    "Linode": fetch_linode_ip_ranges,
+                    "Vultr": fetch_vultr_ip_ranges,
                 }[provider]
                 ranges = await fetch_func()
                 if ranges:

{guard_core-2.2.2 → guard_core-3.1.0}/guard_core/handlers/cloud_ip_stores.py

@@ -27,7 +27,7 @@ class RedisCloudIpStore:
     def __init__(
         self,
         redis_handler: RedisHandlerProtocol,
-        key_prefix: str = "guard:cloud_ip",
+        key_prefix: str = "cloud_ip",
     ) -> None:
         self._redis = redis_handler
         self._prefix = key_prefix

{guard_core-2.2.2 → guard_core-3.1.0}/guard_core/handlers/dynamic_rule_handler.py

@@ -3,9 +3,14 @@ import logging
 import time
 from copy import deepcopy
 from datetime import datetime, timezone
-from typing import Any
+from typing import Any, cast
 
-from guard_core.models import DynamicRules, SecurityConfig
+from guard_core.models import (
+    VALID_CLOUD_PROVIDERS,
+    CloudProvider,
+    DynamicRules,
+    SecurityConfig,
+)
 
 
 class DynamicRuleManager:
@@ -247,12 +252,18 @@ class DynamicRuleManager:
         self, blocked: list[str], allowed: list[str]
     ) -> None:
         if blocked:
-            self.config.blocked_countries = blocked
-            self.logger.info(f"Dynamic rule: Blocked countries {blocked}")
+            normalized_blocked = frozenset(c.upper() for c in blocked)
+            self.config.blocked_countries = normalized_blocked
+            self.logger.info(
+                f"Dynamic rule: Blocked countries {sorted(normalized_blocked)}"
+            )
 
         if allowed:
-            self.config.whitelist_countries = allowed
-            self.logger.info(f"Dynamic rule: Whitelisted countries {allowed}")
+            normalized_allowed = frozenset(c.upper() for c in allowed)
+            self.config.whitelist_countries = normalized_allowed
+            self.logger.info(
+                f"Dynamic rule: Whitelisted countries {sorted(normalized_allowed)}"
+            )
 
     async def _apply_rate_limit_rules(self, rules: DynamicRules) -> None:
         if rules.global_rate_limit:
@@ -272,8 +283,14 @@ class DynamicRuleManager:
             )
 
     async def _apply_cloud_provider_rules(self, providers: set[str]) -> None:
-        self.config.block_cloud_providers = providers
-        self.logger.info(f"Dynamic rule: Blocked cloud providers {providers}")
+        valid = {p for p in providers if p in VALID_CLOUD_PROVIDERS}
+        self.config.block_cloud_providers = cast(set[CloudProvider], valid)
+        invalid = providers - valid
+        if invalid:
+            self.logger.warning(
+                f"Dynamic rule: ignored unknown cloud providers {sorted(invalid)}"
+            )
+        self.logger.info(f"Dynamic rule: Blocked cloud providers {valid}")
 
     async def _apply_user_agent_rules(self, user_agents: list[str]) -> None:
         self.config.blocked_user_agents = user_agents

{guard_core-2.2.2 → guard_core-3.1.0}/guard_core/handlers/ratelimit_handler.py

@@ -5,7 +5,7 @@ from collections.abc import Awaitable, Callable
 from datetime import datetime, timezone
 from typing import Any, Optional
 
-from redis.exceptions import RedisError
+from redis.exceptions import NoScriptError, RedisError
 
 from guard_core.models import SecurityConfig
 from guard_core.protocols.request_protocol import GuardRequest
@@ -54,6 +54,23 @@ class RateLimitManager:
     async def initialize_agent(self, agent_handler: Any) -> None:
         self.agent_handler = agent_handler
 
+    async def _emit_script_reloaded_event(self) -> None:
+        if not self.agent_handler:
+            return
+        try:
+            from guard_agent import SecurityEvent
+
+            event = SecurityEvent(
+                timestamp=datetime.now(timezone.utc),
+                event_type="rate_limit_script_reloaded",
+                ip_address="system",
+                action_taken="script_reloaded",
+                reason="NOSCRIPT recovery: Lua script re-cached on Redis",
+            )
+            await self.agent_handler.send_event(event)
+        except Exception as e:
+            self.logger.error(f"Failed to send script-reload event: {e}")
+
     async def _get_redis_request_count(
         self,
         client_ip: str,
@@ -78,14 +95,31 @@ class RateLimitManager:
         try:
             if self.rate_limit_script_sha:
                 async with self.redis_handler.get_connection() as conn:
-                    count = await conn.evalsha(
-                        self.rate_limit_script_sha,
-                        1,
-                        key_name,
-                        current_time,
-                        window,
-                        limit,
-                    )
+                    try:
+                        count = await conn.evalsha(
+                            self.rate_limit_script_sha,
+                            1,
+                            key_name,
+                            current_time,
+                            window,
+                            limit,
+                        )
+                    except NoScriptError:
+                        self.rate_limit_script_sha = await conn.script_load(
+                            RATE_LIMIT_SCRIPT
+                        )
+                        self.logger.info(
+                            "Rate limit Lua script reloaded after NOSCRIPT"
+                        )
+                        await self._emit_script_reloaded_event()
+                        count = await conn.evalsha(
+                            self.rate_limit_script_sha,
+                            1,
+                            key_name,
+                            current_time,
+                            window,
+                            limit,
+                        )
                 return int(count)
             else:
                 async with self.redis_handler.get_connection() as conn: