bunny-lab/Borealis-Github-Replica
1
0
Fork 0
mirror of https://github.com/bunny-lab-io/Borealis.git synced 2025-10-26 15:21:57 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' of https://github.com/bunny-lab-io/Borealis

Browse Source
This commit is contained in:
Nicole Rappe
2025-10-19 22:38:14 -06:00
parent 7da61336c9 51cb417e39
commit 6e2f4bf526
1 changed files with 114 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
readme.md
View File

@@ -2,8 +2,6 @@
Borealis is a remote management platform with a simple, visual automation layer, enabling you to leverage scripts, Ansible playbooks, and advanced nodegraph-based automation workflows. I originally created Borealis to work towards consolidating the core functionality of several standalone automation platforms in my homelab, such as TacticalRMM, Ansible AWX, SemaphoreUI, and a few others.
⚠️**Security Note**: Server/Client/API authentication mechanisms are not yet enabled. For your own safety, use Borealis in controlled environments only.
---
## Features
@@ -80,4 +78,117 @@ http:
servers:
- url: "http://127.0.0.1:5000"
passHostHeader: true
```
```
## Security Breakdowns
The process that agents go through when authenticating securely with a Borealis server can be a little complex, so I have included a sequence diagram below to go over the core systems so you can visually understand what is going on behind-the-scenes.
### Agent/Server Enrollment
```mermaid
sequenceDiagram
participant Operator
participant Server
participant SYS as "SYSTEM Agent"
participant CUR as "CURRENTUSER Agent"
Operator->>Server: Request installer code
Server-->>Operator: Deliver hashed installer code
Note over Operator,Server: Human-controlled code binds enrollment to known device
par TLS Handshake (SYSTEM)
SYS->>Server: Initiate TLS session
Server-->>SYS: Present TLS certificate
and TLS Handshake (CURRENTUSER)
CUR->>Server: Initiate TLS session
Server-->>CUR: Present TLS certificate
end
Note over SYS,Server: Certificate pinning plus CA checks stop MITM
Note over CUR,Server: Pinning also blocks spoofed control planes
SYS->>SYS: Generate Ed25519 identity key pair
Note right of SYS: Private key stored under Certificates/... protected by DPAPI or chmod 600
CUR->>CUR: Generate Ed25519 identity key pair
Note right of CUR: Private key stored in user context and DPAPI-protected
SYS->>Server: Enrollment request (installer code, public key, fingerprint)
CUR->>Server: Enrollment request (installer code, public key, fingerprint)
Server->>Operator: Prompt for enrollment approval
Operator-->>Server: Approve device enrollment
Note over Operator,Server: Manual approval blocks rogue agents
Server-->>SYS: Send enrollment nonce
Server-->>CUR: Send enrollment nonce
SYS->>Server: Return signed nonce to prove key possession
CUR->>Server: Return signed nonce
Note over Server,Operator: Server verifies signatures and records GUID plus key fingerprint
Server->>SYS: Issue GUID, short-lived token, refresh token, server cert, script-signing key
Server->>CUR: Issue GUID, short-lived token, refresh token, server cert, script-signing key
Note over SYS,Server: Agent pins cert, stores GUID, DPAPI-encrypts refresh token
Note over CUR,Server: Agent stores GUID, pins cert, encrypts refresh token
Note over Server,Operator: Database keeps refresh token hash, key fingerprint, audit trail
loop Secure Sessions
SYS->>Server: REST heartbeat and job polling with Bearer token
CUR->>Server: REST heartbeat and WebSocket connect with Bearer token
Server-->>SYS: Provide new access token before expiry
Server-->>CUR: Provide new access token before expiry
SYS->>Server: Refresh request over pinned TLS
CUR->>Server: Refresh request over pinned TLS
end
Server-->>SYS: Deliver script payload plus Ed25519 signature
SYS->>SYS: Verify signature before execution
Server-->>CUR: Deliver script payload plus Ed25519 signature
CUR->>CUR: Verify signature and reject tampered content
Note over SYS,CUR: Signature failure triggers re-enrollment and detailed logging
Note over Server,Operator: Persistent records and approvals sustain long term trust
```
### Code-Signed Remote Script Execution
```mermaid
sequenceDiagram
participant Operator
participant Server
participant SYS as "SYSTEM Agent"
participant CUR as "CURRENTUSER Agent"
Operator->>Server: Upload or author script
Server->>Server: Store script and metadata on-disk
Operator->>Server: Request script execution on a specific device + execution context (NT Authority\SYSTEM or Current-User)
Server->>Server: Load Ed25519 code signing key from secure store
Server->>Server: Sign script hash and execution manifest (The Assembly)
Server->>Server: Enqueue job with signed payload for target agent (SYSTEM or CurrentUser)
Note over Server: Dispatch limited to enrolled agents with valid GUID + tokens
loop Agent job polling (pinned TLS + Bearer token)
SYS->>Server: REST heartbeat and job poll
CUR->>Server: REST heartbeat and job poll
Server-->>SYS: Pending job payloads
Server-->>CUR: Pending job payloads
end
alt SYSTEM context
Server-->>SYS: Script, signature, hash, execution parameters
SYS->>SYS: Verify TLS pinning and token freshness
SYS->>SYS: Verify Ed25519 signature using pinned server key
SYS->>SYS: Recalculate script hash and compare
Note right of SYS: Verification failure stops execution and logs incident
SYS->>SYS: Execute via SYSTEM scheduled-task runner
SYS-->>Server: Return execution status, output, telemetry
else CURRENTUSER context
Server-->>CUR: Script, signature, hash, execution parameters
CUR->>CUR: Verify TLS pinning and token freshness
CUR->>CUR: Verify Ed25519 signature using pinned server key
CUR->>CUR: Recalculate script hash and compare
Note right of CUR: Validation failure stops execution and logs incident
CUR->>CUR: Execute within interactive PowerShell host
CUR-->>Server: Return execution status, output, telemetry
end
Server->>Server: Record results and logs alongside job metadata
Note over SYS,CUR: Pinned TLS, signed payloads, and DPAPI-protected secrets defend against tampering and replay
```