usulnet

usulnet

Self-hosted Docker management plane with built-in privacy tooling. Single Go binary, AGPL-3.0, one build — every feature in this repo ships in the standard binary, no edition gating, no call-home.

usulnet runs container lifecycle, security scanning, backups, reverse-proxy configuration, monitoring, multi-node orchestration, host infrastructure tooling (firewall, crontab, WireGuard mesh, docker-engine config, image builder), and an opt-in privacy module (OSINT recon plus file metadata hygiene) from a single process on hardware you own.

v26.5.2 Beta — released 2026-05-19. Bug reports: issues. Release notes: CHANGELOG.md and docs/v26.5.2/release-notes.md (v26.5.1 archive: docs/v26.5/release-notes-v26.5.1.md).

Quick start

curl -fsSL https://raw.githubusercontent.com/fr4nsys/usulnet/main/deploy/install.sh | sudo bash

The installer pulls the production compose file, generates the database password, JWT secret, AES-256 data-encryption key, and a self-signed TLS cert. It prints the access URL when ready.

Open https://<host>:7443, log in as admin / usulnet, then change the password from the profile page.

Manual Docker Compose install, standalone binary install, and offline procedures live in docs/installation.md.

What's new in v26.5.2

Polish release on top of v26.5.1. No database migration. Adds the Shodan recon connector to the AGPL binary (second BYO-key external connector after HIBP), ports usulnet-agent to Cobra with run / version / validate-config subcommands and a canonical USULNET_AGENT_DOCKER_HOST env var, lands global CLI --quiet / --json flags with a JSON error envelope, adds migrate up / down [N] / status subcommands, ships header / sidebar / modal / flash a11y landmarks across the web chrome, bakes shell tab-completion into both production Docker images, and publishes a new operator CLI reference at docs/cli.md. Per-feature detail in docs/v26.5.2/release-notes.md; full per-PR changelog in [v26.5.2] of CHANGELOG.md.

What's in v26.5.1

Eleven modules previously gated behind the Business edition now ship in the standard AGPL build, plus a proxy-extended enhancement and the opt-in local-services TLS dispatcher. Per-feature detail in docs/v26.5/release-notes-v26.5.1.md; full per-migration audit in [v26.5.1] of CHANGELOG.md.

Also in v26.5.1: the docker-engine config editor (atomic daemon.json writes with snapshot history and reload-with-rollback — no migration), the sidebar edition cleanup (all isEditionAvailable / RequireFeature / limitProvider callsites removed; license.CELimits() collapsed into license.OpenLimits()), the bootstrap restructure (the 2,700-line startStandalone split into phased init_*.go files), and opt-in local-services TLS via USULNET_TLS_LOCAL_SERVICES=true for in-cluster Postgres / Redis / NATS.

Features

Docker control plane

Host & infrastructure tooling

Capability requirements

The modules in the previous table reach the host through the existing host-management transport or a bind mount. Capability requirements:

All other v26.5.1 modules (crontab, ssl-observatory, calendar, marketplace, rollback, proxy-extended) need nothing beyond the default compose stack. Full detail in docs/installation.md.

Privacy and recon (opt-in)

Off by default — every recon route returns 404 until an admin sets USULNET_RECON_ENABLED=true and records the legal-notice acknowledgement (POST /api/v1/recon/_ack). Full design and threat model in docs/recon.md; signed review at docs/v26.5/security-review-checklist.md.

Auth, RBAC, platform

Developer tools

Web-based terminal hub (xterm.js) with container exec and host SSH. Monaco editor and Neovim with lazy.nvim for in-browser file editing. Filesystem browsers for containers, hosts, and SFTP. Snippets and cheat sheets. Outgoing webhooks on container events with retry. Auto-deploy rules triggered by Git push. Runbooks for multi-step operations. Cron-scheduled jobs for backups, scans, metrics, update checks, recon retention, and cleanup.

Architecture

usulnet ships as a single binary that runs in one of three modes:

• standalone — one Docker host, all services local. NATS not required.
• master — standalone plus a NATS gateway server for remote agents.
• agent — connects to a master via NATS. No web UI; executes Docker operations against its local host.

PostgreSQL stores domain state across 56 migrations (users, RBAC, connections, backups, scans, alerts, recon, audit log, plus the v26.5.1 ported modules: calendar, proxy-extended, DNS, crontab, firewall, SSL observatory, backup verification, image builder, automated rollback, WireGuard, marketplace). Redis backs session storage and JWT blacklisting. NATS with JetStream carries inter-node traffic with persistence. Full component diagram, request flow, and topology in docs/architecture.md.

Multi-node setup

# On the control plane host
export USULNET_MODE=master AGENT_TOKEN=<secure-token>
docker compose up -d

# On each remote host you want to manage
docker run -d --name usulnet-agent --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  usulnet/usulnet-agent:latest \
  --gateway nats://<master-ip>:4222 \
  --token <secure-token>

Master ↔ agent traffic flows over NATS with mTLS on the usulnet-backend Docker network. Full agent protocol, NATS subject map, and TLS provisioning at docs/agents.md.

Stack

Configuration

config.yaml plus environment variables prefixed USULNET_ (nested keys joined by _). The Viper loader treats environment overrides as canonical.

USULNET_SERVER_PORT=9090
USULNET_DATABASE_URL=postgres://usulnet:secret@db/usulnet?sslmode=disable
USULNET_SECURITY_JWT_SECRET=<64-hex>
USULNET_ENCRYPTION_KEY=<64-hex>
USULNET_RECON_ENABLED=true
USULNET_MODE=standalone

# Opt-in TLS for in-cluster Postgres / Redis / NATS (v26.5.1)
USULNET_TLS_LOCAL_SERVICES=true

# Module knobs
USULNET_IMAGE_BUILDER_MAX_CONTEXT_BYTES=268435456   # 256 MiB
USULNET_SSL_OBSERVATORY_PER_TARGET_CONCURRENCY=4

Full reference, defaults, and the production compose template are in docs/installation.md.

CLI

usulnet serve              # run the server
usulnet migrate up         # apply pending migrations
usulnet migrate status     # show migration state
usulnet migrate down [N]   # roll back N migrations (default 1)
usulnet config check       # validate configuration
usulnet config show        # display config with secrets masked
usulnet admin reset-password   # reset the admin password
usulnet recon …            # opt-in recon subcommand tree
usulnet meta …             # opt-in metadata hygiene subcommand tree
usulnet version            # print build info

Global flags affect every subcommand: --quiet suppresses informational summaries (errors and primary data still print); --json is a shortcut for --output json and also switches the error formatter to a single-record envelope on stderr — {"error":"<string>","code":<int>}. Plain errors carry a fixed usulnet: prefix. Exit codes (0 success, 64 usage, 70 infra, 71 server unreachable, 72 auth) are stable across the binary. Full reference: docs/cli.md.

The agent binary (usulnet-agent) ships as a Cobra tree with run, version, and validate-config subcommands. Validate a config before restarting an agent:

usulnet-agent validate-config --config /etc/usulnet-agent/config.yaml

Full agent reference: docs/agents.md.

API examples

REST under /api/v1, authenticated with X-API-KEY or Authorization: Bearer <jwt>. Full OpenAPI at /api/v1/openapi.json, Swagger UI at /docs/api. Reference: docs/api.md.

# List running containers
curl -fsSL -H "X-API-KEY: $USULNET_API_KEY" \
  https://usulnet.example.com:7443/api/v1/containers?status=running | jq

# Browse the embedded marketplace catalog
curl -fsSL -H "X-API-KEY: $USULNET_API_KEY" \
  https://usulnet.example.com:7443/api/v1/marketplace/apps | jq '.[].slug'

# Trigger an SSL observatory scan against every enabled target
curl -fsSL -X POST -H "X-API-KEY: $USULNET_API_KEY" \
  https://usulnet.example.com:7443/api/v1/ssl/scan

# Apply a firewall rule on a host through the agent transport
curl -fsSL -X POST -H "X-API-KEY: $USULNET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"host_id":"<uuid>","chain":"INPUT","action":"ACCEPT","protocol":"tcp","port":22,"comment":"ssh"}' \
  https://usulnet.example.com:7443/api/v1/firewall/rules

# Start a backup verification run
curl -fsSL -X POST -H "X-API-KEY: $USULNET_API_KEY" \
  https://usulnet.example.com:7443/api/v1/backup-verify/runs \
  -d '{"backup_id":"<uuid>","method":"extract"}'

WebSocket endpoints for live container logs / exec / stats / image build output / crontab execution tail follow the same path scheme with the Upgrade: websocket header.

Documentation

Development

git clone https://github.com/fr4nsys/usulnet.git
cd usulnet
make dev-up      # postgres, redis, nats, minio
make build       # templ generate + tailwind compile + go build
make run

make quality runs the full gate: golangci-lint, go vet, scripts/check-naming.sh, and the coverage threshold check (15 % interim, 40 % target). make publish-public produces the curated public-mirror tree under build/public/ for the release workflow. The full developer guide — workflow, hooks, profiling, debugging — is in docs/development.md.

Commits follow Conventional Commits.

License

AGPL-3.0-or-later. Self-hosted use is free in perpetuity. One AGPL build, all features — no edition gating, no closed-source extension point, no feature gated by a paid license tier. Optional commercial support contracts are documented in docs/licensing.md; they do not unlock additional runtime features.

Security

Report vulnerabilities to security@usulnet.com. Do not open public issues for security findings.

Security posture:

• External port surface: only HTTPS (7443) is published by default. HTTP (8080) and NATS (4222) stay internal to the usulnet-backend Docker network.
• No call-home. No outbound request to any usulnet-controlled endpoint at runtime. Every outbound call (registry, DNS provider, OAuth issuer, HIBP) is operator-configured.
• Container user usulnet:1000 (non-root). Recon sandbox runs as nobody:nogroup (65534) with read-only rootfs and all Linux capabilities dropped.
• AES-256-GCM at rest for every sensitive value (passwords are bcrypt; WireGuard keys, DNS provider credentials, HIBP keys, raw recon payloads, JWT signing keys, OAuth client secrets).
• govulncheck in CI on every push and PR. v26.5.1 dependency baseline covers Go 1.25.10, pgx 5.9.2, NATS 1.52.0, go-redis 9.19.0, go-chi 5.2.5, jwt 5.3.1, go-oidc 3.18.0, go-ldap 3.4.13, docker 28.5.2; two Moby false positives (GO-2026-4883, GO-2026-4887) are in the allowlist with inline justification.

Full hardening audits: docs/v26.5/security-review-v26.5.2.md (current — covers v26.5.2 deltas: Shodan connector, agent Cobra port, CLI tab-completion install script, web a11y landmarks, JSON error envelope, route-scoped frontend gzip with BREACH mitigation, batched alert event resolution, request-id strconv swap) and docs/v26.5/security-review-v26.5.1.md (baseline — eleven v26.2.7 modules ported into the AGPL build).