pterodactyl_addon/docs/SECURITY.md

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

• All API endpoints require authenticated session (auth:sanctum)
• Every endpoint checks server ownership (owner, admin, or permitted subuser)
• Role assignment prevents privilege escalation: cannot assign role with higher priority than own
• Admin-only endpoints check root_admin = true on the User model
• Effective permission preview is also server-side computed

Input Validation

• All POST/PUT/PATCH requests use Laravel Form Requests with strict validation
• Permission names validated against known Pterodactyl permission key list
• File paths validated: no absolute paths, no ../ traversal sequences
• Color values validated against hex regex
• Priority values bounded (0–9999)

Injection Prevention

• All DB queries use Eloquent/Query Builder — no raw string interpolation
• Console-derived player names sanitized before storage and rendering (strip tags, control chars)
• Command suggestions are server-side generated — user query is never executed
• Storage keys are validated against known prefix before any file operation

XSS Prevention

• All user-controlled output escaped in React components
• dangerouslySetInnerHTML is never used
• Player names from console output are sanitized via regex before cache insert

CSRF Protection

• All mutating endpoints protected by Laravel's SPA CSRF (Sanctum)
• No state-changing GET endpoints

SSRF Prevention

• Wings API URLs constructed only from trusted Node model data (not user input)
• Server UUID validated against UUID format before inclusion in any URL
• No user-supplied URLs are followed

Path Traversal Prevention (File Revisions)

• guardFilePath() rejects absolute paths and ../ sequences before any operation
• Storage keys validated against allowed prefix: addons/revisions/
• No server can access another server's revisions (server_id enforced on all queries)

Sensitive File Handling

• Configurable exclusion patterns applied before any revision is stored
• Default exclusions: .env, *.key, *.pem, *.p12, secrets.yml, *.sql, *.bak, etc.
• Binary files detected and stored without diff rendering (prevents binary exfiltration via diff)

Rate Limiting

• Live network metrics: 12 requests/min per user per server
• Console autocomplete: 60 requests/min per user per server
• Revision restore: 10 requests/min per user
• Role write operations: 30 requests/min per admin

Data Isolation

• Users can only see metrics/revisions/permissions for servers they own or have access to
• Node-wide metrics visible only to root_admin users
• Revision download streams content directly — no temp files with predictable names
• Player cache is per-server — no cross-server data leakage

Infrastructure

• Docker socket is never exposed to the web panel
• Wings stats collected via REST API with token auth, not via Docker socket directly
• No container privileges escalated beyond Wings' standard operation
• Secrets never stored in frontend code or returned in API responses

Audit Logging

• Role create/update/delete logged
• Role assign/unassign logged
• Permission override set logged
• File revision created logged
• File revision restored logged
• 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.