This README is the one indexed from the repository at its latest ref, not from the tag for this version.

Pared

Pared is a secure, high-performance Linux host security control plane and real-time administrative web console written in Crystal. Built on Kemal and Blueprint server-rendered components with SQLite3, a small vanilla-JS/WebSocket layer, and native libsystemd journal streaming, it unifies firewalld and NetworkManager orchestration into a centralized, reactive interface.

Pared features mutual TLS (mTLS) passwordless authentication, Linux PAM/SSSD identity management, native C-bindings to libsystemd for live journal streaming, kernel packet simulation, automated anti-lockout rollback guardians, and container network bypass auditing.

---

Key Control Plane Features

• Living Topology & Graph Engine: Directed acyclic graph (DAG) topology mapping physical interfaces, network bonds, bridges, WireGuard tunnels, Netavark container networks, firewall zones, and listening daemons.
• Trace-a-Packet Simulator: 7-stage deterministic packet evaluation pipeline simulating packet traversal across ingress interfaces, source overrides, rich rules, policies, NAT, and socket targets without injecting live network traffic.
• Anti-Lockout Guardian (Dead Man's Switch): Automated volatile staging snapshots with a 30-second rollback watchdog timer on disruptive zone target mutations (DROP/REJECT), preventing operator lockout.
• Visual Rich Rule Compiler & AST: Syntax validation, conflict detection (shadowed, contradictory, and duplicate rules), dual-stack IPv4/IPv6 CIDR containment, and plain-English rule translations.
• Host Socket & Daemon Correlator: Real-time correlation of open TCP/UDP sockets with local systemd service units, process IDs, and firewall exposure states.
• Service Exposure Console: One actionable row per port/protocol merging listener and firewall state (ghost opening, shadow block, exposed, local only), with per-row remediation and live filtering.
• Netavark Container Bridge Inspector: Automatic discovery of Podman/Netavark container networks and zero-trust firewall bypass auditing on wildcard host port binds (0.0.0.0, ::).
• WireGuard Orchestrator & Visual Hub: Cryptographic key hygiene, peer endpoint configuration, and dual-stack IPv4/IPv6 CIDR overlap detection.
• Omnibar Keyboard-Driven UX: Full keyboard navigation and mutation palette (/trace, /rollback <zone>, /wg peer <term>, /zone add), with server-side dispatch to the matching console.
• Hardened Identity & Access (RBAC): Linux PAM fallback with account expiration checks (pam_acct_mgmt), SSSD D-Bus group resolution, X.509 client certificate mTLS with CRL checks, and CSRF protection.
• Production Observability: Live systemd journal streaming over WebSockets, native watchdog integration via NOTIFY_SOCKET, and structured audit logging.

---

Quick Start

Prerequisites

• Fedora Linux/RHEL 9+ (or systemd-based Linux distribution)
• Crystal Compiler (v1.21+)
• libsystemd development headers (systemd-devel)
• firewalld and NetworkManager active daemons
• SQLite3 and OpenSSL

Installation & Local Setup

# 1. Clone repository & install shard dependencies
git clone https://gitlab.com/renich/pared.git
cd pared
shards install

# 2. Provision host system Polkit rules & seed default database
make setup
make seed

# 3. Compile and launch development server
make build
make run

The control plane web dashboard is available at http://localhost:3636.

Default Demo Credentials

When seeded via make seed, default credentials are:

• Email: admin@example.com
• Password: password

(Local system PAM user accounts with UID ≥ 1000 can also authenticate directly).

---

Testing & Quality Assurance

Pared enforces strict quality standards with comprehensive unit and E2E browser test suites:

# Run unit & integration test suite (200 examples)
make spec

# Run headless Selenium E2E browser test suite (16 examples)
make test-browser

# Run static analysis (Ameba)
bin/ameba

# Run security vulnerability scan (Flaw)
bin/flaw scan .

# Run reStructuredText documentation linter (crstlint)
find docs -name "*.rst" -exec crstlint {} +

---

Production Deployment & Systemd Service

A production-hardened systemd unit file is provided at scripts/pared.service, implementing kernel sandboxing, watchdog pinging, and capability restrictions:

# Build production release binary
make release

# Install binary and systemd service
sudo install -m 755 bin/pared /usr/local/bin/pared
sudo install -m 644 scripts/pared.service /etc/systemd/system/pared.service

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable --now pared.service

# Inspect service status and watchdog health
sudo systemctl status pared.service

---

Documentation & Reference Library

Comprehensive architectural specifications and decision records are maintained in the docs/ directory:

• Technical Specifications
• Functional Specifications
• Project Roadmap
• Architecture Decision Records (ADRs)
• Echelon Protocol Security & Architecture Audits

To build the Sphinx HTML documentation locally:

sphinx-build -b html -W docs docs/_build/html

---

Repositories & Mirrors

• Primary Canonical Repository: GitLab
• Official Mirror: Codeberg

---

Maintainer

• Rénich Bon Ćirić (@renich) — Creator & Lead Architect
• Released under the GNU General Public License v3.0 or later (GPL-3.0-or-later).