Portainer 2.44 Security and Bootstrap Tokens: Secure First Run and Existing Installs
Tech GuruPortainer is a management plane. If it can control Docker, agents, stacks, volumes, secrets, or remote endpoints, then first-run setup and admin recovery behavior deserve the same care as a firewall or identity provider.
Quick Answer
Keep Portainer reachable only through trusted administrative paths, including during first run and recovery. The cited setup-takeover advisory was fixed in 2.39.4 and 2.43.0; 2.44.0 later improved token visibility in logs. For a new instance, verify token-protected setup or deliberate administrator provisioning. For an existing instance, preserve its data, upgrade through the supported procedure, and audit access. Updating alone cannot undo a prior takeover.
Baseline
Identify the server edition, version, data volume, agents, and every route to the management UI or API.
Change
Restrict access before first run or upgrade, and use the vendor-supported release path.
Validate
Check expected users and environments, limited-user denials, and setup behavior only on a disposable isolated instance.
Operate
Protect management backups, monitor administrative changes, and recheck advisories before future upgrades.
What the Advisory Actually Covers
GHSA-x626-fcwx-f5pc / CVE-2026-55761 describes takeover through restore or first-administrator creation before initialization. The attacker must be able to reach an uninitialized instance during its five-minute setup window. Restarting an uninitialized instance opens another window. An already initialized instance is not in that same state, but an unauthorized account created earlier remains a separate incident concern.
| Release line in the advisory | Affected range | First fixed release for this issue |
|---|---|---|
| 2.39.x LTS | 2.39.0 through versions before 2.39.4 | 2.39.4 |
| STS range | 2.40.0 through versions before 2.43.0 | 2.43.0 |
| Older end-of-life releases | Not a safe exception: the advisory says the path predates these ranges. | Move to a supported branch; do not infer an old-version fix. |
The 2.44.0 release notes say the token became easier to spot in installation logs. They also list fixes involving leftover service accounts and path traversal in the Swarm compose deployer. These are reasons to review the full release history, not evidence that the setup-token fix first appeared in 2.44.0. Do not treat this versioned article as a recommendation to downgrade or as a claim that 2.44.0 is today's newest release.
Secure a New Installation
- Before starting Portainer, restrict management access at the host and network boundaries. Check direct published ports as well as any reverse proxy or tunnel. HTTPS protects transport; it does not by itself restrict who can reach initialization.
- Select the intended CE or BE image and an explicitly reviewed version through the vendor's installation guidance. Record the image and persistent data location. Do not expose setup to the internet while looking for the administrator password.
- If no administrator was provisioned in advance, obtain the setup token through authorized access to the server logs and enter it in the setup form. Treat log access and log exports as sensitive while initialization is pending.
- Create the intended administrator or restore an approved management backup. Review the resulting account and environment lists before connecting real workloads.
- Retain private management access after setup. Test from an authorized workstation and from a network that should be denied; check IPv6 and alternate proxy paths as well as the usual IPv4 URL.
Unperformed Docker Standalone example: on the host running Portainer, this reads logs for a container named portainer. Substitute the actual server container name. Look for setup_token= as described in the setup-token documentation. Do not paste the logs or token into a public issue, screenshot, or article.
docker logs portainerA deployment that supplies the administrator password at startup does not require a setup token. Follow the CLI documentation carefully: --admin-password takes the documented password hash, whereas --admin-password-file points to a file containing the password. Protect the secret in your deployment system and do not commit it to a compose file or repository. A deliberately configured --setup-token is also a secret.
Do not add --no-setup-token merely to get past a failed setup screen. If setup times out, first verify isolation, then restart the uninitialized instance through the normal administration path and retrieve the applicable token. If an existing production installation unexpectedly asks for first-run setup, stop: check whether the intended data volume is mounted before creating another administrator.
Upgrade an Existing Installation Without Losing State
Inventory the server edition and version, agents, environments, registry and Git integrations, reverse proxies, and the persistent data mount. Save the deployment manifest and take a protected Portainer backup before changing the server. Use the edition-specific Docker upgrade procedure or the corresponding guide for your platform; verify the required server/agent compatibility instead of assuming that replacing one container updates everything.
A Portainer backup is not a backup of the applications it manages. The vendor's backup scope includes management state and stack definitions, but excludes workload containers, images, volumes, and application data. Back up databases and persistent application storage separately. Restrict backup access because management state includes users, access controls, and integration credentials.
After the upgrade, confirm the running version rather than only the requested image tag. Check that the original users, teams, endpoints, and stacks are present. An endpoint showing disconnected is not a reason to open its agent port to the internet: check the documented agent version, routing, certificates, and firewall rules from the server's actual network path.
Checks That Establish the Intended Boundary
| Check | What to look for | What it does not establish |
|---|---|---|
| Initialized production instance | Normal login and expected users; no unexpected return to first-run setup. | That initialization was never exploited in the past. |
| Limited user on a disposable workload | Only explicitly assigned environments and actions are allowed. | That all roles or all integrations have been tested. |
| Untrusted network path | UI/API and agent ports are unreachable except for deliberately authorized services. | That trusted administrators or their devices are safe. |
| Isolated fresh test instance | Missing/wrong token is refused and intended setup succeeds, unless an admin was deliberately provisioned at startup. | That another release, proxy configuration, or flag set behaves identically. |
The token test above is an unperformed acceptance procedure. Use a disposable instance with no production Docker socket, credentials, or reachable environments. Never delete production data or reset its administrator just to re-create first-run conditions. A failed setup request is not conclusive unless you establish that it reached the intended fresh instance rather than a proxy denial or an already initialized database.
If Portainer May Already Have Been Claimed
Restrict access and preserve the database, logs, and deployment details for investigation. Review unknown administrators, API keys, role changes, unexpected stacks, scheduled jobs, images, and connected environments. Resetting the visible administrator password is not enough if additional accounts or host-level persistence remain. Review exposed registry, Git, cloud, and environment credentials at their issuers from a clean administrative device.
Portainer's reach matters: Docker daemon access is a high-trust capability, and a compromised management account may have affected the underlying hosts. Investigate those environments before trusting a management backup. If compromise is suspected, use isolated recovery and reviewed rebuilds rather than reconnecting a restored Portainer instance to every production endpoint at once.
Recovery and Rollback
The backup/restore documentation restores management state during setup of a fresh instance with an empty data volume. Practice with a copy on an isolated host; block its routes to live agents and omit the production Docker socket. Otherwise the test instance could become a second controller for real systems. Keep the original data volume and backup untouched.
If an upgrade fails, use the documented rollback procedure for the relevant release and database state. Do not assume an older binary can safely open an upgraded database. If rollback returns to an affected version, keep access restricted while planning a supported recovery; restoring availability does not remove the vulnerability.
Evidence and Next Action
These are documentation-backed checks, not results from a Portainer installation or exploit test. Start by recording the running release, whether the instance is initialized, and every network path to its management API. Then choose the new-install, upgrade, or incident-response path above. Recheck current advisories and supported releases before making a production change.
