docs: add architecture and security documentation
Adds comprehensive documentation for the core-developer package: - architecture.md: directory structure, boot lifecycle, component patterns - security.md: threat model, authorization layers, data protection Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Snider
parent
387436c34b
commit
256e7eb47d
2 changed files with 659 additions and 0 deletions
390
docs/architecture.md
Normal file
390
docs/architecture.md
Normal file
|
|
@ -0,0 +1,390 @@
|
||||||
|
---
|
||||||
|
title: Architecture
|
||||||
|
description: Technical architecture of the core-developer package
|
||||||
|
updated: 2026-01-29
|
||||||
|
---
|
||||||
|
|
||||||
|
# Architecture
|
||||||
|
|
||||||
|
The `core-developer` package provides administrative developer tools for the Host UK platform. It is designed exclusively for "Hades" tier users (god-mode access) and includes debugging, monitoring, and server management capabilities.
|
||||||
|
|
||||||
|
## Package Overview
|
||||||
|
|
||||||
|
| Aspect | Detail |
|
||||||
|
|--------|--------|
|
||||||
|
| Namespace | `Core\Developer\` |
|
||||||
|
| Type | L1 Module (Laravel Package) |
|
||||||
|
| Dependencies | `host-uk/core`, `host-uk/core-admin` |
|
||||||
|
| PHP Version | 8.2+ |
|
||||||
|
| Laravel Version | 11.x / 12.x |
|
||||||
|
| Livewire Version | 3.x / 4.x |
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── Boot.php # Service provider & event handlers
|
||||||
|
├── Controllers/
|
||||||
|
│ └── DevController.php # REST API endpoints
|
||||||
|
├── Concerns/
|
||||||
|
│ └── RemoteServerManager.php # SSH connection trait
|
||||||
|
├── Console/Commands/
|
||||||
|
│ └── CopyDeviceFrames.php # Asset management command
|
||||||
|
├── Data/
|
||||||
|
│ └── RouteTestResult.php # DTO for route test results
|
||||||
|
├── Exceptions/
|
||||||
|
│ └── SshConnectionException.php
|
||||||
|
├── Lang/
|
||||||
|
│ └── en_GB/developer.php # Translations
|
||||||
|
├── Listeners/
|
||||||
|
│ └── SetHadesCookie.php # Login event listener
|
||||||
|
├── Middleware/
|
||||||
|
│ ├── ApplyIconSettings.php # Icon preferences from cookies
|
||||||
|
│ └── RequireHades.php # Authorization middleware
|
||||||
|
├── Migrations/
|
||||||
|
│ └── 0001_01_01_000001_create_developer_tables.php
|
||||||
|
├── Models/
|
||||||
|
│ └── Server.php # SSH server model
|
||||||
|
├── Providers/
|
||||||
|
│ ├── HorizonServiceProvider.php
|
||||||
|
│ └── TelescopeServiceProvider.php
|
||||||
|
├── Routes/
|
||||||
|
│ └── admin.php # Route definitions
|
||||||
|
├── Services/
|
||||||
|
│ ├── LogReaderService.php # Log file parsing
|
||||||
|
│ └── RouteTestService.php # Route testing logic
|
||||||
|
├── Tests/
|
||||||
|
│ └── UseCase/
|
||||||
|
│ └── DevToolsBasic.php # Feature tests
|
||||||
|
└── View/
|
||||||
|
├── Blade/
|
||||||
|
│ └── admin/ # Blade templates
|
||||||
|
│ ├── activity-log.blade.php
|
||||||
|
│ ├── cache.blade.php
|
||||||
|
│ ├── database.blade.php
|
||||||
|
│ ├── logs.blade.php
|
||||||
|
│ ├── route-inspector.blade.php
|
||||||
|
│ ├── routes.blade.php
|
||||||
|
│ └── servers.blade.php
|
||||||
|
└── Modal/
|
||||||
|
└── Admin/ # Livewire components
|
||||||
|
├── ActivityLog.php
|
||||||
|
├── Cache.php
|
||||||
|
├── Database.php
|
||||||
|
├── Logs.php
|
||||||
|
├── RouteInspector.php
|
||||||
|
├── Routes.php
|
||||||
|
└── Servers.php
|
||||||
|
```
|
||||||
|
|
||||||
|
## Event-Driven Module Loading
|
||||||
|
|
||||||
|
The module uses the Core Framework's event-driven lazy loading pattern. The `Boot` class declares which events it listens to:
|
||||||
|
|
||||||
|
```php
|
||||||
|
public static array $listens = [
|
||||||
|
AdminPanelBooting::class => 'onAdminPanel',
|
||||||
|
ConsoleBooting::class => 'onConsole',
|
||||||
|
];
|
||||||
|
```
|
||||||
|
|
||||||
|
This ensures routes, views, and commands are only registered when the admin panel or console is actually used.
|
||||||
|
|
||||||
|
### Lifecycle Events
|
||||||
|
|
||||||
|
| Event | Handler | What Happens |
|
||||||
|
|-------|---------|--------------|
|
||||||
|
| `AdminPanelBooting` | `onAdminPanel()` | Registers views, routes, Pulse override |
|
||||||
|
| `ConsoleBooting` | `onConsole()` | Registers Artisan commands |
|
||||||
|
|
||||||
|
## Core Components
|
||||||
|
|
||||||
|
### 1. Livewire Admin Pages
|
||||||
|
|
||||||
|
All admin pages are full-page Livewire components using attribute-based configuration:
|
||||||
|
|
||||||
|
```php
|
||||||
|
#[Title('Application Logs')]
|
||||||
|
#[Layout('hub::admin.layouts.app')]
|
||||||
|
class Logs extends Component
|
||||||
|
```
|
||||||
|
|
||||||
|
Each component:
|
||||||
|
- Checks Hades access in `mount()`
|
||||||
|
- Uses `developer::admin.{name}` view namespace
|
||||||
|
- Has corresponding Blade template in `View/Blade/admin/`
|
||||||
|
|
||||||
|
### 2. API Controller
|
||||||
|
|
||||||
|
`DevController` provides REST endpoints for:
|
||||||
|
- `/hub/api/dev/logs` - Recent log entries
|
||||||
|
- `/hub/api/dev/routes` - Route listing
|
||||||
|
- `/hub/api/dev/session` - Session/request info
|
||||||
|
- `/hub/api/dev/clear/{type}` - Cache clearing
|
||||||
|
|
||||||
|
All endpoints are protected by `RequireHades` middleware and rate limiting.
|
||||||
|
|
||||||
|
### 3. Services
|
||||||
|
|
||||||
|
**LogReaderService**
|
||||||
|
- Memory-efficient log reading (reads from end of file)
|
||||||
|
- Parses Laravel log format
|
||||||
|
- Automatic sensitive data redaction
|
||||||
|
- Multi-log file support (daily/single channels)
|
||||||
|
|
||||||
|
**RouteTestService**
|
||||||
|
- Route discovery and formatting
|
||||||
|
- Request building with parameters
|
||||||
|
- In-process request execution
|
||||||
|
- Response formatting and metrics
|
||||||
|
|
||||||
|
### 4. RemoteServerManager Trait
|
||||||
|
|
||||||
|
Provides SSH connection management for classes that need remote server access:
|
||||||
|
|
||||||
|
```php
|
||||||
|
class DeployApplication implements ShouldQueue
|
||||||
|
{
|
||||||
|
use RemoteServerManager;
|
||||||
|
|
||||||
|
public function handle(): void
|
||||||
|
{
|
||||||
|
$this->withConnection($this->server, function () {
|
||||||
|
$this->run('cd /var/www && git pull');
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Key methods:
|
||||||
|
- `connect()` / `disconnect()` - Connection lifecycle
|
||||||
|
- `withConnection()` - Guaranteed cleanup pattern
|
||||||
|
- `run()` / `runMany()` - Command execution
|
||||||
|
- `fileExists()` / `readFile()` / `writeFile()` - File operations
|
||||||
|
- `getDiskUsage()` / `getMemoryUsage()` - Server stats
|
||||||
|
|
||||||
|
## Data Flow
|
||||||
|
|
||||||
|
### Admin Page Request
|
||||||
|
|
||||||
|
```
|
||||||
|
Browser Request
|
||||||
|
↓
|
||||||
|
Laravel Router → /hub/dev/logs
|
||||||
|
↓
|
||||||
|
Livewire Component (Logs.php)
|
||||||
|
↓
|
||||||
|
mount() → checkHadesAccess()
|
||||||
|
↓
|
||||||
|
loadLogs() → LogReaderService
|
||||||
|
↓
|
||||||
|
render() → developer::admin.logs
|
||||||
|
↓
|
||||||
|
Response (HTML)
|
||||||
|
```
|
||||||
|
|
||||||
|
### API Request
|
||||||
|
|
||||||
|
```
|
||||||
|
Browser/JS Request
|
||||||
|
↓
|
||||||
|
Laravel Router → /hub/api/dev/logs
|
||||||
|
↓
|
||||||
|
RequireHades Middleware
|
||||||
|
↓
|
||||||
|
Rate Limiter (throttle:dev-logs)
|
||||||
|
↓
|
||||||
|
DevController::logs()
|
||||||
|
↓
|
||||||
|
LogReaderService
|
||||||
|
↓
|
||||||
|
Response (JSON)
|
||||||
|
```
|
||||||
|
|
||||||
|
### SSH Connection
|
||||||
|
|
||||||
|
```
|
||||||
|
Servers Component
|
||||||
|
↓
|
||||||
|
testConnection($serverId)
|
||||||
|
↓
|
||||||
|
Server::findOrFail()
|
||||||
|
↓
|
||||||
|
Write temp key file
|
||||||
|
↓
|
||||||
|
Process::run(['ssh', ...])
|
||||||
|
↓
|
||||||
|
Parse result
|
||||||
|
↓
|
||||||
|
Update server status
|
||||||
|
↓
|
||||||
|
Clean up temp file
|
||||||
|
```
|
||||||
|
|
||||||
|
## Database Schema
|
||||||
|
|
||||||
|
### servers table
|
||||||
|
|
||||||
|
| Column | Type | Description |
|
||||||
|
|--------|------|-------------|
|
||||||
|
| id | bigint | Primary key |
|
||||||
|
| workspace_id | bigint | FK to workspaces |
|
||||||
|
| name | varchar(128) | Display name |
|
||||||
|
| ip | varchar(45) | IPv4/IPv6 address |
|
||||||
|
| port | smallint | SSH port (default 22) |
|
||||||
|
| user | varchar(64) | SSH username |
|
||||||
|
| private_key | text | Encrypted SSH key |
|
||||||
|
| status | varchar(32) | pending/connected/failed |
|
||||||
|
| last_connected_at | timestamp | Last successful connection |
|
||||||
|
| timestamps | | created_at, updated_at |
|
||||||
|
| soft_deletes | | deleted_at |
|
||||||
|
|
||||||
|
Indexes:
|
||||||
|
- `workspace_id`
|
||||||
|
- `(workspace_id, status)` composite
|
||||||
|
|
||||||
|
## Admin Menu Structure
|
||||||
|
|
||||||
|
The module registers a "Dev Tools" menu group with these items:
|
||||||
|
|
||||||
|
```
|
||||||
|
Dev Tools (admin group, priority 80)
|
||||||
|
├── Logs → /hub/dev/logs
|
||||||
|
├── Activity → /hub/dev/activity
|
||||||
|
├── Servers → /hub/dev/servers
|
||||||
|
├── Database → /hub/dev/database
|
||||||
|
├── Routes → /hub/dev/routes
|
||||||
|
├── Route Inspector → /hub/dev/route-inspector
|
||||||
|
└── Cache → /hub/dev/cache
|
||||||
|
```
|
||||||
|
|
||||||
|
The menu is only visible to users with `admin` flag (Hades tier).
|
||||||
|
|
||||||
|
## Rate Limiting
|
||||||
|
|
||||||
|
API endpoints have rate limits configured in `Boot::configureRateLimiting()`:
|
||||||
|
|
||||||
|
| Limiter | Limit | Purpose |
|
||||||
|
|---------|-------|---------|
|
||||||
|
| `dev-cache-clear` | 10/min | Prevent rapid cache clears |
|
||||||
|
| `dev-logs` | 30/min | Log reading |
|
||||||
|
| `dev-routes` | 30/min | Route listing |
|
||||||
|
| `dev-session` | 60/min | Session info |
|
||||||
|
|
||||||
|
Rate limits are per-user (or per-IP for unauthenticated requests).
|
||||||
|
|
||||||
|
## Third-Party Integrations
|
||||||
|
|
||||||
|
### Laravel Telescope
|
||||||
|
|
||||||
|
Custom `TelescopeServiceProvider` configures:
|
||||||
|
- Gate for Hades-only access in production
|
||||||
|
- Entry filtering (errors, failed jobs in production)
|
||||||
|
- Sensitive header/parameter hiding
|
||||||
|
|
||||||
|
### Laravel Horizon
|
||||||
|
|
||||||
|
Custom `HorizonServiceProvider` configures:
|
||||||
|
- Gate for Hades-only access
|
||||||
|
- Notification routing from config (email, SMS, Slack)
|
||||||
|
|
||||||
|
### Laravel Pulse
|
||||||
|
|
||||||
|
Custom Pulse dashboard view override at `View/Blade/vendor/pulse/dashboard.blade.php`.
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
The module expects these config keys (should be in `config/developer.php`):
|
||||||
|
|
||||||
|
```php
|
||||||
|
return [
|
||||||
|
// Hades cookie token
|
||||||
|
'hades_token' => env('HADES_TOKEN'),
|
||||||
|
|
||||||
|
// SSH settings
|
||||||
|
'ssh' => [
|
||||||
|
'connection_timeout' => 30,
|
||||||
|
'command_timeout' => 60,
|
||||||
|
],
|
||||||
|
|
||||||
|
// Horizon notifications
|
||||||
|
'horizon' => [
|
||||||
|
'mail_to' => env('HORIZON_MAIL_TO'),
|
||||||
|
'sms_to' => env('HORIZON_SMS_TO'),
|
||||||
|
'slack_webhook' => env('HORIZON_SLACK_WEBHOOK'),
|
||||||
|
'slack_channel' => env('HORIZON_SLACK_CHANNEL', '#alerts'),
|
||||||
|
],
|
||||||
|
];
|
||||||
|
```
|
||||||
|
|
||||||
|
## Extension Points
|
||||||
|
|
||||||
|
### Adding New Admin Pages
|
||||||
|
|
||||||
|
1. Create Livewire component in `View/Modal/Admin/`
|
||||||
|
2. Create Blade view in `View/Blade/admin/`
|
||||||
|
3. Add route in `Routes/admin.php`
|
||||||
|
4. Add menu item in `Boot::adminMenuItems()`
|
||||||
|
5. Add translations in `Lang/en_GB/developer.php`
|
||||||
|
|
||||||
|
### Adding New API Endpoints
|
||||||
|
|
||||||
|
1. Add method to `DevController`
|
||||||
|
2. Add route in `Routes/admin.php` API group
|
||||||
|
3. Create rate limiter in `Boot::configureRateLimiting()`
|
||||||
|
4. Apply `throttle:limiter-name` middleware
|
||||||
|
|
||||||
|
### Using RemoteServerManager
|
||||||
|
|
||||||
|
```php
|
||||||
|
use Core\Developer\Concerns\RemoteServerManager;
|
||||||
|
|
||||||
|
class MyJob
|
||||||
|
{
|
||||||
|
use RemoteServerManager;
|
||||||
|
|
||||||
|
public function handle(Server $server): void
|
||||||
|
{
|
||||||
|
$this->withConnection($server, function () {
|
||||||
|
// Commands executed on remote server
|
||||||
|
$result = $this->run('whoami');
|
||||||
|
// ...
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Performance Considerations
|
||||||
|
|
||||||
|
1. **Log Reading** - Uses backwards reading to avoid loading entire log into memory. Configurable `maxBytes` limit.
|
||||||
|
|
||||||
|
2. **Route Caching** - Routes are computed once per request. The `RouteInspector` uses `#[Computed(cache: true)]` for route list.
|
||||||
|
|
||||||
|
3. **Query Log** - Enabled only in local environment (`Boot::boot()`).
|
||||||
|
|
||||||
|
4. **SSH Connections** - Always disconnect via `withConnection()` pattern to prevent resource leaks.
|
||||||
|
|
||||||
|
## Dependencies
|
||||||
|
|
||||||
|
### Composer Requirements
|
||||||
|
|
||||||
|
- `host-uk/core` - Core framework
|
||||||
|
- `host-uk/core-admin` - Admin panel infrastructure
|
||||||
|
- `phpseclib3` - SSH connections (via RemoteServerManager)
|
||||||
|
- `spatie/laravel-activitylog` - Activity logging
|
||||||
|
|
||||||
|
### Frontend Dependencies
|
||||||
|
|
||||||
|
- Flux UI components
|
||||||
|
- Tailwind CSS
|
||||||
|
- Livewire 3.x
|
||||||
|
|
||||||
|
## Testing Strategy
|
||||||
|
|
||||||
|
Tests use Pest syntax and focus on:
|
||||||
|
- Page rendering and content
|
||||||
|
- Authorization enforcement
|
||||||
|
- API endpoint behaviour
|
||||||
|
- Service logic
|
||||||
|
|
||||||
|
Test database: SQLite in-memory with Telescope/Pulse disabled.
|
||||||
269
docs/security.md
Normal file
269
docs/security.md
Normal file
|
|
@ -0,0 +1,269 @@
|
||||||
|
---
|
||||||
|
title: Security
|
||||||
|
description: Security considerations and audit notes for core-developer
|
||||||
|
updated: 2026-01-29
|
||||||
|
---
|
||||||
|
|
||||||
|
# Security Considerations
|
||||||
|
|
||||||
|
The `core-developer` package provides powerful administrative capabilities that require careful security controls. This document outlines the security model, known risks, and mitigation strategies.
|
||||||
|
|
||||||
|
## Threat Model
|
||||||
|
|
||||||
|
### Assets Protected
|
||||||
|
|
||||||
|
1. **Application logs** - May contain tokens, passwords, PII in error messages
|
||||||
|
2. **Database access** - Read-only query execution against production data
|
||||||
|
3. **SSH keys** - Encrypted private keys for server connections
|
||||||
|
4. **Cache data** - Application cache, session data, config cache
|
||||||
|
5. **Route information** - Full application route structure
|
||||||
|
|
||||||
|
### Threat Actors
|
||||||
|
|
||||||
|
1. **Unauthorized users** - Non-Hades users attempting to access dev tools
|
||||||
|
2. **Compromised Hades account** - Attacker with valid Hades credentials
|
||||||
|
3. **SSRF/Injection** - Attacker manipulating dev tools to access internal resources
|
||||||
|
4. **Data exfiltration** - Extracting sensitive data via dev tools
|
||||||
|
|
||||||
|
## Authorization Model
|
||||||
|
|
||||||
|
### Hades Tier Requirement
|
||||||
|
|
||||||
|
All developer tools require "Hades" access, verified via the `isHades()` method on the User model. This is enforced at multiple layers:
|
||||||
|
|
||||||
|
| Layer | Implementation | File |
|
||||||
|
|-------|----------------|------|
|
||||||
|
| Middleware | `RequireHades::handle()` | `src/Middleware/RequireHades.php` |
|
||||||
|
| Component | `checkHadesAccess()` in `mount()` | All Livewire components |
|
||||||
|
| API | Controller `authorize()` calls | `src/Controllers/DevController.php` |
|
||||||
|
| Menu | `admin` flag filtering | `src/Boot.php` |
|
||||||
|
|
||||||
|
### Defence in Depth
|
||||||
|
|
||||||
|
The authorization is intentionally redundant:
|
||||||
|
- API routes use `RequireHades` middleware
|
||||||
|
- Livewire components check in `mount()`
|
||||||
|
- Some controller methods call `$this->authorize()`
|
||||||
|
|
||||||
|
This ensures access is blocked even if one layer fails.
|
||||||
|
|
||||||
|
### Known Issue: Test Environment
|
||||||
|
|
||||||
|
Tests currently pass without setting Hades tier on the test user. This suggests authorization may not be properly enforced in the test environment. See TODO.md for remediation.
|
||||||
|
|
||||||
|
## Data Protection
|
||||||
|
|
||||||
|
### Log Redaction
|
||||||
|
|
||||||
|
The `LogReaderService` automatically redacts sensitive patterns before displaying logs:
|
||||||
|
|
||||||
|
| Pattern | Replacement |
|
||||||
|
|---------|-------------|
|
||||||
|
| Stripe API keys | `[STRIPE_KEY_REDACTED]` |
|
||||||
|
| GitHub tokens | `[GITHUB_TOKEN_REDACTED]` |
|
||||||
|
| Bearer tokens | `Bearer [TOKEN_REDACTED]` |
|
||||||
|
| API keys/secrets | `[KEY_REDACTED]` / `[REDACTED]` |
|
||||||
|
| AWS credentials | `[AWS_KEY_REDACTED]` / `[AWS_SECRET_REDACTED]` |
|
||||||
|
| Database URLs | Connection strings with `[USER]:[PASS]` |
|
||||||
|
| Email addresses | Partial: `jo***@example.com` |
|
||||||
|
| IP addresses | Partial: `192.168.xxx.xxx` |
|
||||||
|
| Credit card numbers | `[CARD_REDACTED]` |
|
||||||
|
| JWT tokens | `[JWT_REDACTED]` |
|
||||||
|
| Private keys | `[PRIVATE_KEY_REDACTED]` |
|
||||||
|
|
||||||
|
**Limitation**: Patterns are regex-based and may not catch all sensitive data. Custom application secrets with non-standard formats will not be redacted.
|
||||||
|
|
||||||
|
### SSH Key Storage
|
||||||
|
|
||||||
|
Server private keys are:
|
||||||
|
- Encrypted at rest using Laravel's `encrypted` cast
|
||||||
|
- Hidden from serialization (`$hidden` array)
|
||||||
|
- Never exposed in API responses or views
|
||||||
|
- Stored in `text` column (supports long keys)
|
||||||
|
|
||||||
|
### Database Query Tool
|
||||||
|
|
||||||
|
The database query component restricts access to read-only operations:
|
||||||
|
|
||||||
|
```php
|
||||||
|
protected const ALLOWED_STATEMENTS = ['SELECT', 'SHOW', 'DESCRIBE', 'EXPLAIN'];
|
||||||
|
```
|
||||||
|
|
||||||
|
**Known Risk**: The current implementation only checks the first word, which does not prevent:
|
||||||
|
- Stacked queries: `SELECT 1; DROP TABLE users`
|
||||||
|
- Subqueries with side effects (MySQL stored procedures)
|
||||||
|
|
||||||
|
**Mitigation**: Use a proper SQL parser or prevent semicolons entirely.
|
||||||
|
|
||||||
|
### Session Data Exposure
|
||||||
|
|
||||||
|
The `/hub/api/dev/session` endpoint exposes:
|
||||||
|
- Session ID
|
||||||
|
- User IP address
|
||||||
|
- User agent (truncated to 100 chars)
|
||||||
|
- Request method and URL
|
||||||
|
|
||||||
|
This is intentional for debugging but could be abused for session hijacking if credentials are compromised.
|
||||||
|
|
||||||
|
## Rate Limiting
|
||||||
|
|
||||||
|
All API endpoints have rate limits to prevent abuse:
|
||||||
|
|
||||||
|
| Endpoint | Limit | Rationale |
|
||||||
|
|----------|-------|-----------|
|
||||||
|
| Cache clear | 10/min | Prevent DoS via rapid cache invalidation |
|
||||||
|
| Log reading | 30/min | Limit log scraping |
|
||||||
|
| Route listing | 30/min | Prevent enumeration attacks |
|
||||||
|
| Session info | 60/min | Higher limit for debugging workflows |
|
||||||
|
|
||||||
|
Rate limits are per-user (authenticated) or per-IP (unauthenticated).
|
||||||
|
|
||||||
|
## SSH Connection Security
|
||||||
|
|
||||||
|
### Key Handling
|
||||||
|
|
||||||
|
The `testConnection()` method in `Servers.php` creates a temporary key file:
|
||||||
|
|
||||||
|
```php
|
||||||
|
$tempKeyPath = sys_get_temp_dir().'/ssh_test_'.uniqid();
|
||||||
|
file_put_contents($tempKeyPath, $server->getDecryptedPrivateKey());
|
||||||
|
chmod($tempKeyPath, 0600);
|
||||||
|
```
|
||||||
|
|
||||||
|
**Risk**: Predictable filename pattern and race condition window between write and use.
|
||||||
|
|
||||||
|
**Recommendation**: Use `tempnam()` for unique filename, write with restrictive umask.
|
||||||
|
|
||||||
|
### Connection Validation
|
||||||
|
|
||||||
|
- `StrictHostKeyChecking=no` is used for convenience but prevents MITM detection
|
||||||
|
- `BatchMode=yes` prevents interactive prompts
|
||||||
|
- `ConnectTimeout=10` limits hanging connections
|
||||||
|
|
||||||
|
### Workspace Isolation
|
||||||
|
|
||||||
|
The `RemoteServerManager::connect()` method validates workspace ownership before connecting:
|
||||||
|
|
||||||
|
```php
|
||||||
|
if (! $server->belongsToCurrentWorkspace()) {
|
||||||
|
throw new SshConnectionException('Unauthorised access to server.', $server->name);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This prevents cross-tenant server access.
|
||||||
|
|
||||||
|
## Route Testing Security
|
||||||
|
|
||||||
|
### Environment Restriction
|
||||||
|
|
||||||
|
Route testing is only available in `local` and `testing` environments:
|
||||||
|
|
||||||
|
```php
|
||||||
|
public function isTestingAllowed(): bool
|
||||||
|
{
|
||||||
|
return App::environment(['local', 'testing']);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
This prevents accidental data modification in production.
|
||||||
|
|
||||||
|
### Destructive Operation Warnings
|
||||||
|
|
||||||
|
Routes using `DELETE`, `PUT`, `PATCH`, `POST` methods are marked as destructive and show warnings in the UI.
|
||||||
|
|
||||||
|
### CSRF Consideration
|
||||||
|
|
||||||
|
Test requests bypass CSRF as they are internal requests. The `X-Requested-With: XMLHttpRequest` header is set by default.
|
||||||
|
|
||||||
|
## Cookie Security
|
||||||
|
|
||||||
|
### Hades Cookie
|
||||||
|
|
||||||
|
The `SetHadesCookie` listener sets a cookie on login:
|
||||||
|
|
||||||
|
| Attribute | Value | Purpose |
|
||||||
|
|-----------|-------|---------|
|
||||||
|
| Value | Encrypted token | Validates Hades status |
|
||||||
|
| Duration | 1 year | Long-lived for convenience |
|
||||||
|
| HttpOnly | true | Prevents XSS access |
|
||||||
|
| Secure | true (production) | HTTPS only in production |
|
||||||
|
| SameSite | lax | CSRF protection |
|
||||||
|
|
||||||
|
### Icon Settings Cookie
|
||||||
|
|
||||||
|
`ApplyIconSettings` middleware reads `icon-style` and `icon-size` cookies set by JavaScript. These are stored in session for Blade component access.
|
||||||
|
|
||||||
|
**Risk**: Cookie values are user-controlled. Ensure they are properly escaped in views.
|
||||||
|
|
||||||
|
## Audit Logging
|
||||||
|
|
||||||
|
### Logged Actions
|
||||||
|
|
||||||
|
| Action | What's Logged |
|
||||||
|
|--------|---------------|
|
||||||
|
| Log clear | user_id, email, previous_size_bytes, IP |
|
||||||
|
| Database query | user_id, email, query, row_count, execution_time, IP |
|
||||||
|
| Blocked query | user_id, email, query (attempted), IP |
|
||||||
|
| Route test | user_id, route, method, IP |
|
||||||
|
| Server failure | Server ID, failure reason (via activity log) |
|
||||||
|
|
||||||
|
### Activity Log
|
||||||
|
|
||||||
|
Server model uses Spatie ActivityLog for tracking changes:
|
||||||
|
- Logged fields: name, ip, port, user, status
|
||||||
|
- Only dirty attributes logged
|
||||||
|
- Empty logs suppressed
|
||||||
|
|
||||||
|
## Third-Party Security
|
||||||
|
|
||||||
|
### Telescope
|
||||||
|
|
||||||
|
- Sensitive headers hidden: `cookie`, `x-csrf-token`, `x-xsrf-token`
|
||||||
|
- Sensitive parameters hidden: `_token`
|
||||||
|
- Gate restricts to Hades users (production) or all users (local)
|
||||||
|
|
||||||
|
### Horizon
|
||||||
|
|
||||||
|
- Gate restricts to Hades users
|
||||||
|
- Notifications configured via config (not hardcoded emails)
|
||||||
|
|
||||||
|
## Security Checklist for New Features
|
||||||
|
|
||||||
|
When adding new developer tools:
|
||||||
|
|
||||||
|
- [ ] Enforce Hades authorization in middleware AND component
|
||||||
|
- [ ] Add rate limiting for API endpoints
|
||||||
|
- [ ] Redact sensitive data in output
|
||||||
|
- [ ] Audit destructive operations
|
||||||
|
- [ ] Restrict environment (local/testing) for dangerous features
|
||||||
|
- [ ] Validate and sanitize all user input
|
||||||
|
- [ ] Use prepared statements for database queries
|
||||||
|
- [ ] Clean up temporary files/resources
|
||||||
|
- [ ] Document security considerations
|
||||||
|
|
||||||
|
## Incident Response
|
||||||
|
|
||||||
|
### If Hades credentials are compromised:
|
||||||
|
|
||||||
|
1. Revoke the user's Hades access
|
||||||
|
2. Rotate `HADES_TOKEN` environment variable
|
||||||
|
3. Review audit logs for suspicious activity
|
||||||
|
4. Check server access logs for SSH activity
|
||||||
|
5. Consider rotating SSH keys for connected servers
|
||||||
|
|
||||||
|
### If SSH key is exposed:
|
||||||
|
|
||||||
|
1. Delete the server record immediately
|
||||||
|
2. Regenerate SSH key on the actual server
|
||||||
|
3. Review server logs for unauthorized access
|
||||||
|
4. Update the server record with new key
|
||||||
|
|
||||||
|
## Recommendations for Production
|
||||||
|
|
||||||
|
1. **Separate Hades token per environment** - Don't use same token across staging/production
|
||||||
|
2. **Regular audit log review** - Monitor for unusual access patterns
|
||||||
|
3. **Limit Hades users** - Only grant to essential personnel
|
||||||
|
4. **Use hardware keys** - For servers, prefer hardware security modules
|
||||||
|
5. **Network segmentation** - Restrict admin panel to internal networks
|
||||||
|
6. **Two-factor authentication** - Require 2FA for Hades-tier accounts
|
||||||
|
7. **Session timeout** - Consider shorter session duration for Hades users
|
||||||
Loading…
Add table
Reference in a new issue