roboco/docs/optional/http-security.md

HTTP security hardening (fastapi-guard)

RoboCo can front its API with a fastapi-guard security layer — IP and rate controls, a signature WAF, security headers, cloud-provider and honeypot checks, an emergency kill switch, and three RoboCo-specific content validators — for when you expose the panel/API beyond a trusted LAN.

The layer is off by default. When ROBOCO_GUARD_ENABLED is unset, create_app never mounts the middleware and the request path is byte-for-byte unchanged; the per-route guard decorators are harmless no-ops (roboco/security.py). A personal NAS deploy needs none of this — it's built for cloud/public hosting.

What it does

Armed, the middleware sits outermost and applies, per route:

• Rate limiting & size caps — a baseline throttle plus tighter per-endpoint limits on sensitive routes (provider-key writes, CEO release ops, agent verbs).
• A signature WAF — SQLi/XSS/path-traversal/etc. detection on request bodies, headers, params, and path.
• Security headers — HSTS, CSP, X-Frame-Options, nosniff, referrer and permissions policies on every response.
• Cloud-provider & honeypot checks — block datacenter egress on the highest-value routes; form-trap honeypots on human-facing POSTs.
• Three RoboCo custom validators the stock WAF cannot cover — prompt-injection, secret-exfil, and internal-SSRF scanning on the prompt-facing and agent-content surfaces.
• An emergency lockdown (ROBOCO_GUARD_EMERGENCY) — a flip-on-without-redeploy switch that blocks every non-whitelisted IP during an active attack.

Behind nginx, guard trusts the single proxy hop for the real client IP, excludes WebSocket upgrades and health/docs paths, and keeps RoboCo's own CORS.

Passive first, then enforce

Guard has two enforcement postures, and the intended rollout is passive → active:

ROBOCO_GUARD_PASSIVE_MODE	Behaviour
true (calibrate)	Log-only. Detections are logged but never block — legit and malicious requests pass through. Safe to arm on live traffic to surface false positives first.
false (enforce)	Detections block the request.

!!! warning "Calibrate before you enforce" RoboCo's request bodies are code, SQL, diffs, file paths, HTML, and URLs — task specs, agent notes and commits, RAG queries, git bodies, chat. A stock WAF reads that legitimate traffic as attacks. RoboCo ships a calibration (excluded_detection_body_fields in build_security_config, derived from the real request models) that excludes those free-text fields from WAF scanning so active mode does not false-positive — while the WAF stays active on every structured (id/enum/slug/branch) field and the prompt-injection / secret-exfil / SSRF validators keep firing regardless. Even so, arm passive first on your own deployment, watch the logs for any straggler false positive, then flip to active.

The NAS composes arm the guard in passive/log-only mode by default (ROBOCO_GUARD_PASSIVE_MODE=true, ROBOCO_GUARD_FAIL_SECURE=false) so a deploy calibrates against real traffic before you enforce.

Scanner honeytrap & auto-ban

Automated scanners probe every host for well-known soft spots (/.env, /wp-login.php, /phpmyadmin, /.git/config, …). RoboCo turns those probes against the scanner, in two layers matched to where the traffic actually lands — behind nginx only /api, /ws, /health, and /ready reach the orchestrator, so guard can only see probes on those paths:

• Guard adaptive ban (the /api surface). The guard threat_ban_config carries recon / sensitive_file / cms_probing categories. A scanner probing those fingerprints on an /api path is detected on the URL-path scan, and repeated probes from one IP trip a per-IP auto-ban (redis-backed, 24h). This only bans in active mode (passive logs the recon hit) and requires redis (the 24h ban exceeds the in-memory cap).
• nginx edge-drop (the classic root paths). The classic scanner paths never reach the orchestrator, so nginx drops them at the edge with 444 (closes the connection, returns nothing) before they touch the panel. It's anchored to known scanner fingerprints — /.well-known and every real panel/API route are untouched — and is always on, independent of ROBOCO_GUARD_ENABLED.

Fail-secure

ROBOCO_GUARD_FAIL_SECURE decides what happens if a security check itself errors: true (default) fails closed — block the request — which is the right default for public hosting. The personal NAS compose overrides it to false so a guard-internal bug can never 500 your own deploy.

Enable it

=== "Environment"

```bash
ROBOCO_GUARD_ENABLED=true
ROBOCO_GUARD_PASSIVE_MODE=true      # calibrate first; flip to false to enforce
ROBOCO_GUARD_FAIL_SECURE=true       # false on a personal/NAS deploy
ROBOCO_ENVIRONMENT=production        # drives enforce_https (relaxed in development)
# ROBOCO_GUARD_EMERGENCY=true                 # attack lockdown kill switch
# ROBOCO_GUARD_EMERGENCY_WHITELIST=1.2.3.4    # extra allowed IPs during lockdown
# ROBOCO_GUARD_TELEMETRY_ENABLED=true         # + guard_agent_api_key + guard_project_id
```

=== "Panel"

**Settings → Feature Flags** exposes the master switch. The passive/fail-secure/environment knobs are environment settings, not flags — set them in env.

!!! note "Takes effect on the next backend restart"
    The flag persists in the settings store and applies on the **next backend restart**.

See the environment reference for the full flag list.

Telemetry (optional, off)

ROBOCO_GUARD_TELEMETRY_ENABLED reports security events/metrics to a guard-core platform via guard-agent. It is off by default and no data leaves the box while off; flip it on and set ROBOCO_GUARD_AGENT_API_KEY + ROBOCO_GUARD_PROJECT_ID to enable.

Next

→ Environment reference for every flag · Deployment for where to set them · back to Optional subsystems.