Skip to content

Security and Clustering

Jump to bottom
Sparks Skywere edited this page May 14, 2026 · 1 revision

Security and Clustering

This page explains web/network/SSL security and the host/subhost clustering model with its workflows and APIs.

Home

14. Security

14.1 Web Security

The WebSecurityManager (Modules/security/web_security.py) provides web application security through multiple integrated components:

Rate Limiting:

  • The RateLimiter class implements sliding window rate limiting.
  • Tracks request counts per IP address within configurable time windows.
  • Configurable limits per endpoint or globally.

Account Lockout:

  • The AccountLockout class protects against brute-force attacks.
  • After 5 failed login attempts within 5 minutes, the account is locked for 15 minutes.
  • Lockout status and remaining attempts are communicated in API responses.

CSRF Protection:

  • The CSRFProtection class generates and validates CSRF tokens for form submissions.
  • Tokens are tied to user sessions and have configurable expiration.

Input Validation:

  • The InputValidator class detects and blocks common attack patterns:
    • SQL Injection — Detects common SQL injection patterns (UNION SELECT, OR 1=1, DROP TABLE, etc.).
    • XSS (Cross-Site Scripting) — Detects script injection attempts (<script>, javascript:, onerror=, etc.).
    • Path Traversal — Detects directory traversal patterns (../, ..\\, %2e%2e).

Client-Side XSS Prevention:

  • The escapeHtml() utility function in the web interface sanitises API response data before rendering into the DOM.
  • All dynamic content rendered via innerHTML is escaped to prevent stored/reflected XSS from server data.

Path Security:

  • The PathSecurity class provides safe path joining that prevents directory traversal.
  • All file paths are validated to ensure they remain within allowed directories.

IP Security:

  • The IPSecurity class manages IP allowlisting for sensitive operations.

Security Headers: The web server applies standard security headers to all responses:

  • Content-Security-Policy (CSP) — Restricts resource loading origins.
  • Strict-Transport-Security (HSTS) — Enforces HTTPS when SSL is enabled.
  • X-Frame-Options — Prevents clickjacking (set to DENY).
  • X-Content-Type-Options — Prevents MIME-type sniffing (set to nosniff).
  • X-XSS-Protection — Enables browser XSS filters.
  • Referrer-Policy — Controls referrer information leakage.

14.2 Network Security

The network security module (Modules/security/network_security.py) provides Flask decorators for network-level access control:

@require_allowed_network() — Restricts access to requests from allowed network ranges. Default allowed networks include:

  • 127.0.0.0/8 — Localhost (always allowed)
  • 10.0.0.0/8 — Private network (Class A)
  • 172.16.0.0/12 — Private network (Class B)
  • 192.168.0.0/16 — Private network (Class C)

@require_cluster_network_security() — Additional restrictions for cluster API endpoints, ensuring only authorised cluster nodes can communicate.

14.3 SSL/TLS Certificate Management

The SSL utilities module (Modules/security/ssl_utils.py) manages SSL/TLS certificates for secure HTTPS communication:

Self-Signed Certificate Generation:

  • Generates RSA 2048-bit key pairs.
  • Creates X.509 certificates with Subject Alternative Names (SANs) that include all local IP addresses, the hostname, and localhost.
  • Certificate validity is set to 1 year by default.
  • Certificates and keys are stored in the ssl/ directory as server.crt and server.key.

Certificate Verification:

  • Validates existing certificates for expiration, key matching, and SAN coverage.
  • Reports certificate details including issuer, subject, validity period, and SANs.

Auto-Provisioning:

  • If SSL is enabled but no certificate exists, one is automatically generated.
  • If an existing certificate is expired or invalid, it is regenerated.

CLI Interface:

python Modules/security/ssl_utils.py generate   # Generate a new self-signed certificate
python Modules/security/ssl_utils.py verify     # Verify the existing certificate
python Modules/security/ssl_utils.py info       # Display certificate details

14.4 Cluster Security

The cluster security module (Modules/security/cluster_security.py, SimpleClusterManager) manages cluster membership:

  • Master/Node Topology — A single Host acts as the cluster master, with Subhost nodes joining as members.
  • Join Request Workflow — Nodes must request to join, and the Host admin must approve each request. This prevents unauthorized nodes from joining the cluster.
  • Dual Storage — Cluster role configuration is stored in both the Windows Registry and the cluster database for redundancy.
  • Token-Based Authentication — Cluster communication uses token-based authentication with expiration and revocation support.

15. Clustering and Multi-Node Management

15.1 Cluster Architecture (Host/Subhost)

Server Manager supports a basic clustering model with two roles:

Host:

  • Acts as the central management server.
  • Runs the full web interface, API, and dashboard.
  • Processes join requests from Subhost nodes.
  • Can remotely manage servers on connected Subhosts by proxying API calls.
  • Maintains the cluster database with all node information.

Subhost:

  • Connects to an existing Host node.
  • Runs a local dashboard on port 5002.
  • Sends periodic heartbeats to the Host to report status.
  • Responds to remote management commands forwarded by the Host.
  • Sets the CLUSTER_HOST_URL environment variable for Host discovery.

Communication Protocol: All cluster communication uses HTTP/HTTPS REST API calls between nodes. The Host proxies requests to Subhosts by forwarding them to the Subhost's API endpoint and returning the response.

15.2 Join Request Workflow

The cluster join workflow follows a request-and-approval pattern:

  1. Request: A Subhost sends a join request to the Host: POST /api/cluster/request-join with node name and IP address. The request is stored in the pending_requests table.

  2. Review: The Host administrator views pending requests in the dashboard or cluster management web page. Each request shows the requesting node's name, IP address, and request timestamp.

  3. Approve or Reject: The administrator can:

    • Approve (POST /api/cluster/requests/<id>/approve) — The node is added to the cluster_nodes table with "approved" status, and an authentication token is generated.
    • Reject (POST /api/cluster/requests/<id>/reject) — The request is removed from the pending queue.

  4. Polling: The Subhost periodically checks GET /api/cluster/check-approval/<id> to see if its request has been approved. Once approved, it receives its authentication token and begins sending heartbeats.

  5. Heartbeat: Approved Subhosts send periodic heartbeats (POST /api/cluster/heartbeat) to update their last_ping timestamp. The heartbeat includes node name, IP, port, and server count. Nodes that stop sending heartbeats are eventually marked as offline.

  6. Revocation: The Host administrator can revoke a node at any time (DELETE /api/cluster/nodes/<id>), which removes it from the cluster.

15.3 Cluster API Endpoints

The cluster API is implemented as a Flask Blueprint (api/cluster.py) and registered under /api/cluster/:

Join Workflow:

Method Endpoint Description
POST /api/cluster/request-join Submit a join request
GET /api/cluster/requests List pending join requests
POST /api/cluster/requests/<id>/approve Approve a join request
POST /api/cluster/requests/<id>/reject Reject a join request
GET /api/cluster/check-approval/<id> Check approval status

Node Management:

Method Endpoint Description
GET /api/cluster/nodes List all cluster nodes
DELETE /api/cluster/nodes/<id> Revoke (remove) a node

Subhost Management:

Method Endpoint Description
GET /api/cluster/subhosts List subhosts with status
POST /api/cluster/heartbeat Send node heartbeat

Status:

Method Endpoint Description
GET /api/cluster/status Get cluster status summary
GET /api/cluster/host-status Get host status details
GET /api/cluster/role Get this node's cluster role

Remote Server Operations (Host Only):

Method Endpoint Description
GET /api/cluster/subhost/<id>/servers List servers on a subhost
POST /api/cluster/subhost/<id>/servers Create a server on a subhost
DELETE /api/cluster/subhost/<id>/servers/<name> Remove a server from a subhost
POST /api/cluster/subhost/<id>/servers/<name>/start Start a server on a subhost
POST /api/cluster/subhost/<id>/servers/<name>/stop Stop a server on a subhost
POST /api/cluster/subhost/<id>/servers/<name>/restart Restart a server on a subhost

All remote server operations are forwarded to the target Subhost's API via _forward_request_to_subhost().

15.4 Agent Management GUI

The Agent Manager (Modules/ui/agents.py) provides a Tkinter GUI for cluster administration:

The GUI includes:

  • Cluster Status Panel — Shows the current cluster role, number of registered nodes, and overall cluster health.
  • Pending Requests Section — A tree view of pending join requests with Approve and Reject buttons. Each request shows the node name, IP address, and request time.
  • Registered Nodes Section — A tree view of all cluster nodes with status indicators (online/offline). An "Add Node" form allows manually registering nodes. A right-click context menu provides: Ping Node, View Servers, Remove Node.
  • Background Polling — The GUI polls the cluster database every 5 seconds to update node statuses and detect new join requests.

Node Pinging: The ping_node() method sends an HTTP request to GET /api/status on the target node to verify connectivity and retrieve basic status information.

Server Manager Wiki

Clone this wiki locally