swarmexec › Docs › Security scan & report
Security scan & report_
A gate before stack deploy, and a report of the whole cluster.
On this page
stack deploy — apply a stack file, after checking it
Loads a stack file, runs the security checks over what it would
actually deploy, and applies it. What makes this worth having over
docker stack deploy is the gate: the file is checked
before anything is created, and if something above informational
is found the deploy stops and asks.
Checking without deploying. stack check <file> [stack]
runs the same checks and stops: exit 0 when nothing above
informational was found, 1 when the deploy would stop — the
form for a pipeline. It is stack deploy --check under its own name
(the MCP tool is stack_check), and security check is the
same command again, for whoever looks for it under security.
In the TUI, E → deploy a file does the same: the findings are shown first, d proceeds, Esc walks away. Nothing has been created at that point, which is the whole purpose of the pause.
The checks are not a second set of rules. The file is converted
into the very ServiceSpec values the deploy would submit, and the
existing eight analyzers run on those — the same checks that put
a shield in the tree, fill the ! overlay and the security report. Two
sets would drift: a rule tightened in one place and not the other means the gate
passes a file that the tree flags the moment it is running, and an operator who
was told “nothing found” was told something false. It also means the
checks see what the cluster will do, not what the file
says — compose's defaults and shorthands sit in between.
--yes does not mean “ignore the findings”. It means
“do not ask”, and a run that finds something above informational still
refuses and exits non-zero. Anything else would turn the gate
into a formality the first time someone put it in CI. To deploy despite findings
you have to say --despite-findings, which is a different thing to type and a
different thing to explain afterwards. A non-interactive run with no answer on
stdin counts as no.
| Flag | Description |
|---|---|
--check | run the checks and stop, like stack check. Exits 1 if anything above informational was found, so it gates a pipeline |
-y, --yes | do not ask. Deploys when the checks are clean; refuses when they are not |
--despite-findings | deploy despite findings, without asking. Was --force, which still works |
--prune | remove services of the stack the file no longer declares. Off by default, as in docker: a file that is a subset of the stack is far more often an accident than an instruction to delete |
What a deploy does, in order: networks, then secrets, then
configs, then services — a service that references something not yet there fails,
and the stack is left half-applied. External networks are checked
first, because one that does not exist is the most common way a
deploy stops halfway. An existing secret is never overwritten: a
secret's value is immutable in swarm, so changing one means creating a new one
under a new name — or rotating it under the same one with
secret rotate. If a deploy does fail partway, what had already been applied is
reported alongside the error rather than left to be guessed at.
security report — a Markdown report for the whole cluster
The security-risks overlay scans service specs and shows the
result on screen. This writes the same scan — plus the checks that belong to the
cluster rather than to any one service — as Markdown, so it can be
reviewed away from the terminal, attached to a ticket, or committed next to your
stack files and diffed release over release. It goes to stdout
unless -o is given, so it pipes as readily as it saves.
Six checks run at the cluster level, none of which a service spec can answer for:
| Check | Severity | What it flags |
|---|---|---|
network-unencrypted — “overlay traffic is not encrypted” | medium | an overlay network carrying service traffic without data-plane encryption. Swarm tunnels container traffic between nodes over VXLAN in the clear unless the network was created with --opt encrypted, and nothing about the running service looks any different either way. Networks with nothing attached are not flagged — they carry nothing — and neither is ingress, which cannot be encrypted at all, so a finding on it could never be cleared |
autolock-disabled — “managers are not autolocked” | medium | the managers' raft store is not encrypted at rest. It holds every secret, every config and the cluster CA key, and its key sits on the same disk — so a manager's disk yields the lot. Enable with docker swarm update --autolock=true and keep the unlock key: a restarted manager will ask for it. If the swarm configuration cannot be read, the report says autolock-unknown rather than guessing — assuming “off” would invent a finding and assuming “on” would be a false all-clear |
agent-proto-mismatch / agent-version-skew / agent-too-old / agent-unreachable | high / medium / low | the agent is what enforces authorization on every exec, log and port-forward, so one older than your client may not enforce a rule the client assumes. A protocol mismatch is high and outranks a version difference: the two ends disagree about the contract itself, not merely about which build implements it. An agent that did not answer is reported as a gap, not as a pass. Skew is not reported for an unreleased (dev) client, which differs from every released agent by construction — the same exemption doctor makes |
pinned-overlay-address — “overlay address written into the configuration” | high | a service whose spec names a literal IP that belongs to one of the swarm's own overlay networks — in an environment variable, a command, an argument or a label. Overlay addresses are not stable: Docker assigns them when the network is created, and anything that recreates it (a changed MTU option, a changed subnet, a stack redeployed from a file) hands out different ones. A service that names an alias is unaffected; one that names an address fails to reach it with “no route to host” at startup, long after the change that caused it. Only the swarm's own subnets count — a public IP, a loopback, the office LAN and the node's own underlay address are all legitimate things to write down, and a version string is not read as an address |
unused-secret / unused-config | low | a secret or config no service references. It is still distributed through the raft store and still readable by anything that reaches a manager — usually a credential someone rotated and never removed, which means the old value is still live in the cluster long after everyone believes it is gone |
What the report says about itself. It is read away from the terminal, by someone who was not there when it ran, so it carries its own context: which cluster, when, and with which build. It also has a Not covered section — unreachable agents, an unreadable swarm configuration, an empty node list — because silence in a security report reads as an all-clear for ground it never reached. The ordering depends only on the findings, so two reports of an unchanged cluster differ only in their timestamp and can be diffed against each other; that is worth having only because an absent finding means not found and never not looked at.
The file is written 0600, creating any parent
directories 0700. It names every service, network and secret in the
cluster together with every weakness found in it — that is a map of where to
attack, and it has no business being readable by every account on the machine.
| Flag | Default | Description |
|---|---|---|
-o, --output | stdout | write to this file instead of stdout |
--connect-timeout | 10s | per-node connect timeout when checking agents |
--skip-agents | false | do not contact the node agents. Faster, and agent skew is then listed under Not covered rather than silently omitted |
The same report can be written from the TUI: press w in the security-risks overlay. It is a fresh cluster-wide gather, not a dump of what the overlay is showing, and it runs off the ui goroutine so the interface stays responsive while it talks to every node.