Security
The agent drives Docker, and whoever drives Docker is root on the server. Since 1.1 the agent reaches the daemon through a socket proxy that passes the calls it makes and refuses every other, but a request to create a container passes, so an admin token is root on the server all the same. This page describes the trust model that follows from that, how to expose the API safely and who can reach it, what Shipwick does and does not do — tokens and roles, signing in through a provider, the audit trail, what is encrypted at rest and how the key is rotated, backups and exports, what the proxy sees and logs, what a container goes without, how a release is verified — and how to report a vulnerability.
Trust model
Driving Docker is root. Whoever can ask the daemon for a container can ask for one that mounts /, and the agent's work is asking the daemon for containers. In the default installation, since 1.1, it does so through a socket proxy that passes the calls it makes and refuses every other, never through the socket itself — The Docker socket says what that stops and what it does not. A request to create a container passes, so:
- An
admintoken is equivalent to root SSH access to the server. Treat it so. The token the installer prints is one. - Shipwick is not a multi-tenant sandbox. Whoever can submit a
deploy.yamlto the agent, which anydeploytoken can, can run arbitrary images on the server, with any command, as any user inside the container. - Roles limit what a token may ask the API for, not what the server trusts.
readsees everything, environment values masked and secrets by name only;deploychanges what runs, and sends images and static folders;adminalso deletes applications, manages tokens, secrets, registry credentials and certificates, rotates the encryption key, downloads, restores or removes backups and volumes, and exports and imports the server, reads the audit trail and manages who may sign in. Since 0.6 adeploytoken can be limited to the applications it names; that narrows what a leaked token can be used for, and it is not a wall between tenants: a limited token still reads every application's logs and configuration. - The same holds for anyone with access to the Docker socket — the filtered one the agent holds included, since a request to create a container passes it — the agent's data directory or Caddy's admin socket.
- Whoever holds the backup passphrase and the bucket holds everything: every application's data, and the agent's database together with the key to it. See Backups and exports.
The socket proxy is the default, since 1.1. In every installation the installer sets up, a fourth container, socket-proxy, holds /var/run/docker.sock and answers the agent the calls on its list — a method and a path each — with 403 for every other; the agent reaches Docker through a filtered socket the two share and has no other way to it. Before 1.1 the agent held the socket itself, and the proxy was an overlay to put in by hand. What the proxy stops is a fault in the agent reaching the rest of the Engine API, and every bind mount. What it does not stop is whoever holds an admin token: the proxy reads a request's path and its bind mounts, not the rest of its body, so a privileged container can still be created through it, and that is root on the server.
Two arrangements hold where the proxy does not. Docker's authorization plugin with a policy of the repository's, since 0.9, sees the whole request and refuses, for every client of the daemon, what makes a container root on the server; it composes with the proxy. Rootless Docker makes the daemon and everything it starts an ordinary user of the server. The installer sets up neither. The other way, compose.direct-socket.yml, gives the agent the socket itself for the few servers that want it, and an agent installed from a package holds it by design; the agent says which it has, in GET /server, shipwick server status and shipwick doctor. See The Docker socket.
Exposing the API
The API speaks plain HTTP and binds to 127.0.0.1:9000 by default. There are three ways to reach it from elsewhere:
| Method | How |
|---|---|
| HTTPS through Caddy | Set SHIPWICK_AGENT_DOMAIN. The API is served at that hostname with an automatically obtained certificate. |
| SSH tunnel | Keep the API on the server's loopback and run ssh -L 9000:127.0.0.1:9000 user@server. See Reach the API without a hostname. |
| Private network | WireGuard, Tailscale or similar. |
Never expose port 9000 directly to the internet
The token would cross the network in clear text, and an admin token is root on the server. The production compose file publishes no port for the agent on purpose.
On the server, open ports 80 and 443 and nothing else, plus whatever publish deliberately binds; see Unprivileged containers for why the firewall alone does not decide that.
Caddy's admin API is as sensitive as the agent's. Whoever reaches it controls all routing and the certificate store. Shipwick talks to it over a unix socket in a volume shared by the agent and Caddy only. Do not move it to a TCP port on the application network: every application container could then reconfigure the proxy.
The dashboard should be served over HTTPS too, which SHIPWICK_DASHBOARD_DOMAIN does. Signing in sends the token to the dashboard's server; over plain HTTP on anything but loopback that is a root credential in clear text. Since 0.10 the API's and the dashboard's hostnames answer with Strict-Transport-Security: max-age=31536000, so a browser that has seen them once does not ask over plain HTTP first; an application's hostnames are its own to set, through proxy.headers.
Who can reach the API
The proxy, the dashboard and the server itself; not the applications.
The agent has to be on the shipwick network, where it probes replicas, and until 0.8 it listened there: any application's container could reach port 9000 and try tokens against it. Since 0.8 the API has a network of its own, shipwick-control, which the agent, Caddy and the dashboard are on and no application is. The agent listens on its address there and on loopback, and on nothing else; from inside an application's container a connection to the agent is refused, and the dashboard is not reachable from there either. The installer sets this up, on an upgrade as well, with the applications left running.
- A request from an application's container that reaches the agent all the same is answered
403 APPLICATION_CALLERbefore its token is looked at,GET /healthincluded, and it is not counted as a failed attempt. - Which requests those are is decided by network, not by the caller's address alone. On a bridge it shares with other containers, a container can answer for any address of that bridge — the proxy's, the gateway's — and complete a request under it, with the capabilities every container has by default. So on the control network the agent answers the addresses of that network and no others, and what arrives from an address of
shipwickorshipwick-servicesis an application, whoever it claims to be. - An application that is meant to call the API — a deployment tool you run on Shipwick — does so at the API's hostname,
https://<SHIPWICK_AGENT_DOMAIN>, through the proxy, as anything outside the server does.
What leaves the API open to applications
Three arrangements leave the API open to applications, protected by the token alone. The agent then works as it did before 0.8, refuses the containers it manages by their addresses — which stops a mistake, not someone who claims another address — writes a warning to its log when it starts, and says so: shipwick doctor reports it, and GET /server carries open_to_applications.
! Application containers can reach the agent's API: it listens on a network they are on, and only the token keeps them out. On the server, run the installer again; if this stays, the agent's log says why, and "Who can reach the API" in the handbook (Security) what to change| Arrangement | What to change |
|---|---|
| A compose file of your own without the control network | Add it as compose.production.yml has it: the agent on shipwick-control alone (it joins shipwick by itself), Caddy on all three networks, the dashboard on shipwick-control alone |
SHIPWICK_LISTEN_ADDR set for the agent's container | Leave it unset: the image's default lets the agent choose the control network |
The API's port published (ports: ["127.0.0.1:9000:9000"]) on Docker before 28 | Upgrade Docker, or give the API a hostname and remove the port. Docker forwards a published port to the network a container's default route goes through, and before 28 that is the shipwick network for the agent; the agent keeps listening there so that the port works. On Docker 28 and later the port arrives on the control network and nothing is open. There is no third way on Docker 27: the agent starts on the control network alone, and the moment it joins shipwick for its health checks the daemon moves the port there — measured on Docker 27.5.1, where the forwarding rule followed the join and a listener on the control address alone was reset; on 29.9 with the agent's gateway priority it stayed. That is why the installer publishes no port |
An agent installed from a package is a process of the host, and the addresses of a host are reachable from every container on it. It refuses every address of the two application networks, and on the address it has on the control network every address that is not of that network; nothing is open.
What Shipwick does
Tokens and roles
Every request carries a bearer token, every token has a role, and every endpoint is registered with the role it requires: read < deploy < admin, each including the ones before it. One middleware decides. A wrong or revoked token is 401 UNAUTHORIZED; a valid token whose role does not cover the endpoint is 403 FORBIDDEN, and the answer says which role it has and which the endpoint wants. A person who signed in through a provider is the same kind of caller, and passes through the same check.
- The root token is the one the agent is configured with:
SHIPWICK_AGENT_TOKEN, or the one generated on first start. It isadmin, namedroot, and it is not in the database. The agent keeps only its SHA-256 hash, in memory and inagent-token.sha256next to the database, so a lost or corrupt database can never lock the operator out. It cannot be revoked through the API. Rotating it means setting a newSHIPWICK_AGENT_TOKENand restarting the agent. - Every other token is created with
shipwick token create <name> --role read|deploy|adminand stored as its name, role and the SHA-256 of its value. The value is shown once, in the response that creates it, and nowhere else; the agent cannot show it again.shipwick token revokeends it, and requests with it are401from then on. - A
deploytoken can be limited to applications, since 0.6:--app my-api --app web. It changes those and reads everything; another application is403 TOKEN_LIMITED, with a message that names the token's applications. Since 0.10 the images built byshipwick deployare an application's own as well:image: shipwick.local/<other>:<tag>in itsdeploy.yaml, or the same image given toredeploy, is refused with the application it belongs to, so a limited token cannot run another application's image with this application's environment; and an archive sent toPOST /applications/<a>/imagesthat is tagged with another application's name is refused without moving that application's tag — before 0.10 Docker had moved the tag as it loaded the archive and the refusal left the other application's image without its name. No handler decides this for itself: every endpoint is registered with its role and whether it is about one application, and the check runs before the handler. An endpoint of thedeployrole that is not about one application is refused to a limited token outright. An endpoint that takes adeploy.yamlwithout a name in its address (POST /applications,POST /validate, since 0.7) is checked against thenamein the document, which is read before anything else of it is. - A token can expire, since 0.6:
--expires 90d, or a date. From then on it is401 TOKEN_EXPIRED. Only the token itself gets this answer, so it tells nothing to anyone who does not hold it; a wrong token is401 UNAUTHORIZEDwhatever else exists. An expired token does not count towards the limit on failed attempts, and stays listed until it is revoked. The root token does not expire. - A token's applications and its end can be changed, its role and its value cannot, since 0.7:
shipwick token update. A token that is to do more than it was created for is a new token, so that areadtoken never becomesadminby an edit. Moving an end keeps the value that may have leaked in use for the time added; where a token left with a person or sat in a log, replace it instead. Every change is in the audit trail with what was there before. - Token values are 32 random bytes in unpadded base64url behind the prefix
swk_. The prefix carries no entropy; it is there so that a token is recognisable in the places it must never be, a log line or a commit, and so that a leak scanner can grep for it. - Comparison is constant-time. The presented token is hashed once; the root hash is compared in constant time, and a stored token is looked up by its hash, one indexed query, and then compared in constant time as well, so the database's own comparison cannot be turned into a timing oracle.
- Who did what is recorded. Every request that changes something is written to the audit trail. Each deployment stores the token that started it (
by), and a stop or start by a token other than root names it in the application's events.last_used_aton a token is written at most once a minute: it says whether a token is still in use, not what it did last. - Guessing is answered. After 20 failed authentications within a minute from one client address, the agent answers wrong tokens from that address with
429 RATE_LIMITEDand aRetry-Afterheader for the next minute. A valid token is never refused: behind Caddy every client shares the proxy's address, and behind the dashboard every browser shares the dashboard server's, so a guesser must not be able to lock anyone else out. Only failures count, so a mistyped token does not reach the limit, andGET /healthis not limited. - A configured root token must be at least 16 characters. The agent refuses to start with a shorter one.
- If the agent generates its token, it prints it once, directly to standard output and not through the logger, and it cannot be recovered afterwards. Under Docker, "printed" means it is in the container's log (
docker logs) for as long as that container exists. The installer avoids this by generating the token itself and passing it in. Do the same when setting things up by hand. - The installer writes the token to
/opt/shipwick/.envwith mode0600, in a directory with mode0700, and never rewrites an existing.env.
Give CI a deploy token, limited to what it deploys and with an end, and people admin ones — or no tokens at all: people can sign in with the company's accounts. See Create tokens for CI and teammates.
Signing in through a provider
Since 0.6 the agent can be configured with an OpenID Connect provider, and people then sign in to the dashboard with its accounts. Shipwick keeps no passwords and no list of users: second factors, password rules and offboarding stay with the provider. A table of rules on the agent says who gets which role; nobody without a rule gets in. See Sign in with your company's accounts.
- The client secret is read from the agent's environment, sent to the provider's token endpoint and nowhere else, and never logged or returned. The dashboard and the browser never see it.
- The flow is the authorization code with PKCE. The code the provider appends to the callback is useless to anyone who reads it there: redeeming it takes a verifier that never left the dashboard's server-side cookie, and the provider redeems each code once.
- An ID token is believed only if one of the provider's keys signed it (RS256 or ES256; a token that claims to be unsigned is refused), if it was issued by the configured issuer for this client, is within its time and minutes old, and carries the one-time value of this sign-in. Each such value is accepted once. An address the provider marks as unverified is refused.
- A provider whose configuration names another issuer than the configured one is refused. The one exception, since 0.7, is Microsoft Entra's address for several tenants, and there a token's issuer must be its own tenant's, the tenant one the operator listed in
SHIPWICK_OIDC_TENANTS. - A name the provider reports is kept only if it can be a name, since 0.7, where people are named by another claim than
email: letters, digits and punctuation without spaces, at most 254 characters. It goes into the audit trail, the log and a deployment'sby. A name that is not is refused, and not repeated in the refusal. - The provider is only ever asked to send people back to the dashboard's configured hostname, never to an address taken from a request.
- A session lasts ten hours and is not extended by use. Of a session the agent keeps the SHA-256, as of a token. Every request asks the rules again: a session whose rule was revoked or changed ends with its next request, not at its expiry, and an admin can end one at once with
shipwick access signout. - What the agent cannot see is a change at the provider. Someone removed from a group there, or whose account was disabled, keeps a session that exists until it ends, ten hours at most.
- A failed sign-in and a session nobody issued count towards the same limit as a wrong token, and a limited address is answered without the provider being asked.
- Rules, sessions and sign-ins stay on the server: an export takes none of them along, as it takes no tokens.
The audit trail
Since 0.6 every request that changes something leaves an entry: who made it — the token's name, or the name of a person who signed in — when, from which address, what it was about and how it was answered. Reading it needs admin: shipwick audit, or the dashboard's Access page. See See who changed what.
- Refusals are recorded too: a request refused for its role or its application limit is an entry, since an attempt is what one looks for after a token leaked. So are sign-ins, admitted or not.
- Nothing from a request's body is kept except names: no
env, no secret's value, no command, no passphrase. - A request without a valid token has no entry. It has no name to record; it is in the agent's log, and counted by the limit on failed attempts.
- The address is the connection's, with the proxy's word next to it. Caddy replaces
X-Forwarded-Forwith the address it saw, so through the proxy it is the client; on a connection that bypasses the proxy the header is whatever the caller sent. Both are kept, so the reader can tell. - It is kept for a year, and at most 100,000 entries. It lives in the agent's database and travels with its backups.
- Taking it out is recorded. Since 0.7 the trail can be exported whole, as CSV or JSON; an export needs
adminand is itself an entry,audit.export, with who took it, the format, the filters and the number of entries. In CSV a cell that a spreadsheet would run as a formula — one that begins with=,+,-or@— is written with an apostrophe in front: the trail holds names that callers chose.
Secrets at rest
The env values and the basic-auth passwords of every deployment, since 0.10 its logging.options.splunk-token, the secrets stored with shipwick secret set, the registry passwords stored with shipwick registry login, the keys of the certificates supplied with shipwick cert set and the secret values a deployment's document referred to with ${NAME} (kept with the deployment since 0.7, so that a redeploy or rollback need not look them up) are encrypted before they are written to the database, and nothing else is. Names, images, hostnames and the variable names stay in clear, so the file remains debuggable; only the values are ciphertext.
- The scheme is AES-256-GCM with a fresh 12-byte random nonce per value and the variable name as additional authenticated data. Binding the name means a ciphertext cut from
DB_PASSWORDand pasted intoDEBUG_ECHOdoes not decrypt: a tampered database cannot make the agent hand a secret to a different variable. The stored form isenc1:followed by base64 of nonce and ciphertext; the prefix versions the scheme and marks the value as encrypted. - Every kind of value is bound to what it is. A basic-auth password is sealed under its position in the configuration (
proxy.basic_auth[0].password), a stored secret under its name, a registry password underregistry:<name>, a certificate's key undercertificate:<hostname>. The prefixes keep a registry's password from opening as a secret or a variable that happens to carry the registry's name. - The key is 32 bytes, from
SHIPWICK_ENCRYPTION_KEY(64 hex characters) or, by default,encryption.keyin the data directory, created with mode0600on the agent's first start. It lives next to the database rather than in it, so a copy of the database alone is useless. Opening the database proves the key against every stored value, so a key that does not match is caught at start, not at the first deployment, and the agent refuses to start with a message that says so. Supplying the key from a secret manager at start-up, and what that does to a reboot, is in Keep the encryption key off the server's disk. - What it protects: a copy of the database file without the key. A backup, a snapshot, a disk that left the building, a file opened with
sqlite3by whoever debugs it. - What it does not protect against: root on the server, who can read the key file and the agent's memory; and the values inside running containers, which
docker inspectshows to anyone with the Docker socket. Anenvvalue has to be in clear inside the container for the application to use it. - Upgrading: a database written by a release before encryption is recognised by the missing prefix, and its values are encrypted in place, in one transaction, on the first start after the upgrade.
- The key can be replaced while the agent runs: see Key rotation.
Back up encryption.key together with shipwick.db
Without the key the database cannot be read, and the agent refuses to start against it. The agent says so in its log when it creates the key. A backup of the data directory that leaves the key out is a backup of nothing. Since 0.5 the agent takes that backup itself, daily and encrypted, once SHIPWICK_BACKUP_PASSPHRASE is set, and shipwick doctor says when it is not: see Backups and exports.
Key rotation
When the key may have been seen — a backup that held it went astray, someone who had the server left — replace it with shipwick server rotate-key, or Rotate encryption key on the dashboard's server page. Both need the admin role. See Rotate the encryption key for the steps.
- Nothing is deployed and nothing restarts. The running agent generates a new key, re-encrypts every stored value under it in one transaction — the
envvalues, basic-auth passwords and Splunk token of every deployment record, the secrets, the registry passwords, the certificate keys, the secret values deployments referred to — and carries on with it. - It survives a crash at any point. The database and the key are two files, and no step changes both. The new key is written next to the key file, as
encryption.key.new, and synced; the transaction commits; the new key is moved overencryption.key. A crash before the commit leaves the old key and a pending key that opens nothing; a crash after it leaves a pending key that opens everything. At its next start the agent tries which of the two opens the data and discards or promotes the pending key accordingly. Nothing is deleted while neither fits. - With the key in
SHIPWICK_ENCRYPTION_KEYthe agent cannot take the last step: it cannot change the environment it will be started with next. The new key is shown once, for you to put there before the agent restarts. Until then the agent keeps working with the new key and holds a copy of it inencryption.key.new, so that a lost terminal does not lose the key — which also means that, for as long as that file exists, the data directory holds the key next to the database, the thing setting the variable was meant to avoid. Started with the old key, the agent refuses to start and says where the new one is; started with the new one, it removes the copy. A second rotation is refused until then. - The log records the rotation and the token that asked for it, never a key. It is not an application event.
- Rotation protects what is written from now on. A copy of the old database together with the old key stays readable, so a secret that may have leaked with them has to be changed where it is used as well. Backups of the database made before the rotation still need the old key; back up the new one.
Secrets kept on the server
A value for ${NAME} in env can be stored on the server once, with shipwick secret set NAME, so that no laptop and no pipeline has to hold it. Since 0.9 a secret belongs to one application (--app my-api) or to the whole server; see Keep secrets on the server. What the agent does with it:
- The value is never an argument:
shipwick secret setasks for it without echo, reads it from standard input, or from a file with--from-file. Arguments leak throughpsand shell history. - It is written encrypted, like an
envvalue, with its name as additional authenticated data —applications/<application>/secrets/<name>for an application's own, so that a ciphertext moved between scopes does not open — and is read by nobody afterwards:GET /secretslists names, scopes and dates only, and the value is never returned, logged or repeated in an error. It goes into containers and nowhere else; a secret stored with--appreaches that application's containers and no other's. - A value with characters a URL cannot carry unescaped —
@,:,/,?,#,%, whitespace — is stored all the same, andshipwick secret setwarns which ones it saw, never the value: written into a connection string, such a password breaks it. - The agent fills it into the
envvalues of a deployment when the deployment is recorded, so the record holds the value and a rollback restores what that deployment ran with. A${NAME}that is set neither whereshipwickruns nor on the server refuses the deployment before anything is recorded. - Storing and removing a secret needs the
adminrole; listing the names needsread. In the dashboard, the value is cleared from the page the moment the request is sent. - Since 0.7 the agent remembers, with each deployment, which values it filled in and how the document wrote them —
postgres://app:${DB_PASSWORD}@db:5432/app— encrypted like a secret. That text, never the value, is whatshipwick configgives back. The text around a reference is more than a reader is shown elsewhere, which is why getting the document takes thedeployrole, and a limited token gets the documents of its applications only. - Since 0.8 that document also carries the
envvalues that stood in the deployed file as it was sent —LOG_LEVEL: debug— as they are. The agent cannot tell such a value from a password;shipwick deploycan, because it knows which values it filled in and which it found written, and says so with the deployment. A value it filled in from the environment or--env-file, a basic-auth password, and every value nobody spoke for stay masked. What is written indeploy.yamlin plain sight is therefore readable by everyone who may deploy the application: a password belongs in${NAME}, not in the file.
Passwords of the proxy
A basic-auth password in the proxy block of deploy.yaml is a secret, treated like an env value. Write ${ADMIN_PASSWORD} and it is filled in by the CLI from its environment or --env-file, else by the agent from the secrets stored on the server. It is encrypted in the database, shown as ******** wherever the configuration is shown, and Caddy is given a bcrypt hash of it, never the password. It must have at least 8 characters and at most 72 bytes.
The username reaches Caddy escaped like a header value, since 0.10, and deploy.yaml refuses one with braces, which the proxy would read as a placeholder: before, {env.HOME} was replaced by the proxy's environment before the comparison, and {env.UNSET} made the proxy refuse the configuration, so the rollout failed. A gate with a path matches the path as the proxy reads it — case-insensitively, with .., // and percent-encoding resolved — and nothing else: /admin;x, /admin. or /admin%20 are not /admin to the proxy and reach the application, which may well read them as /admin (Tomcat drops ;…, IIS a trailing dot), so an application with routes of its own under the gated path is gated without path, or does its own authentication.
Basic authentication sends the password with every request; it is protected by HTTPS, which every domain has. It keeps a staging site or an admin area closed. It is not a login system.
Registry credentials
Since 0.5 the agent keeps the credentials of private registries itself, stored with shipwick registry login.
- The password is never an argument: it is asked for without echo or piped in. The agent checks it against the registry before storing it, with a call that verifies and keeps nothing.
- It is written encrypted, like a secret, and is never listed, logged or returned:
GET /registrieslists the registries a credential is stored for, without passwords. It is sent to the Docker daemon with a pull from its registry and nowhere else. The daemon holds no registry credentials; every pull carries its own. - Storing and removing a credential needs the
adminrole. - A registry without a stored credential falls back to the Docker configuration file on the server, where
docker loginstores credentials base64-encoded, not encrypted. See Pull from private registries.
Certificates you supply
The key of a certificate supplied with shipwick cert set is read from a file, never logged and never returned: the API answers with what a certificate says about itself — issuer, expiry, names — never the key or the PEM. The chain is public and is stored in clear; the key is encrypted like a secret, bound to its hostname.
The key does leave the database for one place, the proxy, which cannot serve the certificate without it: it is part of the configuration the agent loads into Caddy. Caddy's autosaved copy of that configuration, on the caddy-config volume, therefore contains it. That volume is mounted by Caddy alone, and should stay so. See Certificates.
The Cloudflare token
SHIPWICK_CLOUDFLARE_API_TOKEN can edit the DNS of your zones. Give it the two permissions it needs and no more: Zone → Zone → Read and Zone → DNS → Edit, on the zones your hostnames are in, those two exactly; DNS Settings, DNS Firewall and DNS Views are other permissions. Not the Global API Key. Caddy uses it to create and remove the _acme-challenge TXT records, nothing else. An IP filter on the token, if you give it one, must name every address the server calls from, its IPv6 address included.
- Where it is. In
/opt/shipwick/.env, in the agent's memory, and inside the configuration the agent loads into Caddy — and therefore in Caddy's autosaved copy of it on thecaddy-configvolume. - Where it is not. It is never logged and never returned by the API;
GET /serversays that the DNS challenge is on and, since 0.9, what the agent found out when it checked the token — the address Cloudflare saw, the zones and the problems, as sentences — and nothing of the token itself. The agent removes it from Caddy's errors before they are logged or shown, and refuses at startup a value that is not of a token's form, without repeating it. - What the check does. Since 0.9 the agent verifies the token when it starts and when
shipwick doctorasks with anadmintoken: whether Cloudflare accepts it from the server's address, which zones it sees, and whether it can create a DNS record in each — a TXT record of its own,_shipwick-check.<zone>, removed at once. Because it writes, the check runs at most once a minute. See Put Cloudflare in front. - Cloudflare's ranges become trusted proxies. With the token set, Cloudflare's address ranges are trusted proxies of Caddy, so applications find the visitor's address first in
X-Forwarded-For, followed by Cloudflare's. From any other sender the header is replaced, since anyone can send one. The ranges are the ones Cloudflare publishes; they are compiled into the agent. - Set the zone's SSL/TLS mode to Full (strict), which checks the certificate Caddy obtained. Full accepts any certificate from the server.
Backups and exports
A backup is the application's data, and the agent's own is every secret together with the key to them.
- Without
SHIPWICK_BACKUP_PASSPHRASE, application backups are plain tar files in the data directory, as readable as the volumes next to them, and the agent's state is not backed up at all. The key is never written anywhere unencrypted:encryption.keynext toshipwick.dbin a directory of backups would be every secret in clear, and no backup is the smaller harm, as long as it is said.shipwick doctorandGET /serversay it. - With it, everything is encrypted before it reaches the disk or the bucket: AES-256-GCM with a key derived from the passphrase by PBKDF2-HMAC-SHA256, a random salt per file. The encryption is the agent's, not the bucket's, so whoever holds the bucket holds nothing they can read — and whoever holds the passphrase and the bucket holds everything, which is why the passphrase is not to be stored in the bucket's account.
- Tampering is detected. Truncating, reordering or altering an encrypted backup is detected when it is read.
- Credentials stay out of sight. The passphrase and the bucket's two keys are never logged or returned by the API; the log names the bucket and its host.
- Roles. Taking and verifying a backup needs the
deployrole; downloading, restoring or removing one, and anything about the agent's state, needsadmin. - Verification runs the application.
shipwick backups verifystarts a container of the application's current image on a restored copy of the data, with the application's environment. It has no route, no name another application could find it under and no published ports, but an application that writes somewhere other than its volumes when it starts does that here too.
An export, the file shipwick export writes to move a server, holds every secret the server has: the env values and basic-auth passwords of every application, the stored secrets, the registry credentials and the certificates with their keys.
- It is encrypted, always, in the format backups use. The passphrase is asked for twice without echo, or read from
SHIPWICK_EXPORT_PASSPHRASE, and must be at least 12 characters. The agent encrypts as it writes, so nothing leaves it unencrypted and nothing is kept on the server. An export written on a schedule is encrypted withSHIPWICK_BACKUP_PASSPHRASE, and the agent refuses to start with a schedule and no passphrase. - The old key does not travel. The values are opened for the export and sealed again on import with the new server's own key. API tokens stay behind as well.
- Exporting and importing need the
adminrole.
See Back up and restore volumes.
What the proxy logs
Since 0.5 the agent reads Caddy's access log to answer shipwick traffic. The log is written with that reader in mind:
- No headers and no query strings. Request and response headers, TLS details and the remote port are removed before a line is written, and the URI is cut at the question mark, so a token in a query string or an
Authorizationheader never reaches the log, let alone the agent. What is left of a request is its time, hostname, method, path, status, duration, size and client address. - The agent's and the dashboard's own hostnames are not logged at all.
- What is kept. Per-minute counts and a latency histogram for seven days, in the database, and the last 200 requests of each application in the agent's memory. The access log itself stays in Docker's log files of the Caddy container, capped at 3 files of 10 MB like every container's log.
- Reading traffic and requests needs the
readrole.
See Traffic.
Nothing secret in logs or responses
- A proxy's URL in
HTTPS_PROXYmay hold a password. The agent logs the proxy's host and port and nothing else of it,GET /serverreports the same, and no error repeats the URL. See Run behind a corporate proxy or without internet. - Tokens,
Authorizationheaders, request bodies and environment values are never logged. The request log holds the method, path, status, duration and remote address. - Environment values, basic-auth passwords and, since 0.10,
logging.options.splunk-tokenare masked as********in every API response. The one exception, since 0.8, is the documentGET /applications/:name/configreturns to a token that may deploy the application: theenvvalues its deployment named as written in plain sight are in it as they are; see Secrets kept on the server. Validation errors never echo a value. - The mask is refused as a value, since 0.7: a configuration copied out of an answer cannot be deployed with
********for a password. A document that holds it as anenvvalue or a basic-auth password is400 INVALID_CONFIG, whoever sends it. - The log archive, since 0.7, holds what applications printed, and is as sensitive as the logs themselves. Reading it takes the role that reads the logs. It puts nothing into events, notifications or the audit trail, and nothing of what its endpoints return is written to the agent's log; the request log holds the path, not the query. The files are not encrypted, like the logs Docker keeps next to them: they are gzip files under
logs/in the data directory. They are removed with their application, and are in neither the backup of the agent's state nor an export. See Find out why it died. GET /metrics, the Prometheus endpoint, is authenticated like the rest of the API: a token with thereadrole. It carries numbers and names — statuses, replica counts, CPU, memory, restarts, the disk, the active alerts — and no values. Give the scraper areadtoken of its own.${NAME}placeholders keep secrets out ofdeploy.yamland out of your repository.shipwickfills them in from its environment or--env-fileat deploy time and reports only how many were substituted, never the values; the agent fills the remainingenvvalues in from the secrets stored on the server, and a name neither has stops the deployment.- The webhook URL is a credential: Slack's and Discord's carry the token in the path. It is validated without being echoed, and only its host ever appears in a log line. Plain
httpis refused unless the host is loopback or a private address. - API responses carry
Cache-Control: no-store.
No shell, anywhere
The agent talks to the Docker Engine API directly. It never runs the docker command line, and nothing from deploy.yaml or an API request is ever executed on the server or interpolated into a command line.
Commands do exist in deploy.yaml now: entrypoint, command, health.command, pre_deploy.command, jobs[].command, and the body of shipwick run. Every one of them is an argv, a list of arguments handed to Docker exactly as written; a string is one argument, spaces included, and nothing is split, joined or passed through a shell. Every one of them runs inside a container of the application's own image, as the image's own command would: a replica's process, a one-off container for the hook, a job or a run, or, for a command health check, an exec inside the running replica through the Engine API, without a TTY. They change what runs inside the container, which the image always decided anyway. The container's boundaries are the same, and nothing runs on the server itself.
The server never builds. With build: ., docker build runs on the developer's machine, as an argv, with paths that were validated as relative and inside the project; the agent only loads the resulting archive, and refuses one that does not carry exactly one image tagged for that application. A Dockerfile runs whatever it likes, with the network and CPU of the machine it runs on, and that machine is yours, not the server. The same goes for the CLI's other programs: ssh in shipwick server install and the browser opener in shipwick open are run as programs with arguments, never through a shell, with fixed remote commands and validated hostnames.
A static folder is files and directories only. The upload of a static application is a tar archive of files and directories with paths inside the folder; a symbolic link is refused, since the proxy's file server would follow it, and the CLI skips one that leads out of the folder before anything is sent. The proxy serves the folder from its own container, /srv/shipwick/<app>/<digest>, and nothing else. Everything sent is served to anyone who asks for its path, dotfiles included — .well-known is content — so the CLI leaves out what describes the site: deploy.yaml and shipwick.yaml, .git and .env files, wherever they are in the folder. Run the build into a folder of its own, not into the project's root.
Validation
Names, images, hostnames, health paths, published ports, logging options, build paths, static folders and secret names are strictly validated. These are the inputs that end up in container names, URLs, the proxy configuration, the daemon's configuration and file paths. Unknown fields in deploy.yaml are errors, and request bodies are size-limited: 64 KB for a deploy.yaml, 4 GB for an image archive, 512 MB for a static folder, 10 GB for a volume archive. The agent re-validates everything the CLI sends: client-side validation is a convenience, not a trust boundary.
Proxy configuration as data
The Caddy configuration is built as data and serialized, never assembled from strings. Even input that slipped past validation could not change its structure. A hostname is taken per path: several applications may share one, each serving a path of its own, and the same path twice is refused. No application can claim a hostname that the agent or the dashboard is served on. The same goes for what the proxy block adds — response headers, redirects, the accounts of basic authentication — and for a supplied certificate and the Cloudflare token: they enter the configuration as values of fields, never as text.
Unprivileged containers
Application containers are never privileged, run with no-new-privileges and get no host mounts; volumes are named Docker volumes, never a host path. Their logs are size-capped at 3 files of 10 MB, so an application cannot fill the disk by logging. This holds for every container and cannot be switched off; the security block of deploy.yaml takes away more, per application: see Containers locked down further.
Published ports are the one exception to "no host ports". publish binds exactly the listed container ports on the server, for services the proxy cannot serve because they are not HTTP. The agent refuses a port it or the proxy listens on, and one another application already publishes, before anything is started; validation refuses publish without recreate and one replica.
Published ports bypass the host firewall
On most distributions Docker inserts its own iptables rules ahead of ufw's or firewalld's, so a port published on every address is reachable from the internet whatever the firewall says. Publish only what must be reachable from outside the server, bind it to a private address where one exists (address: 10.0.0.5), and keep what only other applications need unpublished: they reach it by name on the shipwick network. See Expose a service that is not HTTP.
Logging drivers refuse sockets and files. logging hands replica logs to a Docker logging driver, whose options reach the daemon as written. The driver list is closed to the ones whose options are checked, a collector address must be scheme://host:port (a socket is a path on the server, which Shipwick never mounts), and options that name a certificate or CA file on the server are refused: no application gets to make the daemon read a file. One option is a credential, splunk-token; since 0.10 it is a secret like an env value — masked, encrypted at rest, writable as ${NAME}. An agent before 0.10 stored and returned it in clear; a deployment recorded by one keeps it so until the application is deployed again, so deploy once more and rotate the token if it may have been read.
Containers locked down further
Since 0.8 the security block of deploy.yaml takes away more than the above, for an application that can do without it. Each of its keys narrows; there is none that widens — no capability can be added, nothing of the server mounted, no privilege asked for — so a deploy.yaml with the block is never less confined than one without it.
user: "1000:1000"
security:
read_only: true # the root filesystem cannot be written
tmpfs: # scratch space, in memory
- /tmp
- path: /var/cache/api
size: 200mb # 1mb to 1gb; 64mb unless set
capabilities: none # or the ones to keep: [CHOWN, SETGID, SETUID]
non_root: true # a container that would run as root is refusedThe block applies to every container made from the application: its replicas, the pre_deploy hook, jobs, shipwick run, the container of backups.before_in: container and the one a backup is verified in. A job is not a way around it. shipwick validate says what the block takes away, and GET /applications/:name returns it with the rest of the spec.
read_only. An attacker who can write files inside a container can replace the application's code and leave something behind for the next request; with a read-only root there is nowhere to write it.
- Volumes stay writable, and most applications need a little more: a
tmpfsentry is a directory in memory, empty when a container starts and gone when it stops, never shared between replicas. - A
tmpfsis mountednosuid,nodevandnoexec— a file there cannot be executed — and writable by every user, like/tmp. - What is written to it is memory. It counts against
resources.memoryas the process's own does, and an application that fills atmpfsbeyond its memory limit is stopped for it: 48 MB written into atmpfsof 64 MB undermemory: 32mbended with the writer killed for memory. - Data that must be executed, shared or kept belongs in a volume.
- An application that fails under
read_onlynames the path in its log (Read-only file system); that path is thetmpfsentry it needs.
capabilities. A process that runs as root inside a container is root with fourteen of the kernel's capabilities, Docker's default set: AUDIT_WRITE, CHOWN, DAC_OVERRIDE, FOWNER, FSETID, KILL, MKNOD, NET_BIND_SERVICE, NET_RAW, SETFCAP, SETGID, SETPCAP, SETUID, SYS_CHROOT. capabilities: none drops all of them; a list keeps the ones it names and drops the rest. A name outside the set is refused. An application that runs as another user than root and listens on a port above 1024 needs none.
What some common images need was found by starting the Alpine variant of each under read_only with one set after another, on Docker 29.8:
| Image, as it is started | capabilities | tmpfs |
|---|---|---|
nginx, as root (the image's default) | [CHOWN, SETGID, SETUID] | /var/cache/nginx, /var/run |
node, with user: "1000:1000", listening on 3000 | none | /tmp, if the application writes there |
postgres:17, as root (the image's default) | [CHOWN, DAC_OVERRIDE, FOWNER, SETGID, SETUID] | /var/run/postgresql, /tmp |
postgres:17, with user: "70:70" (the Alpine image's postgres) | none | /var/run/postgresql, /tmp |
redis:7, as root (the image's default), a volume at /data | [SETGID, SETUID] | — |
redis:7, with user: "999:1000" (the Alpine image's redis), a volume at /data | none | — |
- An image that starts as root to give its files to another user and then become that user — what these three do — needs
CHOWN,SETGIDandSETUIDfor exactly that, and nothing once it runs; started as the other user to begin with, it needs none. - PostgreSQL was restarted on its filled volume as well: with fewer than the five capabilities it starts on an empty volume and not again.
NET_BIND_SERVICEis missing from the list for nginx on purpose. Docker lets every user in a container listen on every port (the containers here hadnet.ipv4.ip_unprivileged_port_startat 0), so port 80 needs no capability.- A dropped capability shows as
Operation not permittedin the application's log, next to the call that needed it.
non_root. The agent reads the user from user in deploy.yaml and, when that is not set, from the image's own configuration, and refuses to create a container that would run as root: a user that is missing, root or the id 0. A user given by name is refused as well. Which id a name stands for is written in the image's /etc/passwd, which the agent does not read, and an image is free to give the id 0 a second name; a numeric id is the one thing that can be held to. The remedy is in the message: user: "1000:1000", with the id the image's user has.
shipwick validate already refuses user: root or a name next to non_root. What the image says is known once it is on the server, so a deployment of an image that runs as root fails there, after the pull and before anything is started, with the previous version still serving:
security.non_root refuses image nginx:1.27: it names no user, and a container without one runs as root; set user in deploy.yaml to a numeric id the image can run as, e.g. user: "1000:1000", or build the image with a USER instructionEvery container made later from the same deployment — a restart, a job, a command — is held to the same check when it is created, because a tag can come to name another image.
What the block does not touch. The seccomp and AppArmor profiles are Docker's defaults for every container, with or without it, and there is no key to change them; user namespaces are the daemon's to configure.
An agent older than 0.8 does not know security and refuses a deploy.yaml that has it, as it refuses every key it does not know: the application is not deployed without what the block asks for, and shipwick deploy says that the server is older than the file and how to upgrade it. An export written before 0.9 is the exception: an agent older than 0.8 that imports one reads the applications without the block. From 0.9 on an export names the keys it uses, and an agent that lacks one refuses it; see Move to a new server.
A distroless agent image
The agent image contains the agent binary and CA certificates. It has no shell and no package manager. The binary is statically linked.
Verified installation
Everything the installer fetches comes from one release and is verified against that release's checksums. Downloads are HTTPS-only. A checksum mismatch installs nothing and leaves a running installation as it was. Since 0.10 latest is resolved to a release's tag before the first download, so two files cannot come from two releases and an older, signed release's files put in the latest one's place would not verify; before, every file was fetched through GitHub's latest redirect separately, as install.ps1 and shipwick upgrade never did. The three images — the agent, the dashboard and the proxy, Shipwick's own build of Caddy with the Cloudflare DNS module and Shipwick's own way of finding replicas, and nothing else added — are pinned to the release's version, and since 0.10 what the pull brought is compared with the digests the release published, its signed image-digests.txt: an image the registry serves under the release's tag that is not the release's is removed again, the compose file that ran is put back and the installer stops with the installation as it was. Images of your own, named in .env, are not compared, and the output says so; releases before 0.7.0 published no digests, so the installer says so and goes on, or stops under SHIPWICK_REQUIRE_SIGNATURE=1.
Since 0.7 the images of a bundle are proven the same way: shipwick server bundle checks the archive of images against image-digests.txt before it writes the bundle, and the installer checks what Docker loaded before it replaces anything. The Debian and RPM packages of the agent are files of the release, verified against checksums.txt like the others; they carry no signature of their own.
Signed releases
The checksums say that the files are the ones the release lists. Since 0.8.0 a signature says who wrote the list: checksums.txt — and through it every binary, package, the compose file, the installer and the digests of the images — is signed by the workflow that published the release, and so is each image, by digest.
- No key is stored anywhere. GitHub tells Sigstore which workflow is running and for which tag, Sigstore issues a certificate for that identity that is valid for ten minutes, and the signature goes into a public log.
- What it proves is that the file or image was produced by that workflow file, at that tag, in that repository: a commit you can read. It does not prove that the commit is good.
- The installers,
shipwick upgradeandshipwick server bundleverify it when cosign (2.5 or later) is installed, and stop if the signature is not the release workflow's. Without cosign, which is every new server, they say that the signature was not checked and go by the checksums, as before. Cosign 2.4 does not read the signature. SHIPWICK_REQUIRE_SIGNATURE=1makes the installer refuse anything short of a verified signature. Without it a release that has no signature is installed with a warning: releases before 0.8.0 have none, and the installer cannot tell one of those from a release whose signature somebody removed.- Each file and each image has a provenance attestation, kept by GitHub, and each binary and image a bill of materials in SPDX.
The commands, with the identity they must match: Verify a release.
With a hostname for the API, the installer saves the URL and the token as a context of the user who runs it, so that shipwick works on the server. The token goes to the CLI on standard input, never as an argument, and the CLI writes its own file, mode 0600.
What leaves the server unasked
Since 0.7, one request a day, from the agent to https://github.com/shipwick/shipwick/releases/latest, to learn whether a newer release exists.
- What it says about the server: nothing. It is a
HEADrequest without a body, a query or a cookie, and itsUser-Agentisshipwick-agent: no version, no identifier of the server, nothing about what it runs. - What GitHub sees is the address the request came from, or the proxy's, and that a Shipwick agent runs behind it. The answer is a redirect whose target names the release, and it is not followed.
- It goes through the proxy and the certificate authorities the agent was given, and gives up after 15 seconds. A server that cannot reach GitHub notices nothing.
SHIPWICK_UPDATE_CHECK=offstops it. The agent says at startup, once, that it asks and how to stop it.
Everything else that leaves the server does so because you configured it: the webhook, the bucket, the sign-in provider, the certificate authority, the registries your images come from, and with SHIPWICK_CLOUDFLARE_API_TOKEN set, since 0.9, the check of that token against Cloudflare's API when the agent starts and when doctor asks, at most once a minute. The CLI asks GitHub for the latest release only when you run shipwick upgrade, shipwick doctor or shipwick server bundle, with the User-Agent shipwick/<version>. The dashboard makes no request to any third party.
Token handling in the CLI
shipwicknever takes the token as a flag. Arguments leak throughpsand shell history. The token comes fromSHIPWICK_AGENT_TOKEN, from a prompt without echo, or from standard input.- The saved configuration file is written with mode
0600, in a directory created with mode0700. On Windows the file lives in the profile'sAppDatawith the profile's own permissions (the user, SYSTEM and Administrators), and aSHIPWICK_CONFIGpointed at a shared folder gets no protection from the CLI. It holds one entry per context, each with its URL and token. - A saved token belongs to the URL it was saved for. If
--urlorSHIPWICK_AGENT_URLpoints at a different agent, the saved token is not sent there. - A redirect from the agent's URL is not followed, since 0.10. The agent never answers with one, so a redirect is something in front of it, and Go would have sent the
Authorizationheader along to the same host on any port or scheme — a proxy in front of the agent could have sent the token on over plain HTTP. It is an error that names where the redirect pointed and says that the token was not sent there:https://agent.example.com answered with a redirect (HTTP 301) to http://…, which was not followed and did not receive the token: check the saved URL, and what proxy stands in front of the agent. shipwickwarns before a token crosses the network over plain HTTP to anything other than the local machine.shipwick loginverifies the token against the agent before saving it, unless--no-checksays not to, for a hostname whose DNS record or certificate does not exist yet.shipwick server statusshows which token and role you are using.- The values
shipwickstores on the server are never arguments either: a secret, a registry password and the passphrase of an export are asked for without echo or piped in, and a certificate's key is read from a file. shipwick token createprints the new token once, to standard output, and never stores it; put it in the CI secret and move on.shipwick upgradewrites the new binary next to the old one and renames it over only once its SHA-256 matches the release'schecksums.txt. With cosign on the machine,checksums.txtis first verified against the release's signature, and a signature that does not verify changes nothing; cosign is run as a program with arguments, never through a shell.--versioninstalls the release it names with the same verification, the identity being the workflow at that tag. A binary under Homebrew's Cellar is left to Homebrew.shipwick server configuresends the agent's settings to the server as data on the standard input of a fixed script, never as part of a command, so a value may hold anything but a line break; it never prints a value, and the file keeps its mode.shipwick server install, when the login is refused, runsssh -vonce more and shows of its output only each offered key's name and fingerprint, the public half.
Session handling in the dashboard
- The token never reaches JavaScript. The dashboard's own server verifies it against the agent at sign-in and keeps it in an
httpOnly,SameSite=Strictcookie,Secureover HTTPS, valid for 7 days; a person's session is kept the same way, until the agent says it ends. With several servers in one dashboard each has a cookie of its own. The browser application only knows whether a session exists and, fromGET /server, the token's name and role. An XSS bug or a malicious browser extension cannot read the token. A token created on the Access page is shown once, in the page, and never stored; so is the new key of a rotation, when the agent's key is set in its environment. - The role follows the token. Whoever signs in brings a token, and what the dashboard offers follows that token's role: controls the role does not cover are disabled with the reason, a token limited to some applications is told so on the page of every other, and the Access page appears for
adminonly. That is a courtesy; roles are enforced by the agent, which answers403to a request the role does not cover whatever the page does. - The browser never talks to the agent. The dashboard server relays requests and adds the
Authorizationheader. The agent therefore needs no CORS support and can stay off the public internet. - CSRF. Every state-changing request must carry the header
X-Shipwick-Request: 1. A cross-origin page cannot add a custom header without a CORS preflight, and the server never grants one.Sec-Fetch-Site, where the browser sends it, must besame-origin.SameSite=Strictis the second layer. - The relay is not an open proxy. The target host comes only from the dashboard's
SHIPWICK_AGENT_URLorSHIPWICK_AGENTS; a request chooses among the configured names and never supplies an address. OnlyGET,HEAD,POST,PUTandDELETEare accepted, the path must stay under/api/v1/with each segment limited to[A-Za-z0-9._~-], and onlyAccept,Content-Typeand, for an upload,Content-Lengthare forwarded. The browser's cookies never are.X-Forwarded-Foris set by the relay itself, for the audit trail; a header a browser sends directly is ignored.POSTbodies over 128 KB are refused; aPUTbody, a volume archive or a secret's value, is streamed through and bounded by the agent's own limits. The dashboard uploads neither static folders nor images:shipwick deploydoes that. Since 0.7 an export that is downloaded and a file that is imported pass through the dashboard's server as they arrive; it keeps neither the file nor the passphrase. Adeploy.yamlpasted into it is checked by the agent like one sent by the CLI. - Failed sign-ins are slowed down by the agent. Every browser reaches the agent from the dashboard server's address, so 20 failed sign-ins within a minute, from anyone, make the agent answer wrong tokens with
429for a minute; the dashboard showsToo many failed attempts from this address; try again in a minuteand never presents it as a rejected token. A valid token is never refused. - A
401from the agent ends the session. The cookie is cleared and the application returns to the sign-in page, with the reason when the agent gives one: the token expired, the session ran out or was ended. - Signing in through a provider keeps the client secret on the agent. The dashboard's server only starts the sign-in and passes the code on; the values it keeps for that are in an
httpOnlycookie that lasts ten minutes and is cleared by the callback whatever happens. - The token is never logged by the dashboard. Post-login redirects only accept same-site paths.
- In production the dashboard sends a Content-Security-Policy of
default-src 'self'(with inline script and style allowed),frame-ancestors 'none',X-Frame-Options: DENY,X-Content-Type-Options: nosniffandReferrer-Policy: no-referrer. It loads nothing from third parties. - The dashboard has no database and no credentials of its own. Accounts are the agent's named tokens with roles, and the people its access rules admit.
What Shipwick does not do yet
- A limit on a token does not hide anything. A
deploytoken limited to some applications still reads every application's logs and configuration, andreadandadmincannot be limited. One Docker daemon does not separate tenants, and Shipwick does not promise it. - Rate limiting is per client address, and the dashboard is one client. The agent slows down failed authentications by address, which behind the dashboard is the dashboard server's; there is no limit per token or per browser. Tokens the agent issues are 32 random bytes; a configured root token is at least 16 characters.
- Registry credential helpers are not supported, and are not planned. A helper is a program on the host that the Docker command line executes; the agent's container does not have it, and the agent executes nothing. For Amazon ECR and Google Artifact Registry, hand the cloud CLI's token to
shipwick registry logininstead: see Registries with tokens that expire. A credential stored withshipwick registry loginis encrypted; one read from theauthsentries of the Docker configuration file on the server is stored there base64-encoded, not encrypted. Withbuild: .no registry and no credentials are involved. - Backups are not encrypted unless you set a passphrase. Without
SHIPWICK_BACKUP_PASSPHRASEthe backups of volumes are plain tar files, and the agent's own state, the database and the key, is not backed up at all. - The log archive is not encrypted. What a container printed before it ended is kept as gzip files in the data directory, like the logs Docker keeps: an application that prints secrets has them there for as long as the archive keeps an entry, 14 days unless set otherwise.
- Rotation does not reach back. A copy of the database taken before a rotation opens with the key of that time.
Protect the data directory regardless of all the above; it is created with mode 0700. Anyone who can read it has the database and the key, and anyone with the Docker socket can read every application's environment from its containers.
What a server stores and where, what is encrypted with which key, what leaves it, and what is logged for how long, collected on one page for a security questionnaire: Where your data is.
Reporting a vulnerability
Do not open a public issue. Report privately, either way:
- Email security@shipwick.com
- GitHub private vulnerability reporting: Report a vulnerability. Only maintainers see it.
Helpful to include: the version (shipwick --version, or shipwick server status for the agent's), how the agent is run (the installer, a compose file of your own, a bare process), what an attacker needs to start with, and steps to reproduce. A proof of concept is welcome but not required.
What to expect:
- an acknowledgement within 3 days;
- an assessment, whether the report can be reproduced and how severe it is judged to be, within 10 days;
- a fix released before the details are published, and credit in the release notes unless you prefer otherwise. The disclosure date is agreed with the reporter.
There is no bug bounty. Only the latest release receives security fixes, released as the next patch of the latest minor; upgrading to it is one step from any 1.x. See Versions and compatibility.
What counts
Vulnerabilities:
- reaching the API, or the dashboard's session, without a valid token;
- a token doing what its role or its application limit does not allow, or working after it expired;
- signing in through the provider without a rule that admits the person, or a session that outlives its rule;
- recovering a token, the encryption key or an application's environment values from logs, API responses, error messages, the dashboard, or files readable by others; or reading environment values from a copy of the database without the key;
- input in
deploy.yamlor an API request that executes something on the server itself, escapes the fields it belongs to (proxy configuration, container names, file paths, logging options), or yields a privileged container, a host mount, or a published host port thatpublishdid not ask for; - an application container that can reconfigure the proxy, reach the agent's data, or claim a hostname or a server port held by another application;
- the CLI sending a saved token somewhere other than the agent it was saved for;
- the installer, or
shipwick upgrade, fetching or running something it did not verify; - a file or an image that verifies as signed by this repository's release workflow and was not produced by it, or a way to make the installer or
shipwick upgradeaccept a signature that is not that workflow's; see Signed releases.
Expected behavior, not vulnerabilities:
- a holder of a
deployoradmintoken running arbitrary images and commands inside containers, reading environment values of containers through Docker, or otherwise controlling the server; - anyone with access to the Docker socket — the filtered one the agent holds included, since a request to create a container passes it — the agent's data directory or Caddy's admin socket doing the same; what refuses that request is Docker's authorization plugin, which The Docker socket describes and the installer does not set up;
- root on the server reading
encryption.key, ordocker inspectshowing a running container's environment; - a port published with
publishbeing reachable despite the host firewall; - exposing port 9000 to the internet against the documentation's advice;
- an installation without cosign going by the release's checksums alone: the installer says so, and
SHIPWICK_REQUIRE_SIGNATURE=1refuses instead.
If you are unsure which list something belongs to, report it privately anyway.