castle 7.3.0

Logging

import logging
from castle.configuration import configuration

configuration.logger = logging.getLogger('castle')

The logger only needs to respond to info. Each request and response is logged with sensitive values stripped.

Multi-environment / multi-tenant

Most apps only need the global configuration singleton, but you can also create standalone Configuration instances and pass them per call via APIRequest:

from castle.configuration import Configuration
from castle.api_request import APIRequest
from castle.commands.risk import CommandsRisk

config = Configuration()
config.api_secret = os.environ['CASTLE_API_SECRET_TENANT_A']

APIRequest(config).call(CommandsRisk(context).call({
    'event': '$login',
    'status': '$succeeded',
    'request_token': '<token>',
    'user': {'id': '1234'},
}))

Header allow/deny lists

By default the SDK sends every HTTP header except Cookie and Authorization. Castle uses these headers to fingerprint the request.

from castle.configuration import configuration, DEFAULT_ALLOWLIST

# Always-blocked headers (in addition to Cookie/Authorization).
configuration.denylisted = ['HTTP-X-Internal-Header']

# Strict allow-list mode. Headers outside the list are scrubbed,
# except User-Agent which is always preserved.
configuration.allowlisted = DEFAULT_ALLOWLIST

Header names are case-insensitive and accept both _ and - as separators. A leading HTTP_ prefix is stripped automatically.

Client IP detection

Castle needs the original client IP, not the IP of your proxy or load balancer. The SDK reads X-Forwarded-For and Remote-Addr by default; pick one of the strategies below:

from castle.configuration import configuration, TRUSTED_PROXIES

# 1. Custom header (e.g. Cloudflare's Cf-Connecting-Ip).
configuration.ip_headers = ['Cf-Connecting-Ip']

# 2. Static, known proxy IPs (strings or regexes).
configuration.trusted_proxies = ['10.0.0.1']

# 3. Ephemeral proxies but known chain depth.
configuration.trusted_proxy_depth = 2

# 4. Last resort: trust the entire X-Forwarded-For chain.
# Warning: vulnerable to header spoofing if a malicious proxy is in path.
configuration.trust_proxy_chain = False

Use either trusted_proxies or trusted_proxy_depth, not both. Private/loopback ranges in TRUSTED_PROXIES are always considered trusted.

Optional settings

from castle.configuration import configuration

# Override the API base URL (default: https://api.castle.io/v1)
# configuration.base_url = 'https://api.castle.io/v1'