relintio-agent 0.9.6

RelintioAgent in-process agent for Python ASGI runtimes.

relintio-agent (Python)

Note on Features & Quotas: Advanced features (like Bot Challenge and Custom Shield Pages) are tied to your subscription plan. If you exceed your monthly API quota, the agent will operate in a degraded mode (basic protection) before ultimately failing-open to prevent locking you out of your own site. All configuration rules are centrally managed via the dashboard.

Python in-process agent for ASGI runtimes (FastAPI/Starlette/etc).

Install

pip install relintio-agent

FastAPI usage

from fastapi import FastAPI
from relintio_agent.asgi import UltimateProtectorMiddleware

app = FastAPI()

app.add_middleware(
    UltimateProtectorMiddleware,
    license_key="UP_LIVE_...",
    api_url="https://relintio.com/api",
)

Zero-code-ish usage (env wrapper)

If you can change how the app is created (but don't want to paste config into code), wrap the ASGI app using env vars:

import os
from fastapi import FastAPI
from relintio_agent import wrap_asgi_app

app = wrap_asgi_app(FastAPI())

# env:
# UP_LICENSE_KEY=UP_LIVE_...
# UP_API_URL=https://relintio.com/api

Optional: sitecustomize bootstrap

The platform can generate a sitecustomize.py helper inside the Python auto bundle. If that file is on PYTHONPATH, Python auto-imports it on startup. Set UP_ASGI_APP="module:app" and it will best-effort wrap that object automatically (fail-open).

Risk Scoring Engine (v0.9.3)

Every request is evaluated using an additive 0-100 signal-based score. Signals include:

Signal	Weight	Description
Empty User-Agent	+50	No UA header sent
Short User-Agent	+25	UA < 20 characters
No Accept-Language	+20	Missing browser locale header
Generic Accept	+15	Wildcard */* only
Connection: close	+10	Non-persistent connection
POST without Referer	+15	Form submission without origin
Rate burst	+35	Token-bucket exhaustion

Response Tiers

Tier	Score Range	Behavior
ALLOW	0–39	Request proceeds normally
SLOW	40–59	2-second asyncio.sleep to exhaust scanners
CHALLENGE	60–74	Browser verification challenge
DECOY	75–84	Serves fake maintenance page
BLOCK	85–100	Hard block with configured response

Token-Bucket Rate Limiter

Default: 8 tokens/sec, burst capacity of 24. Route-aware multipliers give extra capacity to static assets. Memory-safe with 5-minute eviction via asyncio-compatible dict.

Notes

• PyPI distribution name: relintio-agent
• Import path: relintio_agent (recommended)
• Legacy import path still supported: ultimateprotector_agent

Options

• license_key (required)
• api_url (required) e.g. https://relintio.com/api
• sync_interval_seconds (default: 60)
• allow_sample_rate (default: 0.01)
• only_paths: list[str] exact (/checkout) or prefix (/product/*)
• except_paths: list[str]
• only_regex: str (Python regex)

Geo Enrichment

When CDN geo headers (CF-IPCountry, etc.) are absent, the agent calls the platform's /api/agent/geo-lookup endpoint. The server resolves the country using local MaxMind GeoLite2 databases — zero external API calls, zero cost, microsecond latency. Results are cached in-memory (24h TTL) to minimize round-trips.

Changelog

0.9.3

• Import path alignment - relintio_agent is now the documented import path, with ultimateprotector_agent kept as a compatibility alias.
• Version telemetry alignment - Runtime telemetry now reports 0.9.3, matching the PyPI package version and release tag.

0.5.0

• Additive risk-scoring engine — 0-100 signal-based scoring with 7 weighted signals.
• 5-tier graduated response — ALLOW, SLOW (asyncio.sleep(2.0)), CHALLENGE, DECOY, BLOCK.
• Token-bucket rate limiter — Replaces fixed-window counter. 8 tokens/sec, 24 burst, route-aware multipliers.
• risk_score telemetry — Agent-calculated score forwarded to server in log payload.

0.3.0

• Geo enrichment architecture hardened — The server-side /api/agent/geo-lookup endpoint now performs local MaxMind GeoLite2 lookups instead of proxying to ipinfo.io. Agent behaviour is unchanged; the improvement is server-side.

0.2.0

• HMAC payload verification — Rules payloads are now authenticated with HMAC-SHA256 before decryption. Requires platform ≥ 2026-04.
• X-Agent-Version header — Sent on every /verify request for dashboard version tracking.
• outdated status handling — If the cloud responds with outdated, the agent fails open and stops protecting until updated.

0.1.1

• Initial stable release with AES-256-CBC encrypted rules sync.