mirror of
https://github.com/bunny-lab-io/Borealis.git
synced 2026-02-04 03:30:32 -07:00
83 lines
4.7 KiB
Markdown
83 lines
4.7 KiB
Markdown
# Architecture Overview
|
|
[Back to Docs Index](index.md) | [Index (HTML)](index.html)
|
|
|
|
## Purpose
|
|
Explain how Borealis is structured and how the core components interact end to end.
|
|
|
|
## Core Components
|
|
- Engine: Flask + Socket.IO runtime that hosts APIs, scheduled jobs, VPN orchestration, and WebUI assets.
|
|
- WebUI: React single page app served by the Engine (Vite in dev, static build in prod).
|
|
- Agent: Python runtime that enrolls, reports inventory, executes scripts, and opens VPN tunnels.
|
|
- SQLite database: stores devices, approvals, schedules, activity history, tokens, and configuration records.
|
|
- Assemblies: script definitions stored in SQLite domains with payload artifacts on disk.
|
|
- Remote access: WireGuard reverse VPN, remote PowerShell, and Guacamole-backed RDP proxy.
|
|
|
|
## How the Pieces Talk
|
|
- Enrollment: agent calls `/api/agent/enroll/request` and `/api/agent/enroll/poll`, operator approves, Engine issues tokens and cert bundle.
|
|
- Inventory: agent posts `/api/agent/heartbeat` and `/api/agent/details`, Engine updates device records.
|
|
- Quick jobs: operator calls `/api/scripts/quick_run`, Engine emits `quick_job_run` over Socket.IO, agent executes and returns `quick_job_result`.
|
|
- Scheduled jobs: scheduler reads jobs from DB, resolves targets (including filters), then emits quick jobs.
|
|
- VPN tunnels: operator calls `/api/tunnel/connect`, Engine emits `vpn_tunnel_start`, agent starts WireGuard client.
|
|
- Remote shell: UI uses Socket.IO `vpn_shell_*` events, Engine bridges to agent TCP shell over WireGuard.
|
|
- RDP: operator calls `/api/rdp/session`, Engine creates a one-time token and proxies Guacamole WebSocket to guacd.
|
|
- Notifications: operator or services call `/api/notifications/notify`, WebUI receives `borealis_notification` events.
|
|
|
|
## Directory Map (High Level)
|
|
- `Data/Engine/` - Engine source (authoritative).
|
|
- `Data/Agent/` - Agent source (authoritative).
|
|
- `Engine/` - Engine runtime copy (regenerated each launch).
|
|
- `Agent/` - Agent runtime copy (regenerated each launch).
|
|
- `Data/Engine/web-interface/src/` - WebUI source.
|
|
- `Engine/Logs/` and `Agent/Logs/` - runtime logs.
|
|
- `Data/Engine/Assemblies/` and `Engine/Assemblies/` - assemblies (staging and runtime).
|
|
|
|
## API Endpoints
|
|
None on this page. See [API Reference](api-reference.md).
|
|
|
|
## Related Documentation
|
|
- [Engine Runtime](engine-runtime.md)
|
|
- [Agent Runtime](agent-runtime.md)
|
|
- [Security and Trust](security-and-trust.md)
|
|
- [Device Management](device-management.md)
|
|
- [Assemblies and Quick Jobs](assemblies.md)
|
|
- [Scheduled Jobs](scheduled-jobs.md)
|
|
- [VPN and Remote Access](vpn-and-remote-access.md)
|
|
- [UI and Notifications](ui-and-notifications.md)
|
|
|
|
## Codex Agent (Detailed)
|
|
### Service map by folder
|
|
- Engine APIs: `Data/Engine/services/API/` (grouped by domain, registered in `Data/Engine/services/API/__init__.py`).
|
|
- Engine realtime: `Data/Engine/services/WebSocket/` (Socket.IO events: quick jobs, VPN shell, agent socket registry).
|
|
- WebUI hosting: `Data/Engine/services/WebUI/` (SPA static assets and 404 fallback).
|
|
- VPN orchestration: `Data/Engine/services/VPN/` (WireGuard server and tunnel lifecycle).
|
|
- Remote desktop proxy: `Data/Engine/services/RemoteDesktop/` (Guacamole WebSocket proxy).
|
|
- Filters and targeting: `Data/Engine/services/filters/matcher.py` (used by scheduled jobs and filter counts).
|
|
- Agent roles: `Data/Agent/Roles/` (script exec, screenshot, WireGuard tunnel, remote PowerShell, etc).
|
|
|
|
### End-to-end flow examples (use these to debug)
|
|
- Quick job:
|
|
1) UI calls `/api/scripts/quick_run` with script path + hostnames.
|
|
2) Engine signs script and emits `quick_job_run`.
|
|
3) Agent role executes and posts `quick_job_result` over Socket.IO.
|
|
4) Engine updates `activity_history` and emits `device_activity_changed`.
|
|
- VPN shell:
|
|
1) UI calls `/api/tunnel/connect` to request tunnel material.
|
|
2) Engine emits `vpn_tunnel_start` to agent socket.
|
|
3) Agent WireGuard role starts tunnel; agent shell role listens on TCP 47002.
|
|
4) UI opens `vpn_shell_open` Socket.IO event; Engine bridges to TCP shell.
|
|
5) UI sends/receives `vpn_shell_send` and `vpn_shell_output` events.
|
|
|
|
### Runtime boundaries
|
|
- Do not edit `Engine/` or `Agent/` directly. They are recreated on each launch.
|
|
- Always edit `Data/Engine/` and `Data/Agent/` then re-run the bootstrap script.
|
|
|
|
### What to read first when debugging
|
|
- Start with logs: `Engine/Logs/engine.log` and `Agent/Logs/agent.log`.
|
|
- Check domain-specific logs (example: `Engine/Logs/VPN_Tunnel/tunnel.log`).
|
|
- Inspect active DB state in `Engine/database.db` for device/job metadata.
|
|
|
|
### Interaction points to remember
|
|
- REST for inventory, enrollment, and admin actions.
|
|
- Socket.IO for realtime job results, VPN shell, and notifications.
|
|
- WireGuard for remote protocol transport (shell, RDP, future protocols).
|