Security

What seawall guards against, the principles and practices it follows, and the limits it has.

Trust model

  • It catches mistakes, seawall run from somewhere you didn't expect (a cron job, an agent), a container that misbehaves and attacks from outside the host.
  • It can't stop anything running as your account or as root. Your account is in the docker group, which is as good as root, and with passwordless sudo it is root.
  • Its checks read root's own files, what your account can read, or the audit log in Loki. The checks page names each row's source. None of them holds against your account.

Principles

A command that changes something prints its plan and changes nothing without --yes. Some act at once, with no --yes, among them grafana reload, cloud capture, proxy login and proxy aop renew. How commands work lists every one. On a terminal init and the wizard show their plan and ask before they act. The command centre reruns a command with --yes only after you press y. It does so only when the dry run succeeded. The rerun plans again, so it acts on the host as it is when you press y.

seawall runs as your account. That account is in the docker group, which is as good as root. So seawall is not a privilege boundary. It adds dry runs, checks and a record of each change.

Root is used through sudo for named steps, and by the root units init installs. See Root and sudo. sudo asks for your password itself. seawall writes no sudoers rules and never works around sudo.

Secrets are never logged. They are stored in 0600 files, in Portainer, or in the containers that own them. Commands show names only. The one secret printed is the data backup password seawall makes, shown once at setup.

Input is untrusted. Every subprocess gets an argument vector. Where a shell runs, in a container or a root unit, its script is fixed text. Values reach it as arguments, or are checked against a strict pattern before they are written into a unit. Values are checked before they reach a command. Escape sequences and control characters are removed before text reaches the terminal.

A check fails closed. A source seawall can't read is shown as information and never as a pass.

Every change seawall makes is recorded in the journal with where it ran from, an SSH client's address included. Loki keeps the journal 30 days. One from outside a login, a tmux pane of one or seawall's timers raises an alert. Where it ran from is where the journal placed it, never what its line says. An account change seawall can't tie to its own line in that login session pages at once.

The calls seawall makes are listed below, with those of the stacks init starts. seawall sends no telemetry and checks for no updates to itself. The seawall.sh site is served through Cloudflare.

What leaves the host

ToWhenWhat is sent
Docker HubThe wizardThe words you search for and image names
Each image's registryThe wizard, the daily image check, stack update, init, status and the dashboard for an image alert's tag (its digest, cached 5 minutes), and seawall optimise and the Host tab's Optimise box for whether a large image in use has an -alpine or -slim tag (a digest each; the TUI keeps the answer a day)Image names, for tags, digests and image configs. Docker pulls the images from there too.
api.github.comThe wizard and an update's dry runThe repository an image names, for its README and release notes
api.github.comSetting up the config repo's captureWhether its branch is protected. Anonymous, or with a token you type for that one request.
Trivy's databasesThe daily image checkA download of the vulnerability databases, from the Trivy container
CrowdSec's apt repoinitAn apt download of the firewall bouncer
Your apt sourcesinit and host upgradeapt downloads of the packages init installs and the upgrades host upgrade applies
Your config repo's Git remoteThe config captureThe host's config, pushed by the config repo's own capture unit
www.cloudflare.comThe facts timer, hourlyA download of Cloudflare's address ranges, for the origin row
api.cloudflare.comThe facts timer every 6 hours, and proxy aop, only with a Cloudflare tokenReads of each zone's SSL settings. With proxy aop, the client certificate seawall makes for the site, its private key and the hostnames it covers, as Cloudflare's Authenticated Origin Pulls needs.
The resolvers in /etc/resolv.confThe facts timer, hourlyDNS questions for the CAA and SOA of each name the proxy serves
api.certspotter.comThe facts timer, dailyEach zone the proxy serves names in, for the certificates logged for it. Anonymous unless you add a Cert Spotter key.
Your backup destinationThe data backup, dailyrestic's repository, which restic encrypts before it leaves. An S3 bucket over HTTPS or an SFTP server over SSH.
github.com, snapshot.debian.org, go.dev and dl.google.com (Go), proxy.golang.org and sum.golang.org (Go's modules) and the base images' registriesBuilding restic's imagerestic's source and Go's release, each checked against a pinned sha256; restic's modules, checked against its go.sum and Go's checksum database; OpenSSH's client by its pinned sha256. The build itself has no network, and the binary it makes is checked against a pinned sha256
keyserver.ubuntu.com and github.comA restic version bumprestic's signing key by its pinned fingerprint, and the release's checksums and signature
CrowdSec's Central APIThe CrowdSec container, as it sees attacksEach alert's scenario, time, machine id and the attacking address. CrowdSec shares these by default.
CrowdSec's hubThe hub timer, dailyA download of the hub's parsers and scenarios

All of it is HTTPS but three. DNS goes to the host's resolvers, the config repo and an SFTP destination are reached over SSH, and Debian's snapshot archive is plain HTTP, where apt checks each file against an index whose sha256 seawall pins. Registry and GitHub requests are anonymous, except the config repo's branch check when you type a token for it. Grafana sends alerts to the destinations you set. Each notification links its alert's page on seawall.sh by the alert's name alone, so opening it is a visit to seawall.sh. notifications.doc_links = false leaves the link out. A download from GitHub follows up to three redirects, so an outbound allowlist needs GitHub's redirect hosts too. Answers are capped in size and checked before use. For a config repo seawall made, cloud capture commits and pushes it over SSH to GitHub with its deploy key alone and GitHub's host keys pinned, and never force-pushes. A privatecloud repo is pushed by its own capture unit. stack new and cloud sync commit the config repo's capture/manifest.json locally and start the capture.

Secrets

"Beside seawall.toml" is the config folder, ~/.config/seawall. The private state folder is ~/.local/state/seawall, 0700.

SecretWhere it livesHow it is handled
Portainer API tokenportainer-token beside seawall.toml, 0600 (or ~/.config/portainer/api-token where a host has only that one, or the file portainer.token names)Sent only as the X-API-Key header. seawall doctor checks the file mode.
NPM user tokennpm-token in seawall's private state folder, 0600seawall acts in NPM as its own non-admin user. Its password is used once and never stored. Each refresh rechecks the user's rights, and a user given wider rights loses its token.
Cloudflare API tokencloudflare-token in seawall's private state folder, 0600Pasted once at a hidden prompt, or taken from SEAWALL_CLOUDFLARE_TOKEN off a terminal, and sent only to Cloudflare's API. It needs SSL and Certificates edit, and read of zones, zone settings and Configuration Rules, for Authenticated Origin Pulls. The link proxy aop login prints starts with all zones, so narrow them in Cloudflare's form. Revoke it in Cloudflare.
Authenticated Origin Pulls keysaop/ in seawall's private state folder, 0600Made by proxy aop. The client certificate and key go to Cloudflare, which presents the certificate to the site. The CA key never leaves the host.
CrowdSec API keycrowdsec-api-key beside seawall.toml, 0600The key of a CrowdSec bouncer seawall adds with cscli. Used to read bans through CrowdSec's API. Never printed.
Traefik's CrowdSec keylapi/key in the Traefik folder, 0600 in a 0700 folderMade by proxy bouncer with cscli, written by seawall's pinned helper image and mounted read-only in Traefik.
Traefik's certificatescerts/<name>.key and .crt in the Traefik folder, 0600 in a 0700 folderNPM's certificates and their private keys, copied out of NPM's data by proxy migrate --to traefik in seawall's pinned helper image and mounted read-only in Traefik. proxy migrate --certs removes a host's copy when Traefik holds a Let's Encrypt certificate for it.
Traefik's access listsaccess/<id> in the Traefik folder, 0600 in a 0700 folderNPM's htpasswd files, copied by the same helper for each list that has users and mounted read-only in Traefik.
NPM database copy~/backups/npm/<UTC>-database.sqlite and <UTC>-seawall.toml, 0600 in a 0700 folderMade by proxy migrate --to traefik before it changes anything. The .sqlite file is NPM's whole database, password hashes included. It is opened again to count its proxy hosts.
SFTP keybackup-sftp-key beside seawall.toml, 0600, its public half beside itMade by backup setup (ed25519) and used by restic's ssh, with the server's host key pinned in backup-sftp-known-hosts.
Capture marker keybackup/marker.key in seawall's private state folder, 060032 random bytes made once. They key the HMAC that shows whether a stack's secrets changed since the last capture, so the config repo holds no plain hash of them.
age secret keyTyped at restore, or a file given to --age-keyRead to open the sealed env, then dropped. It is never written.
Cert Spotter keycertspotter-key beside seawall.toml, 0600Sent only to Cert Spotter, as a Bearer header.
Alert destinations' URLs and tokensThe seawall-notify volume, 0400 to Grafana's userWritten from stdin and read by Grafana as files. Never in an env or a log.
Grafana tokengrafana-token beside seawall.toml, 0600A service account (seawall, Editor) init mints with the admin login once. Sent only as a Bearer header. A bad file is an error, never a fallback.
Grafana admin loginThe grafana container's envUsed only where no token file exists, and sent only as a Basic auth header.
Config repo deploy keycloud-deploy-key beside seawall.toml, 0600, its public half beside itPushes each commit cloud capture makes to the config repo, over SSH, with GitHub's host keys pinned.
Stack env in the config repoThe config repoSealed with age to your public key. The private key never sits on the host.
Branch-check tokenTyped at a prompt and never storedSent in one header to GitHub's API, to check the config repo's branch protection.
Stack secretsPortainer's stack env, or a Compose stack's 0600 .envSent back unchanged on every deploy. stack migrate keeps a 0600 backup of the env it moves. stack secrets shows names only.
Portainer's admin passwordTyped during init, or SEAWALL_PORTAINER_PASSWORDUsed once and never stored.
NPM user passwordTyped for proxy login, or SEAWALL_NPM_PASSWORDUsed to make the NPM user and log in once, then dropped.
CrowdSec bouncer keyThe stack's env, and a root-owned 0600 .yaml.localRandom, 24 bytes from /dev/urandom.
Database credentialsEach database container's envDumps run inside the container. The password never reaches an argument.
Database dumps~/backups/<stack>/0600 files in 0700 folders.
Copies of a stack's files~/backups/<stack>/ (<UTC>-<what>, current.yml, volumes/), ~/backups/strays/ and stage/ in seawall's private state folder, 0600 in 0700 foldersA command that rewrites a compose file or env keeps the old file first. stack remove keeps a tar of each volume, stray rm a tar of the folder it trashes, and a root install is staged and removed after. The copies hold what their stack or folder holds, secrets included. A run's scratch .env is 0600 and removed when the run ends.
Copies a restore keeps<folder>.before-restore-<stamp> beside a restored folder, the volume <v>-before-restore-<stamp>, and ~/backups/restored-<stamp> for dumpsbackup restore keeps what was there, and restores dumps into a new folder. The copies keep their modes and hold what the stack holds, secrets included. volumes clean-aside removes the volume copies.
Data backup passwordbackup-password beside seawall.toml, 0600Shown once at setup. Reaches restic as a read-only file. Never in an argument.
Rootless owner's backup passwordbackup-password.<owner> beside seawall.toml, 0600, and ~<owner>/.config/seawall-backup/password, 0600Made and shown once at backup setup, or taken from the variable --owner-password-env names. The owner's copy is made as the owner, through a 0400 file in /run that is removed after. Reaches restic as a read-only file.
S3 key and secretbackup-s3-credentials beside seawall.toml, 0600Taken from the environment variables you name. Mounted read-only for restic. Never in an argument, a run's environment or a log.
Certificate keysPasted into proxy certs install, or a file given to it. Its copies are seawall-certs/<base>.key in Traefik's file-provider folder and certs/<base>.key in a folder Caddy mounts from the hostRead with echo off. Never printed, logged or recorded. The Traefik and Caddy copies are 0600 files in 0700 folders.

Config capture never adds a file that may hold a secret.

An env name that would steer Compose, Docker, git, the loader or a proxy is refused where seawall carries a stack's env across, such as COMPOSE_FILE, DOCKER_HOST or LD_PRELOAD. So is a name that isn't plain letters, digits and _. stack migrate, container adopt and the rootless move's plan refuse such a name before they write anything. The plan hands Compose the stack's env in a private file holding only the names its compose file reads, removed when the run ends.

Root and sudo

See Root and sudo for each step that uses root and the units that run with a root step.

Stack hardening

Lint checks each compose file against a hardening baseline. It covers no-new-privileges, cap_drop: [ALL], memory and process limits, the Docker socket, privileged mode, host mounts and root. A deploy refuses new lint errors. Every stack init starts passes the baseline, with its few exceptions written in the file. See Hardening.

What the proxy may reach

A container that is root on the host is never routed through the proxy as it is. That covers Portainer, one that mounts the Docker socket or can reach a socket proxy that lets writes through, and one that runs privileged, in the host's PID namespace, with broad capabilities or with a bind mount of a system folder. Such a route needs an access list, at most one public /16 or /48 without a typed confirm, and seawall reads back what nginx serves before the host goes live. A route it can't guard is left disabled. Portainer's route comes only from portainer.url and portainer.allow, and the Security tab names any enabled host that leads to Portainer without that list.

How seawall is built

  • Unsafe Rust is forbidden. Clippy runs at the pedantic level with warnings as errors.
  • Cargo.lock is committed and builds use --locked. cargo deny checks bans, licences and sources on every dependency change, and advisories on the release track. Three advisories are accepted in deny.toml with reasons, to review by 2026-12-01. Only crates.io is allowed.
  • GitHub Actions builds release binaries with cargo build --release --locked and publishes SHA256SUMS and BUILD.txt in the same release. Nothing is signed, and CI runs a smoke run and no cargo deny, Clippy or tests. The checksum shows the download matches the release.
  • Every image init starts is pinned to a version. It is pinned by digest too when its registry answers. The Trivy image pin moves only after cosign verify shows Trivy's own release workflow signed it.
  • Trivy runs in a container as nobody, read-only, without capabilities and without the Docker socket. It sees its database volume and the one image it scans, which is a saved file or the image fetched from its registry.
  • A new dependency is checked for its repository, publisher and downloads before it is added.
  • TLS is rustls, checked against the system's CA store. OpenSSL is never linked. The host's openssl program makes the AOP keys and reads certificates, with arguments only.

Reviews

DateScopeResult
2026-10-04Deploys, Portainer, Grafana, the allowlist and sudo pathsNo high findings. Two medium and six low fixed.
2026-10-04The command centreTen findings fixed.
2026-10-04Databases, CrowdSec, host, secrets, the proxy and the timersFour medium and twelve low fixed.
2026-10-06Fresh-host init and stack moveSeven findings fixed.
2026-10-07The code against an outside assessment of a hostFour gaps listed and fixed in turn.
2026-10-12cloud coverOne medium fixed. Cover could have committed /etc/shadow.
2026-10-12The Security tab, three reviewsA process name could inject arguments. Unreadable sources showed as passes. A key could act on a row the cursor jumped to. All fixed.
2026-10-12The stray listener alertAccept is offered only for a one-word process name.
2026-10-18Alert actions, sudo's settings, root units and root-only filesNo high findings. Three medium and eight low fixed. A fix built from an alert's labels could undo the wrong setting, and a port fix wrote during its dry run.
2026-10-18Changes made outside a login session, the auditd row and cf-onlyNo high findings. Three medium and one low fixed, one low open. An accept could be forged from a cron job, and an alert ended when its collector stopped.
2026-10-19Update plans, To do actions, checks after a reboot and the command centre's own facts runFive low fixed, one low open.
2026-10-19The account change alert and root's own countTwo medium and one low fixed. Forged journal lines on a test VM were refused, and the sev0 alert fired. Two medium and one low found, open.
2026-10-20Stopped stacks in harden and limits, the command centre's Docker reads and the site's security pagesFifteen corrections to the pages. Three low open.

Known limits

  • With passwordless sudo the sudo checks are guard rails, and the account can still reach root. seawall says so in init's plan and in seawall posture.
  • Tagging each change with where it came from catches unexpected runs. It doesn't stop someone who already controls the account. A change counts as yours where it runs in one of your logins, or a tmux pane of one, that root recorded. Root records logins once a minute, so changes from a shorter login count. A process of your account that holds your SSH key, or drives the tmux server of one of your logins, can count as you.
  • An account change within 20 minutes of any package install or upgrade is reported with the upgrade at sev3 and never paged.
  • Ports Docker publishes go around ufw. init adds nothing to the DOCKER-USER chain. Publish only what should be public.
  • The monitoring stack's cAdvisor mounts /var/run read-only. Through it cAdvisor can still call the Docker API.
  • The Trivy container reaches the internet and the host's published ports.
  • Restore tests compare schemas and table counts only.
  • The command centre has the same rights as the command line. It is as safe as the session it runs in.
  • The command centre shows a fix seawall made at once from its own record, state.db in its private state folder. A process of your account can write that record and make an update's row read as done for up to 30 minutes. It never hides an alert or a security row.
  • The Compose engine, stack migrate, proxy certs install, shell completion's --install and the live graphs have not had a full security review yet.
  • The config capture seals only the lines of a Compose stack's .env that seawall reads: NAME=value, the value plain or in single quotes. It lists each other line in NOT-CAPTURED.md by line number and name, and refuses the whole capture when a file it would commit holds that line's value, where the value is 8 characters or more. A line seawall can't read leaves the stack out.

Reporting a vulnerability

Email a report. Reports stay private until fixed. Include the command, what you expected and what happened. Describe any secrets, tokens and dumps.

mail security at seawall dot sh

The repository isn't public yet. Once it is, its GitHub private vulnerability reporting (Security, then Report a vulnerability) works too.