Metadata-Version: 2.4
Name: auraprotector-agent
Version: 0.6.0
Summary: AuraProtector in-process agent for Python ASGI runtimes.
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/auraguard-co/AuraProtector
Project-URL: Repository, https://github.com/auraguard-co/AuraProtector
Project-URL: Issues, https://github.com/auraguard-co/AuraProtector/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.26
Requires-Dist: cryptography>=42
Dynamic: license-file

# auraprotector-agent (Python)

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

## Install

```bash
pip install auraprotector-agent
```

## FastAPI usage

```py
from fastapi import FastAPI
from auraprotector_agent.asgi import UltimateProtectorMiddleware

app = FastAPI()

app.add_middleware(
    UltimateProtectorMiddleware,
    license_key="UP_LIVE_...",
    api_url="https://YOUR_CLOUD/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:

```py
import os
from fastapi import FastAPI
from auraprotector_agent import wrap_asgi_app

app = wrap_asgi_app(FastAPI())

# env:
# UP_LICENSE_KEY=UP_LIVE_...
# UP_API_URL=https://YOUR_CLOUD/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.5.0+)

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: `auraprotector-agent`
- Import path: `auraprotector_agent` (recommended)
- Legacy import path still supported: `ultimateprotector_agent`


## Options

- `license_key` (required)
- `api_url` (required) e.g. `https://cloud.example/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.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.
