Skip to content

Security Decorators

The decorators module provides route-level security controls that can be applied to individual endpoints. These decorators offer fine-grained control over security policies on a per-route basis, complementing the global security pipeline. Framework adapters expose these decorators to their users through their own decorator interfaces.

Overview

Security decorators allow you to:

  • Apply specific security rules to individual routes
  • Override global security settings for specific endpoints
  • Combine multiple security measures in a clean, readable way
  • Implement behavioral analysis and monitoring per endpoint

Main Decorator Class

. SecurityDecorator

guard_core.decorators.SecurityDecorator(config)

Bases: BaseSecurityDecorator, AccessControlMixin, RateLimitingMixin, BehavioralMixin, AuthenticationMixin, ContentFilteringMixin, AdvancedMixin

Source code in guard_core/decorators/base.py 
45
46
47
48
49
def __init__(self, config: SecurityConfig) -> None:
    self.config = config
    self._route_configs: dict[str, RouteConfig] = {}
    self.behavior_tracker = BehaviorTracker(config)
    self.agent_handler: Any = None

The main decorator class that combines all security capabilities. This is the primary class you'll use in your application.

Example Usage:

from guard_core import SecurityConfig
from guard_core.decorators import SecurityDecorator

config = SecurityConfig()
guard_deco = SecurityDecorator(config)

@app.get("/api/sensitive")
@guard_deco.rate_limit(requests=5, window=300)
@guard_deco.require_ip(whitelist=["10.0.0.0/8"])
@guard_deco.block_countries(["CN", "RU"])
def sensitive_endpoint():
    return {"data": "sensitive"}

Base Classes

. BaseSecurityDecorator

guard_core.decorators.base.BaseSecurityDecorator(config)

Source code in guard_core/decorators/base.py 
45
46
47
48
49
def __init__(self, config: SecurityConfig) -> None:
    self.config = config
    self._route_configs: dict[str, RouteConfig] = {}
    self.behavior_tracker = BehaviorTracker(config)
    self.agent_handler: Any = None

agent_handler = None instance-attribute

behavior_tracker = BehaviorTracker(config) instance-attribute

config = config instance-attribute

get_route_config(route_id)

Source code in guard_core/decorators/base.py 
51
52
def get_route_config(self, route_id: str) -> RouteConfig | None:
    return self._route_configs.get(route_id)

initialize_agent(agent_handler) async

Source code in guard_core/decorators/base.py 
76
77
78
async def initialize_agent(self, agent_handler: Any) -> None:
    self.agent_handler = agent_handler
    await self.behavior_tracker.initialize_agent(agent_handler)

initialize_behavior_tracking(redis_handler=None) async

Source code in guard_core/decorators/base.py 
72
73
74
async def initialize_behavior_tracking(self, redis_handler: Any = None) -> None:
    if redis_handler:
        await self.behavior_tracker.initialize_redis(redis_handler)

send_access_denied_event(request, reason, decorator_type, **metadata) async

Source code in guard_core/decorators/base.py 
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
async def send_access_denied_event(
    self,
    request: GuardRequest,
    reason: str,
    decorator_type: str,
    **metadata: Any,
) -> None:
    await self.send_decorator_event(
        event_type="access_denied",
        request=request,
        action_taken="blocked",
        reason=reason,
        decorator_type=decorator_type,
        **metadata,
    )

send_authentication_failed_event(request, reason, auth_type, **metadata) async

Source code in guard_core/decorators/base.py 
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
async def send_authentication_failed_event(
    self,
    request: GuardRequest,
    reason: str,
    auth_type: str,
    **metadata: Any,
) -> None:
    await self.send_decorator_event(
        event_type="authentication_failed",
        request=request,
        action_taken="blocked",
        reason=reason,
        decorator_type="authentication",
        auth_type=auth_type,
        **metadata,
    )

send_decorator_event(event_type, request, action_taken, reason, decorator_type, **kwargs) async

Source code in guard_core/decorators/base.py 
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
async def send_decorator_event(
    self,
    event_type: str,
    request: GuardRequest,
    action_taken: str,
    reason: str,
    decorator_type: str,
    **kwargs: Any,
) -> None:
    if not self.agent_handler:
        return

    try:
        from guard_core.utils import extract_client_ip

        client_ip = await extract_client_ip(
            request, self.config, self.agent_handler
        )

        from guard_agent import SecurityEvent

        event = SecurityEvent(
            timestamp=datetime.now(timezone.utc),
            event_type=event_type,
            ip_address=client_ip,
            country=None,
            user_agent=request.headers.get("User-Agent"),
            action_taken=action_taken,
            reason=reason,
            endpoint=str(request.url_path),
            method=request.method,
            decorator_type=decorator_type,
            metadata=kwargs,
        )

        await self.agent_handler.send_event(event)

    except Exception as e:
        import logging

        logging.getLogger("guard_core.decorators.base").error(
            f"Failed to send decorator event to agent: {e}"
        )

send_decorator_violation_event(request, violation_type, reason, **metadata) async

Source code in guard_core/decorators/base.py 
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
async def send_decorator_violation_event(
    self,
    request: GuardRequest,
    violation_type: str,
    reason: str,
    **metadata: Any,
) -> None:
    await self.send_decorator_event(
        event_type="decorator_violation",
        request=request,
        action_taken="blocked",
        reason=reason,
        decorator_type=violation_type,
        **metadata,
    )

send_rate_limit_event(request, limit, window, **metadata) async

Source code in guard_core/decorators/base.py 
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
async def send_rate_limit_event(
    self,
    request: GuardRequest,
    limit: int,
    window: int,
    **metadata: Any,
) -> None:
    await self.send_decorator_event(
        event_type="rate_limited",
        request=request,
        action_taken="blocked",
        reason=f"Rate limit exceeded: {limit} requests per {window}s",
        decorator_type="rate_limiting",
        limit=limit,
        window=window,
        **metadata,
    )

Base class providing core decorator functionality and route configuration management.

. RouteConfig

guard_core.decorators.base.RouteConfig()

Source code in guard_core/decorators/base.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
def __init__(self) -> None:
    self.rate_limit: int | None = None
    self.rate_limit_window: int | None = None
    self.ip_whitelist: list[str] | None = None
    self.ip_blacklist: list[str] | None = None
    self.blocked_countries: list[str] | None = None
    self.whitelist_countries: list[str] | None = None
    self.bypassed_checks: set[str] = set()
    self.require_https: bool = False
    self.auth_required: str | None = None
    self.custom_validators: list[Callable] = []
    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.max_request_size: int | None = None
    self.allowed_content_types: list[str] | None = None
    self.time_restrictions: dict[str, str] | None = None
    self.enable_suspicious_detection: bool = True
    self.require_referrer: list[str] | None = None
    self.api_key_required: bool = False
    self.session_limits: dict[str, int] | None = None
    self.geo_rate_limits: dict[str, tuple[int, int]] | None = None

allowed_content_types = None instance-attribute

api_key_required = False instance-attribute

auth_required = None instance-attribute

behavior_rules = [] instance-attribute

block_cloud_providers = set() instance-attribute

blocked_countries = None instance-attribute

blocked_user_agents = [] instance-attribute

bypassed_checks = set() instance-attribute

custom_validators = [] instance-attribute

enable_suspicious_detection = True instance-attribute

geo_rate_limits = None instance-attribute

ip_blacklist = None instance-attribute

ip_whitelist = None instance-attribute

max_request_size = None instance-attribute

rate_limit = None instance-attribute

rate_limit_window = None instance-attribute

require_https = False instance-attribute

require_referrer = None instance-attribute

required_headers = {} instance-attribute

session_limits = None instance-attribute

time_restrictions = None instance-attribute

whitelist_countries = None instance-attribute

Configuration class that stores security settings for individual routes.

Mixin Classes

The decorator system uses mixins to organize different types of security features:

. AccessControlMixin

guard_core.decorators.access_control.AccessControlMixin

Bases: BaseSecurityMixin

allow_countries(countries)

Source code in guard_core/decorators/access_control.py 
33
34
35
36
37
38
39
40
41
def allow_countries(
    self, countries: list[str]
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        route_config.whitelist_countries = countries
        return self._apply_route_config(func)

    return decorator

block_clouds(providers=None)

Source code in guard_core/decorators/access_control.py 
43
44
45
46
47
48
49
50
51
52
53
54
def block_clouds(
    self, providers: list[str] | None = None
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        if providers is None:
            route_config.block_cloud_providers = {"AWS", "GCP", "Azure"}
        else:
            route_config.block_cloud_providers = set(providers)
        return self._apply_route_config(func)

    return decorator

block_countries(countries)

Source code in guard_core/decorators/access_control.py 
23
24
25
26
27
28
29
30
31
def block_countries(
    self, countries: list[str]
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        route_config.blocked_countries = countries
        return self._apply_route_config(func)

    return decorator

bypass(checks)

Source code in guard_core/decorators/access_control.py 
56
57
58
59
60
61
62
63
64
def bypass(
    self, checks: list[str]
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        route_config.bypassed_checks.update(checks)
        return self._apply_route_config(func)

    return decorator

require_ip(whitelist=None, blacklist=None)

Source code in guard_core/decorators/access_control.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
def require_ip(
    self,
    whitelist: list[str] | None = None,
    blacklist: list[str] | None = None,
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        if whitelist:
            route_config.ip_whitelist = whitelist
        if blacklist:
            route_config.ip_blacklist = blacklist
        return self._apply_route_config(func)

    return decorator

Provides IP-based and geographic access control decorators.

Available Decorators:

  • @guard_deco.require_ip(whitelist=[], blacklist=[]) - IP address filtering
  • @guard_deco.block_countries(countries=[]) - Block specific countries
  • @guard_deco.allow_countries(countries=[]) - Allow only specific countries
  • @guard_deco.block_clouds(providers=[]) - Block cloud provider IPs
  • @guard_deco.bypass(checks=[]) - Bypass specific security checks

. AuthenticationMixin

guard_core.decorators.authentication.AuthenticationMixin

Bases: BaseSecurityMixin

api_key_auth(header_name='X-API-Key')

Source code in guard_core/decorators/authentication.py 
26
27
28
29
30
31
32
33
34
35
def api_key_auth(
    self, header_name: str = "X-API-Key"
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        route_config.api_key_required = True
        route_config.required_headers[header_name] = "required"
        return self._apply_route_config(func)

    return decorator

require_auth(type='bearer')

Source code in guard_core/decorators/authentication.py 
16
17
18
19
20
21
22
23
24
def require_auth(
    self, type: str = "bearer"
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        route_config.auth_required = type
        return self._apply_route_config(func)

    return decorator

require_headers(headers)

Source code in guard_core/decorators/authentication.py 
37
38
39
40
41
42
43
44
45
def require_headers(
    self, headers: dict[str, str]
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        route_config.required_headers.update(headers)
        return self._apply_route_config(func)

    return decorator

require_https()

Source code in guard_core/decorators/authentication.py 
 8
 9
10
11
12
13
14
def require_https(self) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        route_config.require_https = True
        return self._apply_route_config(func)

    return decorator

Provides authentication and authorization decorators.

Available Decorators:

  • @guard_deco.require_https() - Force HTTPS
  • @guard_deco.require_auth(type="bearer") - Require authentication
  • @guard_deco.api_key_auth(header_name="X-API-Key") - API key authentication
  • @guard_deco.require_headers(headers={}) - Require specific headers

. RateLimitingMixin

guard_core.decorators.rate_limiting.RateLimitingMixin

Bases: BaseSecurityMixin

geo_rate_limit(limits)

Source code in guard_core/decorators/rate_limiting.py 
19
20
21
22
23
24
25
26
27
def geo_rate_limit(
    self, limits: dict[str, tuple[int, int]]
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        route_config.geo_rate_limits = limits
        return self._apply_route_config(func)

    return decorator

rate_limit(requests, window=60)

Source code in guard_core/decorators/rate_limiting.py 
 8
 9
10
11
12
13
14
15
16
17
def rate_limit(
    self, requests: int, window: int = 60
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        route_config.rate_limit = requests
        route_config.rate_limit_window = window
        return self._apply_route_config(func)

    return decorator

Provides rate limiting decorators.

Available Decorators:

  • @guard_deco.rate_limit(requests=10, window=60) - Basic rate limiting
  • @guard_deco.geo_rate_limit(limits={}) - Geographic rate limiting

. BehavioralMixin

guard_core.decorators.behavioral.BehavioralMixin

Bases: BaseSecurityMixin

behavior_analysis(rules)

Source code in guard_core/decorators/behavioral.py 
48
49
50
51
52
53
54
55
56
def behavior_analysis(
    self, rules: list[BehaviorRule]
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        route_config.behavior_rules.extend(rules)
        return self._apply_route_config(func)

    return decorator

return_monitor(pattern, max_occurrences, window=86400, action='ban')

Source code in guard_core/decorators/behavioral.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
def return_monitor(
    self,
    pattern: str,
    max_occurrences: int,
    window: int = 86400,
    action: Literal["ban", "log", "throttle", "alert"] = "ban",
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)

        rule = BehaviorRule(
            rule_type="return_pattern",
            threshold=max_occurrences,
            window=window,
            pattern=pattern,
            action=action,
        )
        route_config.behavior_rules.append(rule)
        return self._apply_route_config(func)

    return decorator

suspicious_frequency(max_frequency, window=300, action='ban')

Source code in guard_core/decorators/behavioral.py 
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
def suspicious_frequency(
    self,
    max_frequency: float,
    window: int = 300,
    action: Literal["ban", "log", "throttle", "alert"] = "ban",
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        max_calls = int(max_frequency * window)

        rule = BehaviorRule(
            rule_type="frequency",
            threshold=max_calls,
            window=window,
            action=action,
        )
        route_config.behavior_rules.append(rule)
        return self._apply_route_config(func)

    return decorator

usage_monitor(max_calls, window=3600, action='ban')

Source code in guard_core/decorators/behavioral.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
def usage_monitor(
    self,
    max_calls: int,
    window: int = 3600,
    action: Literal["ban", "log", "throttle", "alert"] = "ban",
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)

        rule = BehaviorRule(
            rule_type="usage", threshold=max_calls, window=window, action=action
        )
        route_config.behavior_rules.append(rule)
        return self._apply_route_config(func)

    return decorator

Provides behavioral analysis and monitoring decorators.

Available Decorators:

  • @guard_deco.usage_monitor(max_calls, window, action) - Monitor endpoint usage
  • @guard_deco.return_monitor(pattern, max_occurrences, window, action) - Monitor return patterns
  • @guard_deco.behavior_analysis(rules=[]) - Apply multiple behavioral rules
  • @guard_deco.suspicious_frequency(max_frequency, window, action) - Detect suspicious frequency

. ContentFilteringMixin

guard_core.decorators.content_filtering.ContentFilteringMixin

Bases: BaseSecurityMixin

block_user_agents(patterns)

Source code in guard_core/decorators/content_filtering.py 
10
11
12
13
14
15
16
17
18
def block_user_agents(
    self, patterns: list[str]
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        route_config.blocked_user_agents.extend(patterns)
        return self._apply_route_config(func)

    return decorator

content_type_filter(allowed_types)

Source code in guard_core/decorators/content_filtering.py 
20
21
22
23
24
25
26
27
28
def content_type_filter(
    self, allowed_types: list[str]
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        route_config.allowed_content_types = allowed_types
        return self._apply_route_config(func)

    return decorator

custom_validation(validator)

Source code in guard_core/decorators/content_filtering.py 
50
51
52
53
54
55
56
57
58
59
def custom_validation(
    self,
    validator: Callable[[GuardRequest], Awaitable[GuardResponse | None]],
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        route_config.custom_validators.append(validator)
        return self._apply_route_config(func)

    return decorator

max_request_size(size_bytes)

Source code in guard_core/decorators/content_filtering.py 
30
31
32
33
34
35
36
37
38
def max_request_size(
    self, size_bytes: int
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        route_config.max_request_size = size_bytes
        return self._apply_route_config(func)

    return decorator

require_referrer(allowed_domains)

Source code in guard_core/decorators/content_filtering.py 
40
41
42
43
44
45
46
47
48
def require_referrer(
    self, allowed_domains: list[str]
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        route_config.require_referrer = allowed_domains
        return self._apply_route_config(func)

    return decorator

Provides content and request filtering decorators.

Available Decorators:

  • @guard_deco.block_user_agents(patterns=[]) - Block user agent patterns
  • @guard_deco.content_type_filter(allowed_types=[]) - Filter content types
  • @guard_deco.max_request_size(size_bytes) - Limit request size
  • @guard_deco.require_referrer(allowed_domains=[]) - Require specific referrers
  • @guard_deco.custom_validation(validator) - Add custom validation logic

. AdvancedMixin

guard_core.decorators.advanced.AdvancedMixin

Bases: BaseSecurityMixin

honeypot_detection(trap_fields)

Source code in guard_core/decorators/advanced.py 
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def honeypot_detection(
    self, trap_fields: list[str]
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        async def honeypot_validator(
            request: GuardRequest,
        ) -> GuardResponse | None:
            def _has_trap_field_filled(data: dict[str, Any]) -> bool:
                return any(field in data and data[field] for field in trap_fields)

            async def _validate_form_data() -> GuardResponse | None:
                try:
                    raw = (await request.body()).decode()
                    parsed = parse_qs(raw)
                    flat = {k: v[0] for k, v in parsed.items() if v}
                    if _has_trap_field_filled(flat):
                        return _SimpleResponse("Forbidden", 403)
                except Exception:
                    pass
                return None

            async def _validate_json_data() -> GuardResponse | None:
                try:
                    raw = (await request.body()).decode()
                    json_data = json.loads(raw)
                    if _has_trap_field_filled(json_data):
                        return _SimpleResponse("Forbidden", 403)
                except Exception:
                    pass
                return None

            if request.method not in ["POST", "PUT", "PATCH"]:
                return None

            content_type = request.headers.get("content-type", "")

            if "application/x-www-form-urlencoded" in content_type:
                return await _validate_form_data()
            elif "application/json" in content_type:
                return await _validate_json_data()

            return None

        route_config = self._ensure_route_config(func)
        route_config.custom_validators.append(honeypot_validator)
        return self._apply_route_config(func)

    return decorator

suspicious_detection(enabled=True)

Source code in guard_core/decorators/advanced.py 
45
46
47
48
49
50
51
52
53
def suspicious_detection(
    self, enabled: bool = True
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        route_config.enable_suspicious_detection = enabled
        return self._apply_route_config(func)

    return decorator

time_window(start_time, end_time, timezone='UTC')

Source code in guard_core/decorators/advanced.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
def time_window(
    self, start_time: str, end_time: str, timezone: str = "UTC"
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        route_config = self._ensure_route_config(func)
        route_config.time_restrictions = {
            "start": start_time,
            "end": end_time,
            "timezone": timezone,
        }
        return self._apply_route_config(func)

    return decorator

Provides advanced detection and time-based decorators.

Available Decorators:

  • @guard_deco.time_window(start_time, end_time, timezone) - Time-based access control
  • @guard_deco.suspicious_detection(enabled=True) - Toggle suspicious pattern detection
  • @guard_deco.honeypot_detection(trap_fields=[]) - Detect bots using honeypot fields

Utility Functions

. get_route_decorator_config

guard_core.decorators.base.get_route_decorator_config(request, decorator_handler)

Source code in guard_core/decorators/base.py 
192
193
194
195
196
197
198
199
200
def get_route_decorator_config(
    request: GuardRequest, decorator_handler: BaseSecurityDecorator
) -> RouteConfig | None:
    if hasattr(request, "scope") and "route" in request.scope:
        route = request.scope["route"]
        if hasattr(route, "endpoint") and hasattr(route.endpoint, "_guard_route_id"):
            route_id = route.endpoint._guard_route_id
            return decorator_handler.get_route_config(route_id)
    return None

Extract route security configuration from the current FastAPI request.

Integration with Middleware

The decorators work in conjunction with the SecurityMiddleware to provide comprehensive protection:

  1. Route Configuration: Decorators configure route-specific settings
  2. Middleware Processing: SecurityMiddleware reads decorator configurations and applies them
  3. Override Behavior: Route-specific settings can override global middleware settings

Example Integration:

from guard_core import SecurityMiddleware, SecurityConfig
from guard_core.decorators import SecurityDecorator

config = SecurityConfig(
    enable_ip_banning=True,
    enable_rate_limiting=True,
    rate_limit_requests=100,
    rate_limit_window=3600
)

# Create decorator instance
guard_deco = SecurityDecorator(config)

# Apply decorators to routes
@guard_deco.rate_limit(requests=10, window=300)  # Override: 10 requests/5min
@app.get("/api/limited")
def limited_endpoint():
    # Uses decorator-specific rate limiting
    return {"data": "limited"}

@app.get("/api/public")
def public_endpoint():
    # Uses global rate limiting (100 requests/hour)
    return {"data": "public"}

# Add global middleware

# Set decorator handler on app state (required for integration)
app.state.guard_decorator = guard_deco

Best Practices

. Decorator Order

Apply decorators in logical order, with more specific restrictions first:

@app.post("/api/admin/sensitive")
@guard_deco.require_https()                        # Security requirement
@guard_deco.require_auth(type="bearer")            # Authentication
@guard_deco.require_ip(whitelist=["10.0.0.0/8"])   # Access control
@guard_deco.rate_limit(requests=5, window=3600)    # Rate limiting
@guard_deco.suspicious_detection(enabled=True)     # Monitoring
def admin_endpoint():
    return {"status": "admin action"}

. Combining Behavioral Analysis

Use multiple behavioral decorators for comprehensive monitoring:

@app.get("/api/rewards")
@guard_deco.usage_monitor(max_calls=50, window=3600, action="ban")
@guard_deco.return_monitor("rare_item", max_occurrences=3, window=86400, action="ban")
@guard_deco.suspicious_frequency(max_frequency=0.1, window=300, action="alert")
def rewards_endpoint():
    return {"reward": "rare_item", "value": 1000}

. Geographic and Cloud Controls

Combine geographic and cloud provider controls:

@app.get("/api/restricted")
@guard_deco.allow_countries(["US", "CA", "GB"])  # Allow specific countries
@guard_deco.block_clouds(["AWS", "GCP"])         # Block cloud providers
def restricted_endpoint():
    return {"data": "geo-restricted"}

. Content Filtering

Apply content filtering for upload endpoints:

@app.post("/api/upload")
@guard_deco.content_type_filter(["image/jpeg", "image/png"])
@guard_deco.max_request_size(5 * 1024 * 1024)  # 5MB limit
@guard_deco.require_referrer(["myapp.com"])
def upload_endpoint():
    return {"status": "uploaded"}

Error Handling

Decorators integrate with the middleware's error handling system. When decorator conditions are not met, appropriate HTTP responses are returned:

. 403 Forbidden

IP restrictions, country blocks, authentication failures

. 429 Too Many Requests

Rate limiting violations

. 400 Bad Request

Content type mismatches, missing headers

. 413 Payload Too Large

Request size limits exceeded

Configuration Priority

Security settings are applied in the following priority order:

  1. Decorator Settings (highest priority)
  2. Global Middleware Settings
  3. Default Settings (lowest priority)

This allows for flexible override behavior where routes can customize their security requirements while maintaining global defaults.