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
dockergroup, 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
| To | When | What is sent |
|---|---|---|
| Docker Hub | The wizard | The words you search for and image names |
| Each image's registry | The 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.com | The wizard and an update's dry run | The repository an image names, for its README and release notes |
api.github.com | Setting up the config repo's capture | Whether its branch is protected. Anonymous, or with a token you type for that one request. |
| Trivy's databases | The daily image check | A download of the vulnerability databases, from the Trivy container |
| CrowdSec's apt repo | init | An apt download of the firewall bouncer |
| Your apt sources | init and host upgrade | apt downloads of the packages init installs and the upgrades host upgrade applies |
| Your config repo's Git remote | The config capture | The host's config, pushed by the config repo's own capture unit |
www.cloudflare.com | The facts timer, hourly | A download of Cloudflare's address ranges, for the origin row |
api.cloudflare.com | The facts timer every 6 hours, and proxy aop, only with a Cloudflare token | Reads 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.conf | The facts timer, hourly | DNS questions for the CAA and SOA of each name the proxy serves |
api.certspotter.com | The facts timer, daily | Each zone the proxy serves names in, for the certificates logged for it. Anonymous unless you add a Cert Spotter key. |
| Your backup destination | The data backup, daily | restic'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' registries | Building restic's image | restic'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.com | A restic version bump | restic's signing key by its pinned fingerprint, and the release's checksums and signature |
| CrowdSec's Central API | The CrowdSec container, as it sees attacks | Each alert's scenario, time, machine id and the attacking address. CrowdSec shares these by default. |
| CrowdSec's hub | The hub timer, daily | A 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.
| Secret | Where it lives | How it is handled |
|---|---|---|
| Portainer API token | portainer-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 token | npm-token in seawall's private state folder, 0600 | seawall 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 token | cloudflare-token in seawall's private state folder, 0600 | Pasted 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 keys | aop/ in seawall's private state folder, 0600 | Made 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 key | crowdsec-api-key beside seawall.toml, 0600 | The key of a CrowdSec bouncer seawall adds with cscli. Used to read bans through CrowdSec's API. Never printed. |
| Traefik's CrowdSec key | lapi/key in the Traefik folder, 0600 in a 0700 folder | Made by proxy bouncer with cscli, written by seawall's pinned helper image and mounted read-only in Traefik. |
| Traefik's certificates | certs/<name>.key and .crt in the Traefik folder, 0600 in a 0700 folder | NPM'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 lists | access/<id> in the Traefik folder, 0600 in a 0700 folder | NPM'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 folder | Made 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 key | backup-sftp-key beside seawall.toml, 0600, its public half beside it | Made by backup setup (ed25519) and used by restic's ssh, with the server's host key pinned in backup-sftp-known-hosts. |
| Capture marker key | backup/marker.key in seawall's private state folder, 0600 | 32 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 key | Typed at restore, or a file given to --age-key | Read to open the sealed env, then dropped. It is never written. |
| Cert Spotter key | certspotter-key beside seawall.toml, 0600 | Sent only to Cert Spotter, as a Bearer header. |
| Alert destinations' URLs and tokens | The seawall-notify volume, 0400 to Grafana's user | Written from stdin and read by Grafana as files. Never in an env or a log. |
| Grafana token | grafana-token beside seawall.toml, 0600 | A 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 login | The grafana container's env | Used only where no token file exists, and sent only as a Basic auth header. |
| Config repo deploy key | cloud-deploy-key beside seawall.toml, 0600, its public half beside it | Pushes each commit cloud capture makes to the config repo, over SSH, with GitHub's host keys pinned. |
| Stack env in the config repo | The config repo | Sealed with age to your public key. The private key never sits on the host. |
| Branch-check token | Typed at a prompt and never stored | Sent in one header to GitHub's API, to check the config repo's branch protection. |
| Stack secrets | Portainer's stack env, or a Compose stack's 0600 .env | Sent back unchanged on every deploy. stack migrate keeps a 0600 backup of the env it moves. stack secrets shows names only. |
| Portainer's admin password | Typed during init, or SEAWALL_PORTAINER_PASSWORD | Used once and never stored. |
| NPM user password | Typed for proxy login, or SEAWALL_NPM_PASSWORD | Used to make the NPM user and log in once, then dropped. |
| CrowdSec bouncer key | The stack's env, and a root-owned 0600 .yaml.local | Random, 24 bytes from /dev/urandom. |
| Database credentials | Each database container's env | Dumps 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 folders | A 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 dumps | backup 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 password | backup-password beside seawall.toml, 0600 | Shown once at setup. Reaches restic as a read-only file. Never in an argument. |
| Rootless owner's backup password | backup-password.<owner> beside seawall.toml, 0600, and ~<owner>/.config/seawall-backup/password, 0600 | Made 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 secret | backup-s3-credentials beside seawall.toml, 0600 | Taken from the environment variables you name. Mounted read-only for restic. Never in an argument, a run's environment or a log. |
| Certificate keys | Pasted 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 host | Read 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.lockis committed and builds use--locked.cargo denychecks bans, licences and sources on every dependency change, and advisories on the release track. Three advisories are accepted indeny.tomlwith reasons, to review by 2026-12-01. Only crates.io is allowed.- GitHub Actions builds release binaries with
cargo build --release --lockedand publishesSHA256SUMSandBUILD.txtin the same release. Nothing is signed, and CI runs a smoke run and nocargo deny, Clippy or tests. The checksum shows the download matches the release. - Every image
initstarts is pinned to a version. It is pinned by digest too when its registry answers. The Trivy image pin moves only aftercosign verifyshows 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
opensslprogram makes the AOP keys and reads certificates, with arguments only.
Reviews
| Date | Scope | Result |
|---|---|---|
| 2026-10-04 | Deploys, Portainer, Grafana, the allowlist and sudo paths | No high findings. Two medium and six low fixed. |
| 2026-10-04 | The command centre | Ten findings fixed. |
| 2026-10-04 | Databases, CrowdSec, host, secrets, the proxy and the timers | Four medium and twelve low fixed. |
| 2026-10-06 | Fresh-host init and stack move | Seven findings fixed. |
| 2026-10-07 | The code against an outside assessment of a host | Four gaps listed and fixed in turn. |
| 2026-10-12 | cloud cover | One medium fixed. Cover could have committed /etc/shadow. |
| 2026-10-12 | The Security tab, three reviews | A 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-12 | The stray listener alert | Accept is offered only for a one-word process name. |
| 2026-10-18 | Alert actions, sudo's settings, root units and root-only files | No 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-18 | Changes made outside a login session, the auditd row and cf-only | No 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-19 | Update plans, To do actions, checks after a reboot and the command centre's own facts run | Five low fixed, one low open. |
| 2026-10-19 | The account change alert and root's own count | Two 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-20 | Stopped stacks in harden and limits, the command centre's Docker reads and the site's security pages | Fifteen 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 inseawall 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.
initadds nothing to theDOCKER-USERchain. Publish only what should be public. - The monitoring stack's cAdvisor mounts
/var/runread-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.dbin 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--installand the live graphs have not had a full security review yet. - The config capture seals only the lines of a Compose stack's
.envthat seawall reads:NAME=value, the value plain or in single quotes. It lists each other line inNOT-CAPTURED.mdby 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.