File transfer

docs/SECURITY.md

@@ -0,0 +1,97 @@
+# Security Notes
+
+> **Ball Studios** — https://git.balls.studio/BallStudios/pterodactyl_addon
+
+## Security Architecture
+
+All security controls are **server-side only**. The frontend never makes authorization decisions.
+
+---
+
+## Security Checklist
+
+### Authentication & Authorization
+- [x] All API endpoints require authenticated session (`auth:sanctum`)
+- [x] Every endpoint checks server ownership (owner, admin, or permitted subuser)
+- [x] Role assignment prevents privilege escalation: cannot assign role with higher priority than own
+- [x] Admin-only endpoints check `root_admin = true` on the User model
+- [x] Effective permission preview is also server-side computed
+
+### Input Validation
+- [x] All POST/PUT/PATCH requests use Laravel Form Requests with strict validation
+- [x] Permission names validated against known Pterodactyl permission key list
+- [x] File paths validated: no absolute paths, no `../` traversal sequences
+- [x] Color values validated against hex regex
+- [x] Priority values bounded (0–9999)
+
+### Injection Prevention
+- [x] All DB queries use Eloquent/Query Builder — no raw string interpolation
+- [x] Console-derived player names sanitized before storage and rendering (strip tags, control chars)
+- [x] Command suggestions are server-side generated — user query is never executed
+- [x] Storage keys are validated against known prefix before any file operation
+
+### XSS Prevention
+- [x] All user-controlled output escaped in React components
+- [x] `dangerouslySetInnerHTML` is never used
+- [x] Player names from console output are sanitized via regex before cache insert
+
+### CSRF Protection
+- [x] All mutating endpoints protected by Laravel's SPA CSRF (Sanctum)
+- [x] No state-changing GET endpoints
+
+### SSRF Prevention
+- [x] Wings API URLs constructed **only** from trusted Node model data (not user input)
+- [x] Server UUID validated against UUID format before inclusion in any URL
+- [x] No user-supplied URLs are followed
+
+### Path Traversal Prevention (File Revisions)
+- [x] `guardFilePath()` rejects absolute paths and `../` sequences before any operation
+- [x] Storage keys validated against allowed prefix: `addons/revisions/`
+- [x] No server can access another server's revisions (server_id enforced on all queries)
+
+### Sensitive File Handling
+- [x] Configurable exclusion patterns applied before any revision is stored
+- [x] Default exclusions: `.env`, `*.key`, `*.pem`, `*.p12`, `secrets.yml`, `*.sql`, `*.bak`, etc.
+- [x] Binary files detected and stored without diff rendering (prevents binary exfiltration via diff)
+
+### Rate Limiting
+- [x] Live network metrics: 12 requests/min per user per server
+- [x] Console autocomplete: 60 requests/min per user per server
+- [x] Revision restore: 10 requests/min per user
+- [x] Role write operations: 30 requests/min per admin
+
+### Data Isolation
+- [x] Users can only see metrics/revisions/permissions for servers they own or have access to
+- [x] Node-wide metrics visible only to `root_admin` users
+- [x] Revision download streams content directly — no temp files with predictable names
+- [x] Player cache is per-server — no cross-server data leakage
+
+### Infrastructure
+- [x] Docker socket is never exposed to the web panel
+- [x] Wings stats collected via REST API with token auth, not via Docker socket directly
+- [x] No container privileges escalated beyond Wings' standard operation
+- [x] Secrets never stored in frontend code or returned in API responses
+
+### Audit Logging
+- [x] Role create/update/delete logged
+- [x] Role assign/unassign logged
+- [x] Permission override set logged
+- [x] File revision created logged
+- [x] File revision restored logged
+- [x] All logs include actor_id, IP address, timestamp, and payload
+
+---
+
+## Known Limitations
+
+1. **Port-level network metrics** require iptables on the host node. If not available, the port table shows a friendly "unavailable" message rather than failing silently.
+2. **Container flow graph** currently derives inter-container traffic from shared Docker networks — it cannot identify application-layer routing (e.g., Velocity routing logic) purely from network layer data.
+3. **File revision listener** depends on Pterodactyl's `ConsoleDataReceived` event. If a future panel version removes this event, the listener degrades gracefully (no crash).
+
+---
+
+## Reporting Security Issues
+
+Email: **security@balls.studio** (or open a private issue at https://git.balls.studio/BallStudios/pterodactyl_addon)
+
+Please do **not** publicly disclose security vulnerabilities before they are patched.