swarmexec

swarmexec › Docs › Security scan & report

Security scan & report_

A gate before stack deploy, and a report of the whole cluster.

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.

swarmexec stack deploy web.yml # asks if anything is found swarmexec stack check web.yml # only check, never deploy swarmexec stack deploy web.yml --despite-findings # deliberately

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.

FlagDescription
--checkrun the checks and stop, like stack check. Exits 1 if anything above informational was found, so it gates a pipeline
-y, --yesdo not ask. Deploys when the checks are clean; refuses when they are not
--despite-findingsdeploy despite findings, without asking. Was --force, which still works
--pruneremove 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.

swarmexec security report -o security.md

Six checks run at the cluster level, none of which a service spec can answer for:

CheckSeverityWhat it flags
network-unencrypted — “overlay traffic is not encrypted”mediuman 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”mediumthe 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-unreachablehigh / medium / lowthe 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”higha 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-configlowa 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.

FlagDefaultDescription
-o, --outputstdoutwrite to this file instead of stdout
--connect-timeout10sper-node connect timeout when checking agents
--skip-agentsfalsedo 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.