Metadata-Version: 2.3
Name: araxys
Version: 0.14.0
Summary: Plug & play security for FastAPI — CORS, CSRF, IP blocking, rate limiting, honeypots, JWT, API keys, MFA, OAuth2/OIDC, RBAC, brute force, sessions, OTEL, Prometheus, audit, CSP, sanitization, prompt injection, malware scanning, XXE, account enumeration, OIDC Discovery, AWS WAF, Threat Intelligence, GraphQL Security, Headers Audit, Dynamic Secrets Rotation, DB security (Redis+PG pool, TLS, secrets), SQL parser
Keywords: fastapi,security,rate-limiting,jwt,rs256,es256,jwks,token-binding,middleware,honeypot,csp,csrf,audit-logging,nosql-injection,sanitization,sql-injection,sqlparse,prompt-injection,llm-security,malware,antivirus,file-scanning,connection-pooling,permissions-policy
Author: Samuel Esteban Urrego Valencia
Author-email: Samuel Esteban Urrego Valencia <urregodev@gmail.com>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Typing :: Typed
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: fastapi>=0.115.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pyjwt[crypto]>=2.8
Requires-Dist: bleach>=6.0
Requires-Dist: cryptography>=44.0
Requires-Dist: structlog>=24.0
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.0
Requires-Dist: sqlparse>=0.5.0
Requires-Dist: pillow>=10
Requires-Dist: pypdf>=4
Requires-Dist: python-docx>=1
Requires-Dist: openpyxl>=3
Requires-Dist: httpx>=0.27
Requires-Dist: graphql-core>=3.2.8
Requires-Dist: araxys[redis,opentelemetry,prometheus,webhooks,audit,vault,aws-secrets,webauthn,prompt-guard-image,prompt-guard-pdf,prompt-guard-office,xxe,aws-waf,graphql] ; extra == 'all'
Requires-Dist: aiofiles>=24.0 ; extra == 'audit'
Requires-Dist: boto3>=1.34 ; extra == 'aws-secrets'
Requires-Dist: boto3>=1.34 ; extra == 'aws-waf'
Requires-Dist: pytest>=8.0 ; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'
Requires-Dist: httpx>=0.27 ; extra == 'dev'
Requires-Dist: fakeredis>=2.21 ; extra == 'dev'
Requires-Dist: ruff>=0.11 ; extra == 'dev'
Requires-Dist: mypy>=1.10 ; extra == 'dev'
Requires-Dist: pre-commit>=4.0 ; extra == 'dev'
Requires-Dist: uvicorn>=0.30 ; extra == 'dev'
Requires-Dist: graphql-core>=3.2 ; extra == 'graphql'
Requires-Dist: strawberry-graphql>=0.200 ; extra == 'graphql'
Requires-Dist: opentelemetry-api>=1.20 ; extra == 'opentelemetry'
Requires-Dist: opentelemetry-sdk>=1.20 ; extra == 'opentelemetry'
Requires-Dist: prometheus-client>=0.18 ; extra == 'prometheus'
Requires-Dist: pillow>=10 ; extra == 'prompt-guard-image'
Requires-Dist: python-docx>=1 ; extra == 'prompt-guard-office'
Requires-Dist: openpyxl>=3 ; extra == 'prompt-guard-office'
Requires-Dist: pypdf>=4 ; extra == 'prompt-guard-pdf'
Requires-Dist: redis>=5.0 ; extra == 'redis'
Requires-Dist: hvac>=2.0 ; extra == 'vault'
Requires-Dist: cbor2>=5.0 ; extra == 'webauthn'
Requires-Dist: httpx>=0.27 ; extra == 'webhooks'
Requires-Dist: defusedxml>=0.7.1 ; extra == 'xxe'
Requires-Python: >=3.11
Provides-Extra: all
Provides-Extra: audit
Provides-Extra: aws-secrets
Provides-Extra: aws-waf
Provides-Extra: dev
Provides-Extra: graphql
Provides-Extra: opentelemetry
Provides-Extra: prometheus
Provides-Extra: prompt-guard-image
Provides-Extra: prompt-guard-office
Provides-Extra: prompt-guard-pdf
Provides-Extra: redis
Provides-Extra: vault
Provides-Extra: webauthn
Provides-Extra: webhooks
Provides-Extra: xxe
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/araxyslogo.png" alt="Araxys Logo" width="400">
</p>

<p align="center">
  <strong>Plug & Play Security for FastAPI</strong><br>
  <em>CORS · CSRF · Rate Limiting · JWT · API Keys · MFA · OAuth2 · RBAC · WebAuthn · Sessions · Prompt Injection · Malware Scan · XXE · Account Enumeration Prevention · OIDC Discovery · AWS WAF Bridge · Threat Intelligence Feeds · GraphQL Security · Headers Audit · Dynamic Secrets Rotation · Webhooks + DLQ · Honeypots · Audit · DB Security</em>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.11+-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/badge/FastAPI-0.115+-009688?style=for-the-badge&logo=fastapi&logoColor=white" alt="FastAPI">
  <img src="https://img.shields.io/badge/Pydantic-v2-E92063?style=for-the-badge&logo=pydantic&logoColor=white" alt="Pydantic">
  <img src="https://img.shields.io/badge/uv-package%20manager-DE5FE9?style=for-the-badge&logo=uv&logoColor=white" alt="uv">
  <img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="License">
  <img src="https://img.shields.io/badge/version-0.14.0-blue?style=for-the-badge" alt="Version">
</p>

<p align="center">
  <img src="https://img.shields.io/badge/encryption-AES--256--GCM-DC143C?style=flat-square" alt="AES-256-GCM">
  <img src="https://img.shields.io/badge/JWT-OAuth2%20compliant-000000?style=flat-square&logo=jsonwebtokens&logoColor=white" alt="JWT">
  <img src="https://img.shields.io/badge/Redis-optional-DC382D?style=flat-square&logo=redis&logoColor=white" alt="Redis">
  <img src="https://img.shields.io/badge/OpenTelemetry-optional-8B5CF6?style=flat-square&logo=opentelemetry&logoColor=white" alt="OTEL">
  <img src="https://img.shields.io/badge/Prometheus-optional-E6522C?style=flat-square&logo=prometheus&logoColor=white" alt="Prometheus">
  <img src="https://img.shields.io/badge/structlog-logging-4B8BBE?style=flat-square" alt="structlog">
  <img src="https://img.shields.io/badge/tests-1958%20passed-brightgreen?style=flat-square" alt="Tests">
</p>

---

## ⚡ What is Araxys?

**Araxys** is a comprehensive security library for [FastAPI](https://fastapi.tiangolo.com/) that provides enterprise-grade protection with a plug & play architecture. Add security to your API with **three lines of code** — no rewrites, no boilerplate.

> **v0.14.0** adds AWS WAF Bridge (OpenAPI → WAF rule generation + boto3 apply), Threat Intelligence Feeds (8 sources, IPResolver, background scheduler), GraphQL Security (depth/breadth/cost/introspection validation), Security Headers Audit (9 OWASP checks, CLI audit-headers), and Dynamic Secrets Rotation (background credential rotation, pool hot-swap, admin endpoints, CLI). **v0.13.0** added XXE protection, account enumeration prevention, CSRF auto-middleware, and OIDC Discovery. [1958 tests](https://github.com/Samuel-Urrego/Araxys/actions).

```python
from fastapi import FastAPI
from araxys import AraxysShield, AraxysConfig

app = FastAPI()
shield = AraxysShield(app, AraxysConfig(secret_key="your-32-char-secret-key-here!!!!"))
# That's it. Your API is now protected. 🛡️
```

---

## 🧩 Modules

| Module | Description | Status |
|--------|------------|--------|
| 🚦 **CORS** | Per-origin policy with fail-closed default | ✅ v0.3 |
| 🛑 **IP Access Control** | Allow/block/hybrid modes with CIDR support | ✅ v0.3 |
| 🍪 **CSRF Protection** | Double-submit cookie + automatic ASGI middleware | ✅ v0.3 / 🆕 v0.13 |
| 🔒 **Brute Force** | Account lockout + password policy + HIBP check | ✅ v0.3 |
| 👥 **Session Management** | Max concurrent, idle timeout, TTL expiry, touch_session() | ✅ v0.10 |
| 🗄️ **DB Security** | Redis Sentinel/Cluster pools, PG pool, TLS/cert pinning, secret resolver chain | ✅ v0.10 |
| 🎟️ **JWT Auth** | RS256/ES256 + HS256, JWKS, token rotation, family revocation | ✅ Ready |
| 🔑 **API Keys** | Scoped keys with SHA-256 hashing & expiration | ✅ Ready |
| 🔐 **MFA / TOTP** | Time-based OTP (RFC 6238), recovery codes | ✅ v0.9 |
| 🔓 **OAuth2 / OIDC** | PKCE flow, state store, multi-provider, OIDC Discovery (RFC 8414) | ✅ v0.9 / 🆕 v0.13 |
| 🏷️ **RBAC** | Resource:action permission model | ✅ v0.9 |
| 🔏 **WebAuthn / Passkeys** | FIDO2 registration + authentication, COSE key parsing, attestation | ✅ v0.10 |
| 📨 **Webhooks** | Event bus + retry (1s/2s/4s) + dead-letter queue with admin API | ✅ v0.10 |
| 🚦 **Rate Limiting** | Sliding window, per-user/IP/key, escalating bans with cap | ✅ Ready |
| 🍯 **Honeypots** | Fake endpoints that auto-ban bots | ✅ Ready |
| 🛡️ **Secure Headers** | CSP, COOP/COEP/CORP, HSTS, X-Frame-Options (OWASP) | ✅ Ready |
| 🧹 **Sanitization** | SQLi (sqlparse), NoSQL, command injection, XSS, path traversal, multipart | ✅ Ready |
| 🤖 **Prompt Injection** | Heuristic detection (injection, jailbreak, zero-width, homoglyphs), file metadata + hidden content scanning | ✅ v0.11 |
| 📄 **XXE Protection** | Regex + entity expansion detection, ASGI middleware, per-endpoint `xxe_guard` | 🆕 v0.13 |
| 🛡️ **Account Enumeration** | Unified error messages, timing jitter, fake hash pre-lookup, middleware | 🆕 v0.13 |
| 🌐 **OIDC Discovery** | RFC 8414 async client, in-memory TTL cache, `OAuth2Provider.from_issuer()` | 🆕 v0.13 |
| 🦠 **Malware Scan** | Heuristic file-upload scanning (magic bytes, MIME, archive bombs, macros, polyglots, double ext, path traversal) | ✅ v0.12 |
| 🛡️ **AWS WAF Bridge** | OpenAPI → WAF rule generation, boto3 IP set/Web ACL apply, multi-strike escalation | 🆕 v0.14 |
| 🕵️ **Threat Intelligence** | 8 feed sources (Firehol, Spamhaus, Blocklist.de, AbuseIPDB, AlienVault OTX), IPResolver, background scheduler | 🆕 v0.14 |
| 📊 **GraphQL Security** | Depth/breadth/cost/introspection validation via graphql-core AST, GRAPHQL_BLOCKED events | 🆕 v0.14 |
| 🔍 **Headers Audit** | 9 OWASP security header checks, sampling middleware, CLI `araxys audit-headers` | 🆕 v0.14 |
| 🔄 **Secrets Rotation** | Background credential rotation, pool hot-swap, admin endpoints, CLI `araxys secrets` | 🆕 v0.14 |
| 📋 **Audit Logging** | AES-256-GCM encrypted, async I/O, hash-chain integrity, PII masking | ✅ Ready |
| 📡 **OpenTelemetry** | Graceful span tracing (opt-in, no-op fallback) | ✅ v0.3 |
| 📊 **Prometheus Metrics** | 9 counters + histogram + /metrics endpoint | ✅ v0.3 |
| 💻 **Admin API** | Session/IP ban/API key management, secrets rotation, DLQ inspection + replay | ✅ v0.9 / 🆕 v0.14 |

---

## 📦 Installation

```bash
# Core (in-memory backends)
pip install araxys

# With Redis support (recommended for production)
pip install araxys[redis]

# With OpenTelemetry tracing
pip install araxys[opentelemetry]

# With Prometheus metrics
pip install araxys[prometheus]

# With webhook delivery support
pip install araxys[webhooks]

# With AWS WAF support (boto3)
pip install araxys[aws_waf]

# With GraphQL security support
pip install araxys[graphql]

# With prompt injection file scanning support
pip install araxys[prompt-guard-image,prompt-guard-pdf,prompt-guard-office]

# Everything
pip install araxys[all]

# Development
pip install araxys[dev]
```

> **Requires Python 3.11+**

---

> [!TIP]
> **AI Agent Support:** This repository includes an [AI.md](AI.md) file specifically designed to provide high-density context for AI coding assistants (Cursor, Windsurf, etc.), ensuring they follow project standards and understand the internal architecture.

---

## 🚀 Quick Start

### Full Protection (All Modules)

```python
from fastapi import FastAPI
from araxys import AraxysShield, AraxysConfig

app = FastAPI()

shield = AraxysShield(
    app,
    AraxysConfig(
        secret_key="super-secret-key-at-least-32-chars!",
        redis_url="redis://localhost:6379",  # Optional — omit for in-memory
        cors={"allow_origins": ["https://myapp.com"], "allow_methods": ["GET", "POST"]},
        ip_access={"enabled": True, "mode": "block", "blocklist": ["10.0.0.0/8"]},
        rate_limit={"window_seconds": 60, "max_requests": 100},
        honeypot={"paths": ["/admin/config", "/wp-admin", "/.env"]},
        brute_force={"enabled": True, "max_attempts": 5},
        csrf={"enabled": True},
        secure_headers={"enabled": True},
        sanitize={"enabled": True},
        audit={"encrypt": True, "log_file": "audit.log"},
        telemetry={"enabled": True, "service_name": "my-api"},
        metrics={"enabled": True},
    ),
)
```

### CORS Policy

```python
# Fail-closed by default — explicitly allow origins
config = AraxysConfig(
    secret_key="...",
    cors={"allow_origins": ["https://app.example.com"], "allow_methods": ["GET", "POST", "PUT"]},
)
# CORS middleware is always registered. Empty allow_origins = deny all.
```

### IP Access Control

```python
# Allow mode — only listed IPs get through
config = AraxysConfig(
    secret_key="...",
    ip_access={"enabled": True, "mode": "allow", "allowlist": ["10.0.1.0/24", "192.168.1.100"]},
)
```

### CSRF Protection

```python
# v0.13 — Automatic ASGI middleware (no per-route wiring needed)
config = AraxysConfig(
    secret_key="...",
    csrf={"enabled": True},  # Intercepts PUT/POST/DELETE/PATCH automatically
)

# v0.12 and earlier — Per-route opt-in
from fastapi import Depends
from araxys import csrf_protected, CSRFConfig

@app.post("/submit", dependencies=[Depends(csrf_protected(CSRFConfig()))])
async def submit_form():
    return {"status": "ok"}
```

### Brute Force + Password Policy

```python
from fastapi import Depends
from araxys import password_policy_dependency, PasswordPolicyConfig

@app.post("/auth/register")
async def register(
    password: str = Depends(password_policy_dependency(PasswordPolicyConfig())),
):
    # Password already validated — min 8 chars, upper, lower, digit, special
    return {"status": "registered"}
```

### API Key Authentication

```python
from fastapi import Depends
from araxys import Scope
from araxys.api_keys.dependencies import require_api_key
from araxys.api_keys.models import APIKeyRecord

# Create a key
key = await shield.api_key_manager.create_key(
    owner="service-a",
    scopes=[Scope.READ, Scope.WRITE],
    ttl_days=90,
)
print(f"Save this key: {key.raw_key}")  # Shown only once!

### 💻 Command Line Interface (CLI)

Araxys includes a professional CLI for managing API keys and security assets directly from your terminal.

**Setup:**

```bash
# Install (CLI included in core)
pip install araxys

# Configure your storage
export ARAXYS_REDIS_URL="redis://localhost:6379"
```

**Usage:**

```bash
# Create a new key
araxys keys create --owner "service-a" --scopes "read,write" --ttl 90

# List active keys in a beautiful table
araxys keys list

# Revoke a key by its prefix
araxys keys revoke [prefix]
```

# Protect an endpoint
@app.get("/data")
async def get_data(
    key: APIKeyRecord = Depends(
        require_api_key(Scope.READ, manager=shield.api_key_manager)
    ),
):
    return {"data": "protected", "owner": key.owner}
```

### JWT with Token Rotation

```python
from fastapi import Depends
from araxys import Scope
from araxys.jwt_auth.dependencies import require_jwt
from araxys.jwt_auth.tokens import TokenPayload

# Login — issue tokens
@app.post("/auth/login")
async def login(username: str, password: str):
    # ... validate credentials ...
    pair = await shield.jwt_manager.create_token_pair(
        subject=user.id,
        scopes=[Scope.READ, Scope.WRITE],
    )
    return pair.model_dump()

# Refresh — rotate tokens (old refresh token is blacklisted)
@app.post("/auth/refresh")
async def refresh(refresh_token: str):
    new_pair = await shield.jwt_manager.rotate_tokens(refresh_token)
    return new_pair.model_dump()

# Protected endpoint
@app.get("/profile")
async def profile(
    user: TokenPayload = Depends(
        require_jwt(Scope.READ, jwt_manager=shield.jwt_manager)
    ),
):
    return {"user_id": user.sub, "scopes": user.scopes}
```

---

## 🏗️ Architecture

```
src/araxys/
├── core/               # Config, exceptions, shared types
│   ├── config.py       # Pydantic Settings (env var support)
│   ├── exceptions.py   # Custom exception hierarchy
│   └── types.py        # Scope, AuditEntry, SecurityEvent, SecurityEventType
├── cors/               # 🚦 CORS policy manager
│   └── middleware.py   # Per-origin, fail-closed, preflight
├── ip_access/          # 🛑 IP access control
│   ├── backends.py     # Protocol + InMemory + Redis
│   └── middleware.py   # Allow/block/hybrid modes, CIDR
├── csrf/               # 🍪 CSRF protection
│   ├── tokens.py       # Double-submit cookie, constant-time
│   ├── dependencies.py # Per-route FastAPI dependency
│   └── middleware.py   # 🆕 v0.13 — Automatic ASGI middleware
├── brute_force/        # 🔒 Brute force + password policy
│   ├── backends.py     # InMemory + Redis attempt tracking
│   ├── limiter.py      # Lockout middleware
│   └── password_policy.py  # Complexity rules + HIBP
├── sessions/           # 👥 Session management
│   ├── storage.py      # Protocol + InMemory + Redis
│   └── manager.py      # Max concurrent, idle timeout, touch, revocation, cleanup
├── telemetry/          # 📡 OpenTelemetry integration
│   ├── tracer.py       # Graceful no-op fallback, span CM
│   └── middleware.py   # Auto-spanning HTTP middleware
├── webhooks/           # 📨 Security event webhooks
│   ├── emitter.py      # SecurityEventBus (async pub/sub)
│   ├── delivery.py     # httpx POST + retry (1s/2s/4s) + SSRF guard
│   ├── dlq.py          # Dead-letter queue backend + consumer
│   └── dlq_routes.py   # DLQ admin API (list/inspect/replay/purge)
├── webauthn/           # 🔏 WebAuthn / Passkeys (v0.10)
│   ├── manager.py      # Registration + authentication ceremonies
│   ├── cose.py         # COSE key parsing (EC2, RSA)
│   ├── attestation.py  # Attestation verification (none, packed)
│   ├── storage.py      # CredentialStore protocol + Redis/InMemory
│   ├── challenges.py   # ChallengeStore with TTL
│   ├── dependencies.py # FastAPI Depends injection
│   ├── models.py       # RelyingPartyConfig, CredentialRecord
│   └── exceptions.py   # WebAuthnError, COSEAlgorithmError
├── mfa/                # 🔐 MFA / TOTP (v0.9)
│   ├── manager.py      # TOTP gen + verify (RFC 6238)
│   ├── models.py       # MFA config
│   └── dependencies.py # FastAPI Depends
├── rbac/               # 🏷️ RBAC (v0.9)
│   ├── models.py       # Permission, Role models
│   └── manager.py      # Role assignment + permission check
├── oauth/              # 🔓 OAuth2 / OIDC (v0.9)
│   ├── flow.py         # PKCE authorization + token exchange
│   ├── router.py       # Login + callback routes
│   └── providers/      # Google, GitHub, etc.
├── admin/              # 💻 Admin API (v0.9)
│   └── router.py       # Sessions, IP bans, API keys, DLQ management
├── metrics/            # 📊 Prometheus metrics
│   ├── collector.py    # 9 counters + histogram registry
│   └── endpoint.py     # /metrics scrape endpoint
├── rate_limit/         # 🚦 Dynamic rate limiting
│   ├── backends.py     # Protocol + InMemory + Redis
│   ├── limiter.py      # Sliding window + escalation
│   └── middleware.py   # ASGI middleware
├── xxe/                # 📄 XXE Protection (v0.13)
│   ├── config.py       # Detection toggles, exclusions
│   ├── scanner.py      # Regex + entity expansion detection
│   ├── middleware.py   # ASGI middleware
│   ├── dependencies.py # Per-endpoint xxe_guard
│   ├── events.py       # Audit + security event definitions
│   └── exceptions.py   # XXEError
├── account_protection/ # 🛡️ Account Enumeration (v0.13)
│   ├── config.py       # Protection config
│   ├── middleware.py   # Response normalization + timing jitter
│   ├── detection.py    # Enumeration detection logic
│   └── helpers.py      # Constant-time compare, normalize
├── oidc/               # 🌐 OIDC Discovery (v0.13)
│   ├── models.py       # OIDCProviderMetadata (Pydantic)
│   ├── client.py       # Async discovery client + TTL cache
│   └── __init__.py     # Public exports
├── honeypot/           # 🍯 Trap endpoints
│   ├── trap.py         # Route registration + auto-ban
│   └── middleware.py   # IP ban enforcement
├── api_keys/           # 🔑 API Key management
│   ├── models.py       # Pydantic models
│   ├── manager.py      # CRUD + verification
│   ├── storage.py      # Protocol + InMemory + Redis
│   └── dependencies.py # FastAPI dependencies
├── cli.py              # 💻 Command Line Interface (Typer + Rich)
├── jwt_auth/           # 🎟️ JWT tokens
│   ├── tokens.py       # Create, decode, rotate
│   ├── storage.py      # JTI blacklisting
│   └── dependencies.py # FastAPI dependencies
├── headers/            # 🛡️ Security headers
│   └── middleware.py   # HSTS, CSP, COOP, CORP
├── sanitize/           # 🧹 Input sanitization
│   ├── patterns.py     # SQLi + XSS regex patterns
│   ├── filters.py      # Detection + stripping
│   └── middleware.py   # ASGI middleware
├── audit/              # 📋 Audit logging
│   ├── encryption.py   # AES-256-GCM + PBKDF2
│   ├── logger.py       # Structured logger
│   └── events.py       # Event types
├── db_security/        # 🗄️ Database security (v0.5)
│   ├── pool.py         # Connection pooling + health
│   ├── secrets.py      # Env→Vault→AWS resolver chain
│   ├── tls.py          # TLS config + cert pinning
│   ├── audit.py        # Query auditor + slow detection
│   ├── manager.py      # Lifecycle orchestrator
│   └── dependencies.py # FastAPI DI
└── shield.py           # ⚡ Main orchestrator + shutdown()
```

### Middleware Chain (outer → inner)

```
CORS → SecureHeaders → Telemetry → CSRF → RateLimit → BruteForce → Honeypot → AccountProtection → IP Access → Sanitize → XXE → Auth (JWT / APIKey / WebAuthn)
```

---

## 🔐 Security Features in Detail

### CORS Policy Manager (v0.3)

- **Per-origin allowlist** with exact match and wildcard `*` support
- **Fail-closed default**: empty allowlist denies all cross-origin requests
- **Preflight handling**: automatic OPTIONS 200 with correct headers
- Full header injection: `Access-Control-Allow-Origin`, `Allow-Methods`, `Allow-Headers`, `Allow-Credentials`, `Expose-Headers`, `Max-Age`

### IP Access Control (v0.3)

- Three modes: **allow** (default-deny), **block** (default-allow), **hybrid**
- **CIDR support** for IPv4 and IPv6
- **X-Forwarded-For** fallback for proxied requests
- Pluggable backends (InMemory + Redis)

### CSRF Protection (v0.3 / 🆕 v0.13)

- **Double-submit cookie** pattern
- **Constant-time comparison** via `secrets.compare_digest`
- **Per-route opt-in** as a FastAPI dependency — original approach
- **🆕 v0.13 — Automatic ASGI middleware** (`CSRFMiddleware`) — intercepts PUT/POST/DELETE/PATCH automatically, no per-route `Depends` wiring
- Configurable token expiry, cookie security, path exclusions, and safe methods

### Brute Force Protection (v0.3)

- **Account lockout** after N failed attempts (423 Locked response)
- **Auto-reset** on successful login
- **Password policy** with 6 configurable rules (length, upper, lower, digit, special)
- **HIBP integration** via k-anonymity model (opt-in)

### Session Management (v0.3)

- **Max concurrent sessions** per user with auto-revoke of oldest
- **Session listing** and per-session revocation
- Background cleanup loop for expired sessions
- `SecurityEvent` emission on create/revoke

### OpenTelemetry (v0.3)

- **Opt-in** — zero overhead when disabled or OTEL SDK absent
- Graceful **no-op fallback** when `opentelemetry` package not installed
- `araxys_span()` async context manager for custom spans
- Auto-spanning HTTP middleware

### Security Event Webhooks (v0.3)

- **Unified event bus** with 12 event types
- **Per-event-type webhook URLs** with retry (exponential backoff: 1s/2s/4s)
- **Fire-and-forget** delivery — never blocks the request
- Internally consumed by Prometheus metrics

### Prometheus Metrics (v0.3)

- **9 counters**: rate_limit_exceeded, honeypot_triggered, sanitize_blocked, jwt_rotated, csrf_failed, brute_force_lockout, ip_blocked, session_revoked, security_events
- **1 histogram**: middleware_duration_seconds
- Standard `/metrics` endpoint (configurable path)
- Opt-in, no-op when `prometheus-client` not installed

### Rate Limiting

- **Sliding window** counter per IP + endpoint
- **Escalating bans**: repeated violations increase ban duration exponentially
- **X-RateLimit headers**: `Limit`, `Remaining`, `Window` injected in every response
- **Path exclusion**: Skip `/docs`, `/healthz`, etc.

### Honeypot Endpoints

- Registers **fake routes** like `/admin/config`, `/wp-admin`, `/.env`
- Returns **200 OK** with fake content (doesn't alert the bot)
- **Auto-bans the IP** across ALL endpoints
- Integrates with audit logging

### API Key Management

- **256-bit entropy** keys via `secrets.token_urlsafe`
- Stored as **SHA-256 hashes** (raw key is never persisted)
- **Scope-based authorization**: `read`, `write`, `admin`
- **Expiration support** with configurable TTL
- **Pluggable storage**: implement the `APIKeyStorage` protocol with your database

### JWT with Token Rotation

- **Access + Refresh** token pairs following OAuth2 best practices
- **JTI-based revocation**: each refresh token has a unique ID
- **Replay attack detection**: reusing a rotated refresh token triggers an alert
- **Configurable TTLs**: access (default 30min), refresh (default 7 days)
- **Scope embedding** in token claims

### Secure Headers

| Header | Default Value |
|--------|--------------|
| `Strict-Transport-Security` | `max-age=31536000; includeSubDomains` |
| `X-Content-Type-Options` | `nosniff` |
| `X-Frame-Options` | `DENY` |
| `X-XSS-Protection` | `0` (disabled — modern best practice) |
| `Referrer-Policy` | `strict-origin-when-cross-origin` |
| `Cross-Origin-Opener-Policy` | `same-origin` (v0.3) |
| `Cross-Origin-Resource-Policy` | `same-origin` (v0.3) |
| `Content-Security-Policy` | Configurable (CSP builder in v0.3) |
| `Permissions-Policy` | Configurable |
| `Server` | Hidden by default (v0.3) |

### XXE Protection (v0.13)

- **Regex-based pre-scanning**: DTD, ENTITY, SYSTEM, `<!DOCTYPE>` detection
- **Entity expansion detection**: Billion-laughs / quadratic blowup via `XXEScanner`
- **ASGI middleware**: `XXEMiddleware` — intercepts XML content types at the middleware level
- **Per-endpoint guard**: `xxe_guard` Depends for targeted protection
- **Zero external dependencies**: stdlib-only, no `defusedxml` required
- **Security events**: `XXE_DETECTED` security event + audit trail

### Account Enumeration Prevention (v0.13)

- **Unified error messages**: Auth endpoints return identical responses regardless of user/key existence
- **Timing jitter**: Randomized response delays to mask timing-based enumeration
- **Fake hash pre-lookup**: Constant-time fake hash verification for non-existent API keys
- **ASGI middleware**: `AccountProtectionMiddleware` normalizes 401/403 responses
- **Enumeration detection**: Identifies scanning patterns and emits audit events

### OIDC Discovery (v0.13)

- **RFC 8414 client**: Async `OIDCDiscoveryClient` fetches `/.well-known/openid-configuration`
- **Pydantic metadata model**: `OIDCProviderMetadata` with required fields (issuer, authorization_endpoint, token_endpoint, jwks_uri)
- **In-memory TTL cache**: Keyed by issuer URL, configurable cache duration
- **OAuth2Provider integration**: `OAuth2Provider.from_issuer()` classmethod for auto-discovery
- **Graceful error handling**: Timeout, invalid JSON, missing fields → `OIDCDiscoveryError`

### AWS WAF Bridge (v0.14)

- **OpenAPI → WAF rules**: `SchemaReader` + `WafRuleGenerator` produce IP sets, regex pattern sets, rule groups, Web ACL JSON
- **boto3 apply**: `WafClient` with lazy boto3, semaphore-guarded, supports create/update IP sets, rule groups, Web ACLs
- **Multi-strike escalation**: `WafEscalationSubscriber` with configurable threshold, dry-run, TTL eviction, auto-adds blocked IPs to AWS
- **CLI**: `araxys waf generate`, `araxys waf apply`

### Threat Intelligence Feeds (v0.14)

- **8 feed sources**: Firehol (levels 1–3), Spamhaus DROP/EDROP, Blocklist.de, AbuseIPDB, AlienVault OTX
- **IPResolver**: Cross-feed dedup, CIDR exclusion, in-memory TTL tracking with eviction, bulk sync to backend
- **Background scheduler**: Staggered feed loops, per-feed asyncio.Tasks, refresh/stats/purge API
- **Security events**: `THREAT_INTEL_LOADED`, `THREAT_INTEL_MATCH` emitted on IP match
- **CLI**: `araxys threat-intel refresh|stats|purge|feeds`

### GraphQL Security (v0.14)

- **4 validators**: Depth limit, breadth limit, cost limit, introspection disable
- **graphql-core AST**: Parses and validates queries via `graphql-core` before processing
- **ASGI middleware**: Intercepts `POST /graphql`, returns GraphQL-formatted errors on violations
- **Security events**: `GRAPHQL_BLOCKED` emitted on query violation
- **Optional dependency**: `araxys[graphql]`

### Security Headers Audit (v0.14)

- **9 OWASP checks**: HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, COOP, COEP, X-XSS-Protection
- **Sampling middleware**: `AuditHeadersMiddleware` with configurable sample rate
- **CLI**: `araxys audit-headers check <url>` with Rich table or JSON output

### Dynamic Secrets Rotation (v0.14)

- **Background credential rotation**: `SecretsRotationScheduler` re-resolves secrets via `ChainedResolver` on configurable interval
- **Pool hot-swap**: `reload_url()`/`reload_dsn()` on RedisPool, SentinelPool, ClusterPool, InMemoryPool, and PGPool — PING validates new URL before atomic swap
- **Security events**: `SECRET_ROTATING`, `SECRET_ROTATED`, `SECRET_ROTATION_FAILED`
- **Admin API**: `POST /admin/secrets/rotate`, `GET /admin/secrets/status`
- **CLI**: `araxys secrets rotate [--target NAME]`, `araxys secrets status`

### Payload Sanitization

- **16 SQL injection patterns**: UNION, DROP, blind injection, time-based, etc.
- **9 XSS patterns**: script tags, JS URIs, event handlers, iframes
- **Recursive scanning** with configurable depth limit
- SQLi → **block** (400 response) · XSS → **strip** (bleach)

### Encrypted Audit Logging

- **AES-256-GCM** authenticated encryption (confidentiality + integrity)
- **PBKDF2-HMAC-SHA256** key derivation (480,000 iterations — OWASP 2023)
- **Per-entry unique salt + nonce** (no two entries share the same key material)
- **Tamper detection**: GCM authentication tag catches any modification
- Structured output via **structlog**

---

## ⚙️ Configuration

All settings support **environment variables** with the `ARAXYS_` prefix:

```bash
export ARAXYS_SECRET_KEY="your-production-secret-key-here!"
export ARAXYS_REDIS_URL="redis://localhost:6379"
export ARAXYS_CORS__ALLOW_ORIGINS='["https://myapp.com"]'
export ARAXYS_IP_ACCESS__ENABLED="true"
export ARAXYS_METRICS__ENABLED="true"
```

Or configure programmatically:

```python
from araxys import AraxysConfig, RateLimitConfig, HoneypotConfig, CORSConfig

config = AraxysConfig(
    secret_key="...",
    cors=CORSConfig(allow_origins=["https://app.example.com"]),
    ip_access={"enabled": True, "mode": "hybrid"},
    rate_limit=RateLimitConfig(
        max_requests=200,
        window_seconds=120,
        ban_threshold=10,
        ban_duration_seconds=600,
        escalation_multiplier=3.0,
    ),
    honeypot=HoneypotConfig(
        paths=["/admin", "/wp-login.php", "/.git/config"],
        ban_duration_seconds=7200,
    ),
    brute_force={"enabled": True, "max_attempts": 5},
    csrf={"enabled": True},
    telemetry={"enabled": True, "service_name": "my-api"},
    metrics={"enabled": True},
    jwt={"access_token_ttl_minutes": 15, "refresh_token_ttl_days": 30},
    audit={"encrypt": True, "log_file": "/var/log/araxys/audit.log"},
)
```

---

## 🧪 Testing

```bash
# Run all tests
uv run pytest tests/ -v

# With coverage
uv run pytest tests/ --cov=araxys --cov-report=term-missing
```

**1958 tests** covering all 33 modules — CORS, IP access, CSRF, brute force, sessions, telemetry, webhooks, DLQ, WebAuthn, MFA, OAuth2/OIDC, RBAC, admin, metrics, rate limiting, honeypots, API keys, JWT, headers, sanitization, prompt injection, malware scanning, XXE protection, account enumeration prevention, OIDC Discovery, AWS WAF Bridge, threat intelligence feeds, GraphQL security, headers audit, secrets rotation, audit logging, and database security.

---

## 🏭 Production Recommendations

| Aspect | Recommendation |
|--------|---------------|
| **Backends** | Use Redis (`araxys[redis]`) for multi-worker deployments |
| **Secret Key** | Generate with `openssl rand -hex 32` — never hardcode |
| **API Key Storage** | Implement `APIKeyStorage` protocol with your database |
| **Audit Logs** | Enable encryption + write to a dedicated log file |
| **Rate Limits** | Tune `max_requests` and `ban_threshold` per endpoint |
| **CORS** | Explicitly list allowed origins — never use `*` in production |
| **Observability** | Enable OTEL + Prometheus for production monitoring |
| **HTTPS** | Always deploy behind TLS — HSTS and secure cookies expect it |

---

## 📁 Tech Stack

<p align="center">
  <img src="https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/badge/FastAPI-009688?style=for-the-badge&logo=fastapi&logoColor=white" alt="FastAPI">
  <img src="https://img.shields.io/badge/Pydantic-E92063?style=for-the-badge&logo=pydantic&logoColor=white" alt="Pydantic">
  <img src="https://img.shields.io/badge/JWT-000000?style=for-the-badge&logo=jsonwebtokens&logoColor=white" alt="JWT">
  <img src="https://img.shields.io/badge/Redis-DC382D?style=for-the-badge&logo=redis&logoColor=white" alt="Redis">
  <img src="https://img.shields.io/badge/OpenTelemetry-8B5CF6?style=for-the-badge&logo=opentelemetry&logoColor=white" alt="OTEL">
  <img src="https://img.shields.io/badge/Prometheus-E6522C?style=for-the-badge&logo=prometheus&logoColor=white" alt="Prometheus">
  <img src="https://img.shields.io/badge/structlog-4B8BBE?style=for-the-badge&logo=python&logoColor=white" alt="structlog">
  <img src="https://img.shields.io/badge/cryptography-AES256-DC143C?style=for-the-badge" alt="cryptography">
  <img src="https://img.shields.io/badge/pytest-0A9EDC?style=for-the-badge&logo=pytest&logoColor=white" alt="pytest">
  <img src="https://img.shields.io/badge/Ruff-D7FF64?style=for-the-badge&logo=ruff&logoColor=black" alt="Ruff">
  <img src="https://img.shields.io/badge/mypy-strict-blue?style=for-the-badge" alt="mypy">
  <img src="https://img.shields.io/badge/uv-DE5FE9?style=for-the-badge&logo=uv&logoColor=white" alt="uv">
</p>

---

## 📄 License

MIT License — see [LICENSE](LICENSE) for details.

---

<p align="center">
  <strong>Built with 🛡️ by <a href="https://github.com/andresramirez">Samuel Esteban Urrego Valencia</a></strong><br>
  <em>"Security shouldn't be an afterthought — it should be a single import."</em>
</p>
