BallStudios/pterodactyl_addon
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

File transfer

Browse Source
This commit is contained in:
BaileyCodes
2026-06-11 20:33:44 -05:00
parent 2cb1d58264
commit b362357bcb
58 changed files with 5096 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
docs/CONFIG.md Normal file
View File

@@ -0,0 +1,60 @@
# Configuration Reference
> **Ball Studios** — https://git.balls.studio/BallStudios/pterodactyl_addon
All settings are in `config/advanced-admin.php`. Many can be overridden via `.env`.
## Network Traffic Dashboard
| Key | Default | `.env` Override | Description |
|---|---|---|---|
| `network.enabled` | `true` | `ADDON_NETWORK_ENABLED` | Enable/disable module |
| `network.collection_interval_seconds` | `10` | `ADDON_NETWORK_INTERVAL` | Seconds between metrics collection |
| `network.iptables_enabled` | `false` | `ADDON_NETWORK_IPTABLES` | Enable port-level iptables collection |
| `network.retention.raw` | `1` | `ADDON_NETWORK_RETENTION_RAW` | Raw data retention (days) |
| `network.retention.5m` | `7` | `ADDON_NETWORK_RETENTION_5M` | 5-min downsampled retention (days) |
| `network.retention.1h` | `30` | `ADDON_NETWORK_RETENTION_1H` | Hourly downsampled retention (days) |
| `network.retention.1d` | `365` | `ADDON_NETWORK_RETENTION_1D` | Daily downsampled retention (days) |
| `network.rate_limit_per_minute` | `12` | `ADDON_NETWORK_RATE_LIMIT` | Live endpoint rate limit |
## Role-Based Permissions
| Key | Default | Description |
|---|---|---|
| `roles.enabled` | `true` | Enable/disable module |
| `roles.max_roles_per_server` | `0` | 0 = unlimited |
| `roles.warn_on_delete_in_use` | `true` | Warn before deleting assigned role |
| `roles.dangerous_permissions` | See config | Permissions that trigger UI warning |
| `roles.write_rate_limit` | `30` | Admin write operations per minute |
## File Revision History
| Key | Default | `.env` Override | Description |
|---|---|---|---|
| `revisions.enabled` | `true` | `ADDON_REVISIONS_ENABLED` | Enable/disable module |
| `revisions.storage_path` | `addons/revisions` | `ADDON_REVISIONS_PATH` | Storage path under `storage/app/` |
| `revisions.max_file_size` | `10485760` (10 MB) | `ADDON_REVISIONS_MAX_FILE_SIZE` | Max file size to track (bytes) |
| `revisions.max_revisions_per_file` | `50` | `ADDON_REVISIONS_MAX_PER_FILE` | Max revisions per file |
| `revisions.max_storage_per_server` | `524288000` (500 MB) | `ADDON_REVISIONS_MAX_STORAGE` | Max storage per server |
| `revisions.retention_days` | `90` | `ADDON_REVISIONS_RETENTION_DAYS` | Delete revisions older than N days |
| `revisions.excluded_patterns` | See config | — | File glob patterns to never track |
### Default Excluded Patterns
```
.env, *.env, *.key, *.pem, *.p12, *.pfx, *.crt, *.cer, *.jks
secrets.yml, secrets.yaml, *secret*, *password*, *token*
*.sql, *.sql.gz, *.bak, *.backup, *.dump
*.zip, *.tar, *.tar.gz, *.tar.bz2, *.7z, *.rar
```
## Console Autocomplete
| Key | Default | `.env` Override | Description |
|---|---|---|---|
| `console.enabled` | `true` | `ADDON_CONSOLE_ENABLED` | Enable/disable module |
| `console.autocomplete_rate_limit` | `60` | `ADDON_CONSOLE_RATE_LIMIT` | Requests per minute per user |
| `console.player_cache_ttl_minutes` | `30` | `ADDON_CONSOLE_PLAYER_TTL` | Player cache expiry (minutes) |
| `console.max_suggestions` | `10` | `ADDON_CONSOLE_MAX_SUGGESTIONS` | Max suggestions returned |
| `console.patterns.join.*` | See config | — | Regex patterns for player join |
| `console.patterns.leave.*` | See config | — | Regex patterns for player leave |

107
docs/INSTALL.md Normal file
View File

@@ -0,0 +1,107 @@
# Installation Guide
> **Ball Studios** — https://git.balls.studio/BallStudios/pterodactyl_addon
## One-Line Install (Recommended)
Run as **root** on your Pterodactyl server:
```bash
bash <(curl -fsSL https://git.balls.studio/BallStudios/pterodactyl_addon/raw/branch/main/install.sh)
```
Custom panel path:
```bash
bash <(curl -fsSL https://git.balls.studio/BallStudios/pterodactyl_addon/raw/branch/main/install.sh) /path/to/pterodactyl
```
The script will:
1. Run preflight checks (PHP version, panel path, git)
2. Back up all files it will modify to `.addon_backup_<timestamp>/`
3. Clone the addon repository
4. Copy backend + frontend files
5. Apply 4 minimal patches to panel core files
6. Run database migrations
7. Seed default roles (Owner, Admin, Moderator, Viewer)
8. Run `yarn build:production`
9. Clear Laravel caches
---
## Manual Install
### Prerequisites
| Requirement | Version |
|---|---|
| Pterodactyl Panel | v1.12.x |
| PHP | 8.1+ |
| Node.js | 22.x |
| Yarn | 1.x |
| MySQL/MariaDB | 8.0+ / 10.4+ |
### Steps
```bash
# 1. Clone the addon (outside panel dir)
git clone https://git.balls.studio/BallStudios/pterodactyl_addon /tmp/ptero-addon
cd /tmp/ptero-addon
# 2. Copy files
cp -r app/Addons /var/www/pterodactyl/app/
cp config/advanced-admin.php /var/www/pterodactyl/config/
cp -r config/addon-commands /var/www/pterodactyl/config/
cp -r database/migrations/addon /var/www/pterodactyl/database/migrations/
cp routes/addon-client.php /var/www/pterodactyl/routes/
cp routes/addon-application.php /var/www/pterodactyl/routes/
cp -r resources/scripts/addons /var/www/pterodactyl/resources/scripts/
cp -r database/seeders/. /var/www/pterodactyl/database/seeders/
# 3. Register the service provider
# In /var/www/pterodactyl/app/Providers/AppServiceProvider.php
# Add inside the register() method:
# $this->app->register(\Pterodactyl\Addons\AdvancedAdmin\AddonServiceProvider::class);
# 4. Migrate
cd /var/www/pterodactyl
php artisan migrate --path=database/migrations/addon --force
# 5. Seed default roles
php artisan db:seed --class="Pterodactyl\\Addons\\AdvancedAdmin\\Database\\Seeders\\DefaultRolesSeeder" --force
# 6. Build frontend
export NODE_OPTIONS=--openssl-legacy-provider
yarn install --frozen-lockfile && yarn build:production
# 7. Clear caches
php artisan optimize:clear && php artisan optimize
# 8. Fix permissions
chown -R www-data:www-data storage bootstrap/cache app/Addons resources/scripts/addons
```
### Core Patches Applied
All patches are documented in `patches/PATCHES.md`. Each patch is **≤ 3 lines**:
| File | Change |
|---|---|
| `app/Providers/AppServiceProvider.php` | Register `AddonServiceProvider` |
| `resources/scripts/routers/ServerRouter.tsx` | Add Network tab route |
| `resources/scripts/components/server/files/FileEditContainer.tsx` | Import `FileHistoryButton` |
| `resources/scripts/components/server/console/ServerConsole.tsx` | Import `CommandInput` wrapper |
---
## Post-Install
1. Review `config/advanced-admin.php` — adjust retention, rate limits, and exclusions
2. Add `.env` overrides if needed (see [CONFIG.md](CONFIG.md))
3. Restart queue worker: `php artisan queue:restart`
4. Navigate to your panel — the **Network**, **History**, and **Autocomplete** features are now active
---
## Troubleshooting
See [TROUBLESHOOTING.md](TROUBLESHOOTING.md).

97
docs/SECURITY.md Normal file
View File

@@ -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.