guard-core 0.1.0__tar.gz

guard_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Renzo F
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

guard_core-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: guard-core
+Version: 0.1.0
+Summary: Framework-agnostic security engine for the Guard ecosystem.
+Author-email: Renzo Franceschini <rennf93@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/rennf93/guard-core
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cachetools
+Requires-Dist: httpx
+Requires-Dist: maxminddb
+Requires-Dist: pydantic
+Requires-Dist: redis
+Requires-Dist: requests
+Requires-Dist: typing-extensions
+Provides-Extra: dev
+Requires-Dist: bandit[toml]; extra == "dev"
+Requires-Dist: deptry; extra == "dev"
+Requires-Dist: fastapi-guard-agent; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Requires-Dist: mkdocs; extra == "dev"
+Requires-Dist: mkdocstrings; extra == "dev"
+Requires-Dist: mkdocstrings-python; extra == "dev"
+Requires-Dist: mkdocs-material; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pip-audit; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pymarkdownlnt; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: radon; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: safety; extra == "dev"
+Requires-Dist: types-cachetools; extra == "dev"
+Requires-Dist: types-requests; extra == "dev"
+Requires-Dist: vulture; extra == "dev"
+Requires-Dist: xenon; extra == "dev"
+Dynamic: license-file
+
+# guard-core
+API Guard Core - Core library for Guard Agent, FastAPI Guard, FlaskAPI Guard and DjAPI Guard

guard_core-0.1.0/README.md

@@ -0,0 +1,2 @@
+# guard-core
+API Guard Core - Core library for Guard Agent, FastAPI Guard, FlaskAPI Guard and DjAPI Guard

guard_core-0.1.0/guard_core/__init__.py

@@ -0,0 +1,42 @@
+from guard_core.decorators import RouteConfig, SecurityDecorator
+from guard_core.handlers.behavior_handler import BehaviorRule, BehaviorTracker
+from guard_core.handlers.cloud_handler import CloudManager, cloud_handler
+from guard_core.handlers.ipban_handler import IPBanManager, ip_ban_manager
+from guard_core.handlers.ipinfo_handler import IPInfoManager
+from guard_core.handlers.ratelimit_handler import RateLimitManager, rate_limit_handler
+from guard_core.handlers.redis_handler import RedisManager, redis_handler
+from guard_core.handlers.security_headers_handler import (
+    SecurityHeadersManager,
+    security_headers_manager,
+)
+from guard_core.handlers.suspatterns_handler import sus_patterns_handler
+from guard_core.models import SecurityConfig
+from guard_core.protocols.geo_ip_protocol import GeoIPHandler
+from guard_core.protocols.redis_protocol import RedisHandlerProtocol
+from guard_core.protocols.request_protocol import GuardRequest
+from guard_core.protocols.response_protocol import GuardResponse, GuardResponseFactory
+
+__all__ = [
+    "SecurityConfig",
+    "SecurityDecorator",
+    "RouteConfig",
+    "BehaviorTracker",
+    "BehaviorRule",
+    "ip_ban_manager",
+    "IPBanManager",
+    "cloud_handler",
+    "CloudManager",
+    "IPInfoManager",
+    "rate_limit_handler",
+    "RateLimitManager",
+    "redis_handler",
+    "RedisManager",
+    "security_headers_manager",
+    "SecurityHeadersManager",
+    "sus_patterns_handler",
+    "GeoIPHandler",
+    "RedisHandlerProtocol",
+    "GuardRequest",
+    "GuardResponse",
+    "GuardResponseFactory",
+]

guard_core-0.1.0/guard_core/core/__init__.py

@@ -0,0 +1,3 @@
+from guard_core.core.events import MetricsCollector, SecurityEventBus
+
+__all__ = ["SecurityEventBus", "MetricsCollector"]

guard_core-0.1.0/guard_core/core/behavioral/__init__.py

@@ -0,0 +1,4 @@
+from guard_core.core.behavioral.context import BehavioralContext
+from guard_core.core.behavioral.processor import BehavioralProcessor
+
+__all__ = ["BehavioralContext", "BehavioralProcessor"]

guard_core-0.1.0/guard_core/core/behavioral/context.py

@@ -0,0 +1,14 @@
+from dataclasses import dataclass
+from logging import Logger
+
+from guard_core.core.events import SecurityEventBus
+from guard_core.decorators.base import BaseSecurityDecorator
+from guard_core.models import SecurityConfig
+
+
+@dataclass
+class BehavioralContext:
+    config: SecurityConfig
+    logger: Logger
+    event_bus: SecurityEventBus
+    guard_decorator: BaseSecurityDecorator | None

guard_core-0.1.0/guard_core/core/behavioral/processor.py

@@ -0,0 +1,95 @@
+from guard_core.core.behavioral.context import BehavioralContext
+from guard_core.decorators.base import RouteConfig
+from guard_core.protocols.request_protocol import GuardRequest
+from guard_core.protocols.response_protocol import GuardResponse
+
+
+class BehavioralProcessor:
+    def __init__(self, context: BehavioralContext) -> None:
+        self.context = context
+
+    async def process_usage_rules(
+        self, request: GuardRequest, client_ip: str, route_config: RouteConfig
+    ) -> None:
+        if not self.context.guard_decorator:
+            return
+
+        endpoint_id = self.get_endpoint_id(request)
+        for rule in route_config.behavior_rules:
+            if rule.rule_type in ["usage", "frequency"]:
+                behavior_tracker = self.context.guard_decorator.behavior_tracker
+                threshold_exceeded = await behavior_tracker.track_endpoint_usage(
+                    endpoint_id, client_ip, rule
+                )
+                if threshold_exceeded:
+                    details = f"{rule.threshold} calls in {rule.window}s"
+                    message = f"Behavioral {rule.rule_type}"
+                    reason = "threshold exceeded"
+
+                    await self.context.event_bus.send_middleware_event(
+                        event_type="decorator_violation",
+                        request=request,
+                        action_taken="behavioral_action_triggered",
+                        reason=f"{message} {reason}: {details}",
+                        decorator_type="behavioral",
+                        violation_type=rule.rule_type,
+                        threshold=rule.threshold,
+                        window=rule.window,
+                        action=rule.action,
+                        endpoint_id=endpoint_id,
+                    )
+
+                    await self.context.guard_decorator.behavior_tracker.apply_action(
+                        rule,
+                        client_ip,
+                        endpoint_id,
+                        f"Usage threshold exceeded: {details}",
+                    )
+
+    async def process_return_rules(
+        self,
+        request: GuardRequest,
+        response: GuardResponse,
+        client_ip: str,
+        route_config: RouteConfig,
+    ) -> None:
+        if not self.context.guard_decorator:
+            return
+
+        endpoint_id = self.get_endpoint_id(request)
+        for rule in route_config.behavior_rules:
+            if rule.rule_type == "return_pattern":
+                behavior_tracker = self.context.guard_decorator.behavior_tracker
+                pattern_detected = await behavior_tracker.track_return_pattern(
+                    endpoint_id, client_ip, response, rule
+                )
+                if pattern_detected:
+                    details = f"{rule.threshold} for '{rule.pattern}' in {rule.window}s"
+
+                    await self.context.event_bus.send_middleware_event(
+                        event_type="decorator_violation",
+                        request=request,
+                        action_taken="behavioral_action_triggered",
+                        reason=f"Return pattern threshold exceeded: {details}",
+                        decorator_type="behavioral",
+                        violation_type="return_pattern",
+                        threshold=rule.threshold,
+                        window=rule.window,
+                        pattern=rule.pattern,
+                        action=rule.action,
+                        endpoint_id=endpoint_id,
+                    )
+
+                    await self.context.guard_decorator.behavior_tracker.apply_action(
+                        rule,
+                        client_ip,
+                        endpoint_id,
+                        f"Return pattern threshold exceeded: {details}",
+                    )
+
+    def get_endpoint_id(self, request: GuardRequest) -> str:
+        if hasattr(request, "scope") and "route" in request.scope:
+            route = request.scope["route"]
+            if hasattr(route, "endpoint"):
+                return f"{route.endpoint.__module__}.{route.endpoint.__qualname__}"
+        return f"{request.method}:{request.url_path}"

guard_core-0.1.0/guard_core/core/bypass/__init__.py

@@ -0,0 +1,4 @@
+from guard_core.core.bypass.context import BypassContext
+from guard_core.core.bypass.handler import BypassHandler
+
+__all__ = ["BypassContext", "BypassHandler"]

guard_core-0.1.0/guard_core/core/bypass/context.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+from logging import Logger
+
+from guard_core.core.events import SecurityEventBus
+from guard_core.core.responses import ErrorResponseFactory
+from guard_core.core.routing import RouteConfigResolver
+from guard_core.core.validation import RequestValidator
+from guard_core.models import SecurityConfig
+
+
+@dataclass
+class BypassContext:
+    config: SecurityConfig
+    logger: Logger
+    event_bus: SecurityEventBus
+    route_resolver: RouteConfigResolver
+    response_factory: ErrorResponseFactory
+    validator: RequestValidator

guard_core-0.1.0/guard_core/core/bypass/handler.py

@@ -0,0 +1,52 @@
+from collections.abc import Awaitable, Callable
+
+from guard_core.core.bypass.context import BypassContext
+from guard_core.decorators.base import RouteConfig
+from guard_core.protocols.request_protocol import GuardRequest
+from guard_core.protocols.response_protocol import GuardResponse
+
+
+class BypassHandler:
+    def __init__(self, context: BypassContext) -> None:
+        self.context = context
+
+    async def handle_passthrough(
+        self,
+        request: GuardRequest,
+        call_next: Callable[[GuardRequest], Awaitable[GuardResponse]],
+    ) -> GuardResponse | None:
+        if not request.client_host:
+            response = await call_next(request)
+            return await self.context.response_factory.apply_modifier(response)
+
+        if await self.context.validator.is_path_excluded(request):
+            response = await call_next(request)
+            return await self.context.response_factory.apply_modifier(response)
+
+        return None
+
+    async def handle_security_bypass(
+        self,
+        request: GuardRequest,
+        call_next: Callable[[GuardRequest], Awaitable[GuardResponse]],
+        route_config: RouteConfig | None,
+    ) -> GuardResponse | None:
+        if not route_config or not self.context.route_resolver.should_bypass_check(
+            "all", route_config
+        ):
+            return None
+
+        await self.context.event_bus.send_middleware_event(
+            event_type="security_bypass",
+            request=request,
+            action_taken="all_checks_bypassed",
+            reason="Route configured to bypass all security checks",
+            bypassed_checks=list(route_config.bypassed_checks),
+            endpoint=str(request.url_path),
+        )
+
+        if not self.context.config.passive_mode:
+            response = await call_next(request)
+            return await self.context.response_factory.apply_modifier(response)
+
+        return None

guard_core-0.1.0/guard_core/core/checks/__init__.py

@@ -0,0 +1,43 @@
+from guard_core.core.checks.base import SecurityCheck
+from guard_core.core.checks.implementations import (
+    AuthenticationCheck,
+    CloudIpRefreshCheck,
+    CloudProviderCheck,
+    CustomRequestCheck,
+    CustomValidatorsCheck,
+    EmergencyModeCheck,
+    HttpsEnforcementCheck,
+    IpSecurityCheck,
+    RateLimitCheck,
+    ReferrerCheck,
+    RequestLoggingCheck,
+    RequestSizeContentCheck,
+    RequiredHeadersCheck,
+    RouteConfigCheck,
+    SuspiciousActivityCheck,
+    TimeWindowCheck,
+    UserAgentCheck,
+)
+from guard_core.core.checks.pipeline import SecurityCheckPipeline
+
+__all__ = [
+    "SecurityCheck",
+    "SecurityCheckPipeline",
+    "RouteConfigCheck",
+    "EmergencyModeCheck",
+    "HttpsEnforcementCheck",
+    "RequestLoggingCheck",
+    "RequestSizeContentCheck",
+    "RequiredHeadersCheck",
+    "AuthenticationCheck",
+    "ReferrerCheck",
+    "CustomValidatorsCheck",
+    "TimeWindowCheck",
+    "CloudIpRefreshCheck",
+    "IpSecurityCheck",
+    "CloudProviderCheck",
+    "UserAgentCheck",
+    "RateLimitCheck",
+    "SuspiciousActivityCheck",
+    "CustomRequestCheck",
+]

guard_core-0.1.0/guard_core/core/checks/base.py

@@ -0,0 +1,48 @@
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+from guard_core.protocols.request_protocol import GuardRequest
+from guard_core.protocols.response_protocol import GuardResponse
+
+if TYPE_CHECKING:
+    from guard_core.protocols.middleware_protocol import GuardMiddlewareProtocol
+
+
+class SecurityCheck(ABC):
+    def __init__(self, middleware: "GuardMiddlewareProtocol") -> None:
+        self.middleware = middleware
+        self.config = middleware.config
+        self.logger = middleware.logger
+
+    @abstractmethod
+    async def check(self, request: GuardRequest) -> GuardResponse | None:
+        pass  # pragma: no cover
+
+    @property
+    @abstractmethod
+    def check_name(self) -> str:
+        pass  # pragma: no cover
+
+    async def send_event(
+        self,
+        event_type: str,
+        request: GuardRequest,
+        action_taken: str,
+        reason: str,
+        **kwargs: Any,
+    ) -> None:
+        await self.middleware.event_bus.send_middleware_event(
+            event_type=event_type,
+            request=request,
+            action_taken=action_taken,
+            reason=reason,
+            **kwargs,
+        )
+
+    async def create_error_response(
+        self, status_code: int, default_message: str
+    ) -> GuardResponse:
+        return await self.middleware.create_error_response(status_code, default_message)
+
+    def is_passive_mode(self) -> bool:
+        return self.config.passive_mode

guard_core-0.1.0/guard_core/core/checks/helpers.py

@@ -0,0 +1,174 @@
+import re
+from ipaddress import ip_address, ip_network
+from typing import Any
+from urllib.parse import urlparse
+
+from guard_core.decorators.base import RouteConfig
+from guard_core.models import SecurityConfig
+from guard_core.protocols.request_protocol import GuardRequest
+from guard_core.utils import detect_penetration_attempt
+
+
+def is_ip_in_blacklist(client_ip: str, ip_addr: object, blacklist: list[str]) -> bool:
+    for blocked in blacklist:
+        if "/" in blocked:
+            if ip_addr in ip_network(blocked, strict=False):
+                return True
+        elif client_ip == blocked:
+            return True
+    return False
+
+
+def is_ip_in_whitelist(
+    client_ip: str, ip_addr: object, whitelist: list[str]
+) -> bool | None:
+    if not whitelist:
+        return None
+
+    for allowed in whitelist:
+        if "/" in allowed:
+            if ip_addr in ip_network(allowed, strict=False):
+                return True
+        elif client_ip == allowed:
+            return True
+    return False
+
+
+def check_country_access(
+    client_ip: str, route_config: RouteConfig, geo_ip_handler: Any
+) -> bool | None:
+    if not geo_ip_handler:
+        return None
+
+    country = None
+
+    if route_config.blocked_countries:
+        country = geo_ip_handler.get_country(client_ip)
+        if country and country in route_config.blocked_countries:
+            return False
+
+    if route_config.whitelist_countries:
+        if country is None:
+            country = geo_ip_handler.get_country(client_ip)
+
+        if country:
+            return country in route_config.whitelist_countries
+        return False
+
+    return None
+
+
+def _check_ip_blacklist(
+    client_ip: str, ip_addr: object, route_config: RouteConfig
+) -> bool:
+    if not route_config.ip_blacklist:
+        return False
+    return is_ip_in_blacklist(client_ip, ip_addr, route_config.ip_blacklist)
+
+
+def _check_ip_whitelist(
+    client_ip: str, ip_addr: object, route_config: RouteConfig
+) -> bool | None:
+    return is_ip_in_whitelist(client_ip, ip_addr, route_config.ip_whitelist or [])
+
+
+async def check_route_ip_access(
+    client_ip: str, route_config: RouteConfig, middleware: Any
+) -> bool | None:
+    try:
+        ip_addr = ip_address(client_ip)
+
+        if _check_ip_blacklist(client_ip, ip_addr, route_config):
+            return False
+
+        whitelist_result = _check_ip_whitelist(client_ip, ip_addr, route_config)
+        if whitelist_result is not None:
+            return whitelist_result
+
+        country_result = check_country_access(
+            client_ip, route_config, middleware.geo_ip_handler
+        )
+        if country_result is not None:
+            return country_result
+
+        return None
+    except ValueError:
+        return False
+
+
+async def check_user_agent_allowed(
+    user_agent: str, route_config: RouteConfig | None, config: Any
+) -> bool:
+    from guard_core.utils import is_user_agent_allowed as global_user_agent_check
+
+    if route_config and route_config.blocked_user_agents:
+        for pattern in route_config.blocked_user_agents:
+            if re.search(pattern, user_agent, re.IGNORECASE):
+                return False
+
+    return await global_user_agent_check(user_agent, config)
+
+
+def validate_auth_header(auth_header: str, auth_type: str) -> tuple[bool, str]:
+    if auth_type == "bearer":
+        if not auth_header.startswith("Bearer "):
+            return False, "Missing or invalid Bearer token"
+    elif auth_type == "basic":
+        if not auth_header.startswith("Basic "):
+            return False, "Missing or invalid Basic authentication"
+    else:
+        if not auth_header:
+            return False, f"Missing {auth_type} authentication"
+
+    return True, ""
+
+
+def is_referrer_domain_allowed(referrer: str, allowed_domains: list[str]) -> bool:
+    try:
+        referrer_domain = urlparse(referrer).netloc.lower()
+        for allowed_domain in allowed_domains:
+            if referrer_domain == allowed_domain.lower() or referrer_domain.endswith(
+                f".{allowed_domain.lower()}"
+            ):
+                return True
+        return False
+    except Exception:
+        return False
+
+
+def _get_effective_penetration_setting(
+    config: SecurityConfig, route_config: RouteConfig | None
+) -> tuple[bool, bool | None]:
+    route_specific_detection = None
+    penetration_enabled = config.enable_penetration_detection
+
+    if route_config and hasattr(route_config, "enable_suspicious_detection"):
+        route_specific_detection = route_config.enable_suspicious_detection
+        penetration_enabled = route_specific_detection
+
+    return penetration_enabled, route_specific_detection
+
+
+def _get_detection_disabled_reason(
+    config: SecurityConfig, route_specific_detection: bool | None
+) -> str:
+    if route_specific_detection is False and config.enable_penetration_detection:
+        return "disabled_by_decorator"
+    return "not_enabled"
+
+
+async def detect_penetration_patterns(
+    request: GuardRequest,
+    route_config: RouteConfig | None,
+    config: SecurityConfig,
+    should_bypass_check_fn: Any,
+) -> tuple[bool, str]:
+    penetration_enabled, route_specific_detection = _get_effective_penetration_setting(
+        config, route_config
+    )
+
+    if penetration_enabled and not should_bypass_check_fn("penetration", route_config):
+        return await detect_penetration_attempt(request)
+
+    reason = _get_detection_disabled_reason(config, route_specific_detection)
+    return False, reason

guard_core-0.1.0/guard_core/core/checks/implementations/__init__.py

@@ -0,0 +1,65 @@
+from guard_core.core.checks.implementations.authentication import (
+    AuthenticationCheck,
+)
+from guard_core.core.checks.implementations.cloud_ip_refresh import (
+    CloudIpRefreshCheck,
+)
+from guard_core.core.checks.implementations.cloud_provider import (
+    CloudProviderCheck,
+)
+from guard_core.core.checks.implementations.custom_request import (
+    CustomRequestCheck,
+)
+from guard_core.core.checks.implementations.custom_validators import (
+    CustomValidatorsCheck,
+)
+from guard_core.core.checks.implementations.emergency_mode import (
+    EmergencyModeCheck,
+)
+from guard_core.core.checks.implementations.https_enforcement import (
+    HttpsEnforcementCheck,
+)
+from guard_core.core.checks.implementations.ip_security import (
+    IpSecurityCheck,
+)
+from guard_core.core.checks.implementations.rate_limit import RateLimitCheck
+from guard_core.core.checks.implementations.referrer import ReferrerCheck
+from guard_core.core.checks.implementations.request_logging import (
+    RequestLoggingCheck,
+)
+from guard_core.core.checks.implementations.request_size_content import (
+    RequestSizeContentCheck,
+)
+from guard_core.core.checks.implementations.required_headers import (
+    RequiredHeadersCheck,
+)
+from guard_core.core.checks.implementations.route_config import (
+    RouteConfigCheck,
+)
+from guard_core.core.checks.implementations.suspicious_activity import (
+    SuspiciousActivityCheck,
+)
+from guard_core.core.checks.implementations.time_window import (
+    TimeWindowCheck,
+)
+from guard_core.core.checks.implementations.user_agent import UserAgentCheck
+
+__all__ = [
+    "AuthenticationCheck",
+    "CloudIpRefreshCheck",
+    "CloudProviderCheck",
+    "CustomRequestCheck",
+    "CustomValidatorsCheck",
+    "EmergencyModeCheck",
+    "HttpsEnforcementCheck",
+    "IpSecurityCheck",
+    "RateLimitCheck",
+    "ReferrerCheck",
+    "RequestLoggingCheck",
+    "RequestSizeContentCheck",
+    "RequiredHeadersCheck",
+    "RouteConfigCheck",
+    "SuspiciousActivityCheck",
+    "TimeWindowCheck",
+    "UserAgentCheck",
+]