Home / Applications / Chromatic Core

Chromatic Core

A transaction-safe, compiled high-performance Linux control panel engine designed to replace legacy web-to-shell administrative wrappers with a secure state machine.

Control Panel Engine AGPL-3.0 License Rust / Tokio WIP Status

Overview

Chromatic Core is a next-generation control panel engine for Linux servers, written from the ground up in Rust. It targets the architectural insecurity of legacy web control panels (such as HestiaCP, VestaCP, or cPanel) by completely replacing vulnerable shell-spawning PHP scripts and wrapper utilities with a single, compile-time type-safe system daemon.

Built on defensive programming invariants, Chromatic Core rejects dynamic command building and global configuration overrides. Instead, the engine enforces kernel-level privilege separation, deterministic directory traversal limits (combating symlink/TOCTOU races), and strictly typed IPC payloads.

Core Architectural Pillars

Absolute Separation of Privilege

  • Sandboxed Web UI: The administrative web panel UI runs under a completely unprivileged system user (chromatic-admin) with zero write capability to system configuration files.
  • State Machine Daemon: Privileged operations are executed solely by the compiled chromatic-core-daemon running as root (or with confined capabilities like CAP_CHOWN, CAP_DAC_OVERRIDE, and CAP_NET_ADMIN). Communication is conducted via strongly-typed IPC messages over Unix Domain Sockets (UDS).

TOCTOU Symlink Race Defenses

  • FD-Relative Operations: Path-based operations are vulnerable to Time-of-Check to Time-of-Use (TOCTOU) symlink substitution exploits. Chromatic Core caches file descriptors of base directories (e.g., HOME_DIR_FD for /home) at startup during single-threaded boot initialization.
  • Strict Confined APIs: Tenant folder creation and file writes utilize relative file descriptor operations (openat(2) and mkdirat(2)) with O_NOFOLLOW | O_DIRECTORY | O_CLOEXEC flags. File permissions are set directly on active descriptors (via fchmod/fchown), bypassing process umask and directory swap windows.
  • Hardlink Audits: Immediately after opening any descriptor inside tenant homes, the daemon calls fstat and aborts if st_nlink > 1 to block hardlink hijack tricks.

Kernel-Level Socket Segmentation

  • Segmented UDS Channels: The system isolates connections at the kernel boundary. The global socket at /run/chromatic/admin.sock handles non-tenant requests, while individual tenants communicate via isolated sockets at /run/chromatic/tenants/<tenant>.sock owned strictly by root:<tenant>.
  • Peer Authorization: The daemon validates callers at the kernel boundary via SO_PEERCRED on incoming connections, matching tenant socket bindings directly to the connecting UID.
  • Frame Size Limiting: Streams are immediately wrapped in a length-delimited reader enforcing a maximum payload size of 64KB (65536 bytes), disconnecting clients instantly if exceeded to prevent memory exhaustion DoS.

Direct Netlink Firewall Driver

  • No Subprocess Spawning: Bypasses spawning external iptables or nft command wrappers. Chromatic Core binds directly to Netlink sockets to perform atomic firewall ruleset updates via native libnftables library contexts.

Isolated Tenant Mail SQLite Shards

  • No Monolithic Databases: Rejects central mail databases. Mail accounts are sharded per tenant (e.g. stored at /home/<tenant>/mail/mail.db), initialized in WAL (Write-Ahead Logging) mode with connection pools and a 5000ms busy timeout handler.

Developer & Sandbox Testing

Chromatic Core includes a robust developer compilation feature that allows compiling and executing the UDS socket listener sandboxed without requiring system root privileges.

1. Running Tests in User Sandbox

Compile and run workspace unit and integration tests with developer-level credential authorization active:

bash - Cargo Test
# Run tests with local UID authorization and randomized /run/user/<uid> sockets cargo test --all --features test-env

2. Linting & Style Checks

Validate the codebase for formatting adherence and security warnings:

bash - Code Hygiene
# Verify formatting cargo fmt --all -- --check # Check clippy warnings with sandbox features active cargo clippy --all --all-targets --features test-env