187 lines
4.9 KiB
Markdown
187 lines
4.9 KiB
Markdown
# SysAdmin Agent Roadmap
|
|
|
|
This document tracks Agent-specific work for the AI SysAdmin system.
|
|
|
|
## Completed Work
|
|
|
|
### Core Infrastructure
|
|
- [x] Secure startup
|
|
- [x] Automatic registration with orchestrator
|
|
- [x] Polling loop (configurable interval)
|
|
- [x] Heartbeat loop
|
|
- [x] Executor registry system
|
|
- [x] BaseExecutor + ExecutionResult model
|
|
- [x] Logging with structlog
|
|
- [x] Sandboxing and path validation
|
|
- [x] Task timing, error propagation
|
|
- [x] Circuit breaker for resilience
|
|
- [x] Full test suite (140+ tests)
|
|
|
|
### Executors
|
|
|
|
| Executor | Purpose | Tests | Status |
|
|
|----------|---------|-------|--------|
|
|
| ECHO | Test connectivity | ✅ | Done |
|
|
| SHELL | Run allowed shell commands | ✅ | Done |
|
|
| ENV_UPDATE | Atomic env file edits | ✅ | Done |
|
|
| ENV_INSPECT | Read and parse env files | ✅ | Done |
|
|
| FILE_WRITE | Write files safely | ✅ | Done |
|
|
| FILE_INSPECT | Read files with size limits | 24 | Done |
|
|
| DOCKER_RELOAD | Pull + up -d compose stacks | 26 | Done |
|
|
| COMPOSITE | Chain multiple executors | ✅ | Done |
|
|
| NEXTCLOUD | Nextcloud-specific tasks | ✅ | Done |
|
|
| PLAYWRIGHT | Browser automation | ✅ | Done |
|
|
|
|
### Security
|
|
- [x] Path sandboxing to `/opt/letsbe/`
|
|
- [x] Allowed file root validation
|
|
- [x] Max file size limits
|
|
- [x] Shell command timeout
|
|
- [x] Non-root execution (configurable)
|
|
|
|
---
|
|
|
|
## Remaining Work
|
|
|
|
### Phase 1: Support for New Playbooks
|
|
|
|
No new executors needed - existing executors support all Phase 1 tool playbooks via COMPOSITE tasks.
|
|
|
|
---
|
|
|
|
### Phase 2: Introspection Executors
|
|
|
|
| Executor | Purpose | Status |
|
|
|----------|---------|--------|
|
|
| SERVICE_DISCOVER | List all running services/containers | ⬚ Todo |
|
|
| CONFIG_SCAN | Find misconfigurations across services | ⬚ Todo |
|
|
| NGINX_INSPECT | Parse nginx configs for domain info | ⬚ Todo |
|
|
|
|
---
|
|
|
|
### Phase 3: Server-Level Executors
|
|
|
|
| Executor | Purpose | Status |
|
|
|----------|---------|--------|
|
|
| NGINX_RELOAD | Validate and reload nginx | ⬚ Todo |
|
|
| HEALTHCHECK | Check docker status, ports, logs | ⬚ Todo |
|
|
| STACK_HEALTH | Verify docker compose stack integrity | ⬚ Todo |
|
|
| PACKAGE_UPGRADE | System package updates | ⬚ Todo |
|
|
|
|
**NGINX_RELOAD requirements:**
|
|
- Validate config with `nginx -t`
|
|
- Reload with `nginx -s reload`
|
|
- Rollback on failure
|
|
- Path sandboxing for config files
|
|
|
|
**HEALTHCHECK requirements:**
|
|
- Check container status via Docker API
|
|
- Verify expected ports are listening
|
|
- Scan logs for error patterns
|
|
- Return structured health report
|
|
|
|
---
|
|
|
|
### Phase 4: Advanced Executors
|
|
|
|
| Executor | Purpose | Status |
|
|
|----------|---------|--------|
|
|
| BACKUP | Create and upload backups | ⬚ Todo |
|
|
| RESTORE | Restore from backup | ⬚ Todo |
|
|
| LOG_TAIL | Stream logs from containers | ⬚ Todo |
|
|
| CERT_CHECK | Verify SSL certificate status | ⬚ Todo |
|
|
|
|
---
|
|
|
|
### Phase 5: Playwright Browser Automation ✅
|
|
|
|
**Completed:**
|
|
|
|
- [x] Playwright installation in container
|
|
- [x] Scenario-based executor architecture
|
|
- [x] Domain allowlist security (mandatory)
|
|
- [x] Screenshot capture for success/failure
|
|
- [x] Artifact storage with per-task isolation
|
|
- [x] Route interception for domain blocking
|
|
- [x] Unit tests for validation logic
|
|
|
|
**Available Scenarios:**
|
|
|
|
| Scenario | Purpose | Status |
|
|
|----------|---------|--------|
|
|
| `echo` | Test connectivity and page load | ✅ Done |
|
|
| `nextcloud_initial_setup` | Automate Nextcloud admin setup wizard | ✅ Done |
|
|
|
|
**Usage Example:**
|
|
```json
|
|
{
|
|
"type": "PLAYWRIGHT",
|
|
"payload": {
|
|
"scenario": "nextcloud_initial_setup",
|
|
"inputs": {
|
|
"base_url": "https://cloud.example.com",
|
|
"admin_username": "admin",
|
|
"admin_password": "secret123"
|
|
},
|
|
"options": {
|
|
"allowed_domains": ["cloud.example.com"],
|
|
"screenshot_on_success": true
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Remaining Work:**
|
|
- [ ] MCP sidecar service for exploratory browser control
|
|
- [ ] Additional tool setup scenarios (Keycloak, Poste, etc.)
|
|
|
|
---
|
|
|
|
## Executor Implementation Pattern
|
|
|
|
All executors follow the same pattern:
|
|
|
|
```python
|
|
from app.executors.base import BaseExecutor, ExecutionResult
|
|
|
|
class NewExecutor(BaseExecutor):
|
|
"""Description of what this executor does."""
|
|
|
|
async def execute(self, payload: dict) -> ExecutionResult:
|
|
# 1. Validate payload
|
|
# 2. Validate paths (if file operations)
|
|
# 3. Perform operation
|
|
# 4. Return ExecutionResult(success=True/False, data={...}, error=...)
|
|
```
|
|
|
|
Register in `app/executors/__init__.py`:
|
|
```python
|
|
from .new_executor import NewExecutor
|
|
EXECUTOR_REGISTRY["NEW_TYPE"] = NewExecutor
|
|
```
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
All executors must have comprehensive tests:
|
|
|
|
```bash
|
|
# Run all tests
|
|
pytest
|
|
|
|
# Run specific executor tests
|
|
pytest tests/test_executors/test_new_executor.py -v
|
|
|
|
# Run with coverage
|
|
pytest --cov=app/executors
|
|
```
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. Existing executors support Phase 1 - no changes needed
|
|
2. When Phase 2 starts, implement SERVICE_DISCOVER executor
|
|
3. When Phase 3 starts, implement NGINX_RELOAD and HEALTHCHECK
|