🌐 getbor.dev · 📦 GitHub · 📖 Contributing · 🔒 Security

Bor is an open-source policy management system for Linux desktops. A central server distributes configuration policies to enrolled Linux endpoints in real-time. A lightweight Go agent daemon on each machine receives policies over an encrypted gRPC stream and enforces them locally.

Currently enforced policies:

• Firefox ESR — system-wide policies.json (RPM/DEB and Flatpak)
• Google Chrome / Chromium — managed JSON in /etc/opt/chrome/ and /etc/chromium/ (including Flatpak)
• KDE Plasma — KDE Kiosk (kconfig files under /etc/xdg/, KCM module restrictions)

┌─────────────────────┐    gRPC stream / mTLS     ┌──────────────────────┐
│     Bor Agent       │ ◄────── port 8444 ────────► │     Bor Server       │
│  (Go daemon, root)  │                             │  Go + PatternFly UI  │
└─────────────────────┘    gRPC enrollment / TLS   └──────────┬───────────┘
  • One-time token enrollment ◄── port 8443 ──►               │ SQL
  • mTLS client certificate auth                               ▼
  • Applies Firefox / Chrome /               ┌──────────────────────────────┐
    KDE Kiosk policies                       │        PostgreSQL            │
  • Reports compliance                       │  policies · nodes · users    │
  • Desktop notifications                   │  bindings · RBAC · audit log │
                                             └──────────────────────────────┘

The server runs two HTTPS listeners with different security postures:

REST and enrollment gRPC share port 8443, routed by Content-Type: application/grpc* → gRPC handler, everything else → REST API + embedded PatternFly web UI.

• Centralised web UI — PatternFly 5 dashboard for policies, nodes, and bindings
• Real-time distribution — gRPC server-side streaming; agents receive changes instantly
• Secure by design — mTLS certificate authentication for every agent; internal CA auto-generated on first run; FIPS 140-3 validated crypto module
• Easy enrollment — one-time token generated in the UI; agent bootstraps its own certificate
• Automatic renewal — agent certificates (90-day) are renewed automatically before expiry; no operator action required
• Delta sync — monotonic revision counter with ring buffer; reconnecting agents receive only what changed
• Node Groups — many-to-many assignment of nodes to policy groups
• RBAC — built-in roles (Super Admin, Org Admin, Policy Editor, …) with granular per-resource permissions
• Audit log — every API action recorded with user, IP, and timestamp
• Tamper protection — file watcher detects and restores managed files that are modified outside Bor
• LDAP/AD integration — optional, enabled via environment variables
• HSM support — optional PKCS#11 integration stores the CA private key in a hardware security module
• Linux-native packaging — deb, rpm, apk, Arch Linux packages via nfpm

git clone https://github.com/VuteTech/Bor.git
cd Bor
cp .env.example .env
$EDITOR .env   # set DB_PASSWORD, JWT_SECRET, BOR_ADMIN_PASSWORD at minimum
podman-compose up -d

The server starts on https://localhost:8443 (UI + enrollment) and https://localhost:8444 (agent mTLS). On first boot it auto-generates an internal CA (ECDSA P-384) and a server TLS certificate (ECDSA P-256) under /var/lib/bor/pki/.

Log in at https://localhost:8443 with the admin credentials set in .env.

Download the appropriate package for your distribution from the releases page and install it:

# Debian / Ubuntu
sudo dpkg -i bor-agent_<version>_amd64.deb

# Fedora / RHEL
sudo rpm -i bor-agent-<version>.x86_64.rpm

# Arch Linux
sudo pacman -U bor-agent-<version>-x86_64.pkg.tar.zst

1. Edit /etc/bor/config.yaml (installed by the package):

   server:
     address: "your-server"
     enrollment_port: 8443
     policy_port: 8444
     insecure_skip_verify: true   # set false after deploying a trusted cert

2. Generate an enrollment token in the web UI (Node Groups page).

3. Enroll the agent:

   sudo bor-agent --token <ENROLLMENT_TOKEN>

   The agent generates an ECDSA P-256 key pair, sends a CSR to the server, and stores the signed certificate, private key, and CA cert in /var/lib/bor/agent/. After enrollment, start it as a service:

   sudo systemctl enable --now bor-agent

4. To re-enroll (e.g. after a CA rotation or to move a node to a different group), pass a new token — the old certificates are removed automatically before re-enrollment begins:

   sudo bor-agent --token <NEW_TOKEN>

All build targets are in the Makefile. Run make help to list them.

make install-deps

This installs protoc-gen-go, protoc-gen-go-grpc, golangci-lint, nfpm, and the TypeScript proto plugin via npm. You must have protoc and Node.js available separately.

All Go builds use GOFIPS140=v1.0.0, which embeds the FIPS 140-3 validated crypto module snapshot (CAVP certificate A6650) regardless of the host toolchain.

make server      # → server/server       (FIPS 140-3)
make agent       # → agent/bor-agent     (FIPS 140-3)
make frontend    # → embedded into the server binary (run before make server)
make proto       # regenerate Go + TypeScript from proto/ definitions

Build everything in the correct order:

make frontend && make server && make agent

To store the CA private key in a hardware security module, build with the pkcs11 tag. This requires CGO and the crypto11 dependency:

cd server && go get github.com/ThalesIgnite/crypto11
cd ..
make server-pkcs11   # → server/server  (FIPS 140-3 + PKCS#11)

See docs/SECURITY.md for the full configuration guide and a SoftHSMv2 example.

The build flag embeds the validated module. To additionally restrict the running process to FIPS-approved algorithms only (removes X25519, enforces P-256/P-384):

GODEBUG=fips140=on ./server/server

Add Environment=GODEBUG=fips140=on to the systemd unit override for production deployments.

# Start PostgreSQL
make dev

# Run the server (reads .env automatically via go run)
make run-server

# In a separate terminal — run the agent against the local server
sudo ./agent/bor-agent --config agent/config.yaml.example

Build distribution packages for all formats:

make packages                          # deb + rpm + apk + archlinux, version 0.1.0
make packages VERSION=1.2.3            # specify version
make packages VERSION=1.2.3 ARCH=arm64 # cross-arch
make packages-agent VERSION=1.2.3      # agent packages only
make packages-server VERSION=1.2.3     # server packages only

Packages are written to builds/. Requires nfpm (make install-deps).

make docker   # builds bor-server:latest with podman

make test            # all tests (server + agent)
make test-server     # server tests only
make test-agent      # agent tests only
make coverage        # HTML coverage reports → server/coverage.html, agent/coverage.html

Run a single test by name:

cd server && go test -v -run TestPolicyService ./internal/services/...
cd agent  && go test -v -run TestMergeKConfig  ./internal/policy/...

The server reads configuration from a YAML file (default /etc/bor/server.yaml, override with BOR_CONFIG) and environment variables. Environment variables always take precedence. Copy .env.example to .env for local development, or use /etc/bor/server.env for production (loaded by the systemd unit).

A full annotated YAML reference is in server/server.yaml.example.

If the CA and TLS variables are not set, the server auto-generates an internal CA (ECDSA P-384, 10 years) and a server TLS certificate (ECDSA P-256, 365 days) under /var/lib/bor/pki/ and reuses them on subsequent starts.

Requires the server-pkcs11 binary. The PIN must come from an environment variable — never store it in a YAML file.

The agent reads /etc/bor/config.yaml by default. Pass --config <path> to override. A full annotated reference is in agent/config.yaml.example.

server:
  address: "bor-server.example.com"
  enrollment_port: 8443   # UI + enrollment gRPC
  policy_port: 8444       # mTLS policy stream
  insecure_skip_verify: false   # true only for self-signed certs during setup

agent:
  client_id: ""   # defaults to system hostname

enrollment:
  data_dir: "/var/lib/bor/agent"   # cert, key, and CA cert stored here

firefox:
  policies_path: "/etc/firefox/policies/policies.json"
  flatpak_policies_path: "/var/lib/flatpak/extension/org.mozilla.firefox.systemconfig/x86_64/stable/policies/policies.json"

chrome:
  chrome_policies_path: "/etc/opt/chrome/policies/managed"
  chromium_policies_path: "/etc/chromium/policies/managed"
  chromium_browser_policies_path: "/etc/chromium-browser/policies/managed"
  flatpak_chromium_policies_path: ""   # set to enable Flatpak Chromium

kconfig:
  config_path: "/etc/xdg"   # KDE Kiosk overlay directory

• Security — cryptographic algorithms, FIPS 140-3 compliance, EU standards, deployment checklist, HSM integration
• Architecture — detailed design and data flows
• Contributing — setup, coding standards, PR process

Contributions are welcome via GitHub pull requests or by emailing patches to [email protected].

See docs/CONTRIBUTING.md for the full guide.

• Core policy management API and web UI
• Dual-port architecture (8443 UI/enrollment, 8444 agent mTLS)
• gRPC streaming with mTLS (TLS 1.3, mandatory client cert)
• Token-based agent enrollment (one-time, 5-minute TTL)
• Automatic certificate renewal (ECDSA P-256, 90-day lifetime)
• FIPS 140-3 validated builds (GOFIPS140=v1.0.0, CAVP A6650)
• PKCS#11 HSM support for CA private key (-tags pkcs11)
• Firefox ESR policy enforcement (RPM/DEB + Flatpak)
• Chrome / Chromium policy enforcement (including Flatpak)
• KDE Plasma KConfig (Kiosk) enforcement + KCM module restrictions
• Tamper protection (file watcher restores managed files)
• RBAC with roles and permissions
• Audit log
• Desktop notifications on policy change
• Many-to-many node group membership
• LDAP / Active Directory authentication
• deb / rpm / apk / Arch Linux packaging

• Persistent compliance reporting (database storage)
• Prometheus metrics endpoint
• AD / FreeIPA LDAP enrollment (Kerberos)
• Additional policy types: dconf, systemd units, firewalld, polkit, packages
• Agent auto-update mechanism
• Multi-tenancy

Copyright (C) 2026 Vute Tech LTD Copyright (C) 2026 Bor contributors

Licensed under the GNU Lesser General Public License v3.0.