mirror of
https://github.com/bunny-lab-io/Borealis.git
synced 2026-02-04 05:00:32 -07:00
Documentation Overhaul
This commit is contained in:
116
Docs/device-management.md
Normal file
116
Docs/device-management.md
Normal file
@@ -0,0 +1,116 @@
|
||||
# Device Management
|
||||
[Back to Docs Index](index.md) | [Index (HTML)](index.html)
|
||||
|
||||
## Purpose
|
||||
Explain how Borealis tracks devices, ingests inventory, manages sites and filters, and handles enrollment approvals.
|
||||
|
||||
## Inventory and Status
|
||||
- Agents send heartbeats and inventory payloads to the Engine.
|
||||
- The Engine stores device summaries and detailed hardware/software data in SQLite.
|
||||
- Online status is derived from `last_seen` (online if the heartbeat is within ~5 minutes).
|
||||
|
||||
## Sites and Enrollment Codes
|
||||
- Sites group devices for organizational and targeting purposes.
|
||||
- Each site can have an enrollment code that agents can use during install.
|
||||
- Site mapping is stored separately from device records and exposed via API.
|
||||
|
||||
## Device Filters
|
||||
- Filters are stored in the `device_filters` table as JSON criteria groups.
|
||||
- The Engine computes match counts using `DeviceFilterMatcher` against the inventory snapshot.
|
||||
- Filters can be global or scoped to a site.
|
||||
|
||||
## Device List Views
|
||||
- Operators can save custom table views for the device list UI.
|
||||
- Views are stored per operator and exposed via `/api/device_list_views`.
|
||||
|
||||
## Per-Device VPN Configuration
|
||||
- Each device can have a per-agent allowlist of VPN ports.
|
||||
- These settings are used by the WireGuard service to build firewall rules.
|
||||
|
||||
## Enrollment Approvals
|
||||
- Enrollment requests are queued for admin approval.
|
||||
- Approvals enforce hostname conflict checks and device identity tracking.
|
||||
|
||||
## API Endpoints
|
||||
- `POST /api/agent/heartbeat` (Device Authenticated) - heartbeat + metrics.
|
||||
- `POST /api/agent/details` (Device Authenticated) - inventory payloads.
|
||||
- `GET /api/agents` (Token Authenticated) - online collectors grouped by context.
|
||||
- `GET /api/devices` (Token Authenticated) - device summary list.
|
||||
- `GET /api/devices/<guid>` (Token Authenticated) - device summary by GUID.
|
||||
- `GET /api/device/details/<hostname>` (Token Authenticated) - full device details.
|
||||
- `POST /api/device/description/<hostname>` (Token Authenticated) - update description.
|
||||
- `GET /api/device/vpn_config/<agent_id>` (Token Authenticated) - VPN allowed ports.
|
||||
- `PUT /api/device/vpn_config/<agent_id>` (Token Authenticated) - update VPN allowed ports.
|
||||
- `GET /api/device_list_views` (Token Authenticated) - list saved views.
|
||||
- `GET /api/device_list_views/<int:view_id>` (Token Authenticated) - get saved view.
|
||||
- `POST /api/device_list_views` (Token Authenticated) - create saved view.
|
||||
- `PUT /api/device_list_views/<int:view_id>` (Token Authenticated) - update saved view.
|
||||
- `DELETE /api/device_list_views/<int:view_id>` (Token Authenticated) - delete saved view.
|
||||
- `GET /api/sites` (Token Authenticated) - list sites.
|
||||
- `POST /api/sites` (Admin) - create site.
|
||||
- `POST /api/sites/delete` (Admin) - delete sites.
|
||||
- `GET /api/sites/device_map` (Token Authenticated) - hostname to site map.
|
||||
- `POST /api/sites/assign` (Admin) - assign devices to site.
|
||||
- `POST /api/sites/rename` (Admin) - rename site.
|
||||
- `POST /api/sites/rotate_code` (Admin) - rotate site enrollment code.
|
||||
- `GET /api/device_filters` (Token Authenticated) - list filters.
|
||||
- `GET /api/device_filters/<filter_id>` (Token Authenticated) - get filter.
|
||||
- `POST /api/device_filters` (Token Authenticated) - create filter.
|
||||
- `PUT /api/device_filters/<filter_id>` (Token Authenticated) - update filter.
|
||||
- `GET /api/admin/enrollment-codes` (Admin) - list enrollment codes.
|
||||
- `POST /api/admin/enrollment-codes` (Admin) - create enrollment codes.
|
||||
- `DELETE /api/admin/enrollment-codes/<code_id>` (Admin) - delete enrollment codes.
|
||||
- `GET /api/admin/device-approvals` (Admin) - approval queue.
|
||||
- `POST /api/admin/device-approvals/<approval_id>/approve` (Admin) - approve device.
|
||||
- `POST /api/admin/device-approvals/<approval_id>/deny` (Admin) - deny device.
|
||||
|
||||
## Related Documentation
|
||||
- [Agent Runtime](agent-runtime.md)
|
||||
- [Security and Trust](security-and-trust.md)
|
||||
- [Scheduled Jobs](scheduled-jobs.md)
|
||||
- [VPN and Remote Access](vpn-and-remote-access.md)
|
||||
- [API Reference](api-reference.md)
|
||||
|
||||
## Codex Agent (Detailed)
|
||||
### Key files and services
|
||||
- Device APIs: `Data/Engine/services/API/devices/` (management, approval, tunnel, rdp, routes).
|
||||
- Filters: `Data/Engine/services/filters/matcher.py` and `Data/Engine/services/API/filters/management.py`.
|
||||
- Enrollment approvals: `Data/Engine/services/API/devices/approval.py`.
|
||||
|
||||
### Inventory ingestion behavior
|
||||
- `/api/agent/heartbeat` updates `last_seen` and key metrics (last_user, OS, uptime).
|
||||
- `/api/agent/details` stores full inventory payloads for memory, network, storage, software, cpu.
|
||||
- JSON blobs are serialized into SQLite text columns and rehydrated for UI.
|
||||
|
||||
### Status computation
|
||||
- Online/offline is computed from `last_seen` (online if within ~300 seconds).
|
||||
- UI tables use the derived `status` field from the API payload.
|
||||
|
||||
### Device identity and keys
|
||||
- Device identity is tied to GUID + SSL fingerprint + token version.
|
||||
- `DeviceAuthManager` enforces fingerprint matches and token version checks.
|
||||
|
||||
### Sites and enrollment codes
|
||||
- Sites live in `sites` and `device_sites` tables (see `Data/Engine/database.py`).
|
||||
- Enrollment codes are stored in `enrollment_install_codes` and can be site-scoped.
|
||||
- Rotating a site code updates the code record and timestamps.
|
||||
|
||||
### Device filters (matching)
|
||||
- Filters are stored as JSON criteria groups in `device_filters.criteria_json`.
|
||||
- `DeviceFilterMatcher.fetch_devices()` loads a snapshot from `devices` and joins `sites`.
|
||||
- `count_filter_devices` computes match counts for UI summaries.
|
||||
|
||||
### Per-device VPN configuration
|
||||
- Allowed ports are stored in `device_vpn_config.allowed_ports` (JSON list).
|
||||
- WireGuard uses this list to build firewall rules and allowlist transport ports.
|
||||
|
||||
### Approval flow detail
|
||||
- Enrollment requests create approval records (pending).
|
||||
- Admin approval handles hostname conflicts (merge or rename).
|
||||
- Denials are logged and remove pending requests.
|
||||
|
||||
### Debug checklist
|
||||
- Device missing from list: check `Engine/database.db` tables `devices` and `device_keys`.
|
||||
- Online status wrong: check `last_seen` timestamps in `devices` table.
|
||||
- Filter counts zero: validate `device_filters.criteria_json` and matcher logic.
|
||||
- VPN config not applying: confirm `device_vpn_config` row and tunnel logs.
|
||||
Reference in New Issue
Block a user