Added Security Breakdowns

readme.md

@@ -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
+```