Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Prefer authenticated and direct-loopback configuration recovery

pulse-triage[bot]5098e7d63588
diff --git a/SECURITY.md b/SECURITY.md
index cfd378ace0..8fb9588f40 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -293,32 +293,50 @@ and import have different permissions; a successful public health check does
not establish either. Prefer the signed-in UI and keep the encrypted export and
its passphrase separate and private.
-### Option 1: Create an API Token (Recommended)
-Create a dedicated token in **API Access** with `settings:read` for export, or
-`settings:write` for import. Use the [private-file export example](#usage) below;
-do not paste a token or export passphrase into a command. An organization-bound
-token can transfer only its selected organization, not the whole instance.
-
-### Option 2: Allow Unprotected Export (Homelab)
-```bash
-# Using systemd
-sudo systemctl edit pulse
-# Add:
-[Service]
-Environment="ALLOW_UNPROTECTED_EXPORT=true"
-
-# Docker: set ALLOW_UNPROTECTED_EXPORT=true in the existing deployment's
-# environment, without changing its image, data volumes or other settings.
-```
-
-This exception applies only when Pulse has no configured authentication and
-only to configuration export. It never enables import and never overrides
-password, proxy, API-token, SSO, or hosted authentication. Without the
-exception, unauthenticated export and import recovery is limited to a direct
-loopback connection; private-network and forwarded requests are not loopback.
-
-**Note:** for production, prefer Docker secrets or systemd environment files
-for sensitive data.
+### Use existing authorised access
+
+For a browser transfer, use an instance administrator in the default
+organisation, or an owner/admin of the selected tenant. A viewer or editor
+session is not enough. A trusted-proxy identity also needs administrator
+authority. Check the [organisation and access requirements](docs/MIGRATION.md#confirm-organisation-and-access)
+before exporting or replacing settings.
+
+For automation, create a dedicated token in **API Access** with `settings:read`
+for export, or `settings:write` for import. Use the [private-file export
+example](#usage) below; do not paste a token or export passphrase into a command.
+An organization-bound token can transfer only its selected organization, not
+the whole instance. Signing in as an administrator does not enlarge an
+explicitly supplied token's scopes or organisation binding.
+
+### Recover an installation with no authentication
+
+Only when Pulse has **no configured authentication**, configuration export and
+import can use a direct loopback connection without enabling a network-wide
+exception. The request must reach Pulse directly inside the server's own
+network namespace. A private LAN address, reverse proxy, forwarded request or
+your laptop's `localhost` is not that connection. Do not change network
+exposure or remove working authentication to make recovery possible.
+
+If authentication is configured but you cannot sign in, follow the
+[deployment-specific access recovery guide](docs/TROUBLESHOOTING.md#i-forgot-my-password).
+Loopback does not bypass password, proxy, API-token, SSO or hosted
+authentication. Keep the existing deployment, data and credentials intact.
+
+### Existing unprotected-export exception
+
+`ALLOW_UNPROTECTED_EXPORT=true` is an **export only** exception for an
+installation with no configured authentication. It permits export beyond
+direct loopback: **anyone who can reach the export endpoint can choose their
+own passphrase and receive the configuration, including provider and SSO
+secrets**. Export encryption does not authenticate the caller, and a homelab
+or private network is not an access-control boundary.
+
+Prefer the authorised or direct-loopback routes above; do not enable this
+exception just to clear an export error. It never enables import and never
+overrides configured authentication. If it is already enabled, review its
+exposure privately and remove it from the existing deployment's managed
+configuration when no longer needed, without replacing the installation or
+discarding state. Do not test exposure by making a public export.
## Security Features Summary
@@ -844,7 +862,7 @@ JSON
## Troubleshooting
**Account locked?** Wait 15 minutes or contact admin for manual reset
-**Export blocked?** Authenticate with management authority, use a correctly scoped API token, connect directly over loopback on a no-auth installation, or deliberately set `ALLOW_UNPROTECTED_EXPORT=true` for export only<br>
+**Export blocked?** Check the [transfer access and direct-loopback requirements](#exportimport-protection). Do not enable unprotected network export just to clear an error.<br>
**Rate limited?** Wait 1 minute and try again
**Can't login?** Check `PULSE_AUTH_USER` and `PULSE_AUTH_PASS` environment variables
**API access denied?** Verify the token you supplied matches one of the values created in *Settings → API Tokens* (use the original token, not the hash)
diff --git a/frontend-modern/public/docs/SECURITY.md b/frontend-modern/public/docs/SECURITY.md
index cfd378ace0..8fb9588f40 100644
--- a/frontend-modern/public/docs/SECURITY.md
+++ b/frontend-modern/public/docs/SECURITY.md
@@ -293,32 +293,50 @@ and import have different permissions; a successful public health check does
not establish either. Prefer the signed-in UI and keep the encrypted export and
its passphrase separate and private.
-### Option 1: Create an API Token (Recommended)
-Create a dedicated token in **API Access** with `settings:read` for export, or
-`settings:write` for import. Use the [private-file export example](#usage) below;
-do not paste a token or export passphrase into a command. An organization-bound
-token can transfer only its selected organization, not the whole instance.
-
-### Option 2: Allow Unprotected Export (Homelab)
-```bash
-# Using systemd
-sudo systemctl edit pulse
-# Add:
-[Service]
-Environment="ALLOW_UNPROTECTED_EXPORT=true"
-
-# Docker: set ALLOW_UNPROTECTED_EXPORT=true in the existing deployment's
-# environment, without changing its image, data volumes or other settings.
-```
-
-This exception applies only when Pulse has no configured authentication and
-only to configuration export. It never enables import and never overrides
-password, proxy, API-token, SSO, or hosted authentication. Without the
-exception, unauthenticated export and import recovery is limited to a direct
-loopback connection; private-network and forwarded requests are not loopback.
-
-**Note:** for production, prefer Docker secrets or systemd environment files
-for sensitive data.
+### Use existing authorised access
+
+For a browser transfer, use an instance administrator in the default
+organisation, or an owner/admin of the selected tenant. A viewer or editor
+session is not enough. A trusted-proxy identity also needs administrator
+authority. Check the [organisation and access requirements](docs/MIGRATION.md#confirm-organisation-and-access)
+before exporting or replacing settings.
+
+For automation, create a dedicated token in **API Access** with `settings:read`
+for export, or `settings:write` for import. Use the [private-file export
+example](#usage) below; do not paste a token or export passphrase into a command.
+An organization-bound token can transfer only its selected organization, not
+the whole instance. Signing in as an administrator does not enlarge an
+explicitly supplied token's scopes or organisation binding.
+
+### Recover an installation with no authentication
+
+Only when Pulse has **no configured authentication**, configuration export and
+import can use a direct loopback connection without enabling a network-wide
+exception. The request must reach Pulse directly inside the server's own
+network namespace. A private LAN address, reverse proxy, forwarded request or
+your laptop's `localhost` is not that connection. Do not change network
+exposure or remove working authentication to make recovery possible.
+
+If authentication is configured but you cannot sign in, follow the
+[deployment-specific access recovery guide](docs/TROUBLESHOOTING.md#i-forgot-my-password).
+Loopback does not bypass password, proxy, API-token, SSO or hosted
+authentication. Keep the existing deployment, data and credentials intact.
+
+### Existing unprotected-export exception
+
+`ALLOW_UNPROTECTED_EXPORT=true` is an **export only** exception for an
+installation with no configured authentication. It permits export beyond
+direct loopback: **anyone who can reach the export endpoint can choose their
+own passphrase and receive the configuration, including provider and SSO
+secrets**. Export encryption does not authenticate the caller, and a homelab
+or private network is not an access-control boundary.
+
+Prefer the authorised or direct-loopback routes above; do not enable this
+exception just to clear an export error. It never enables import and never
+overrides configured authentication. If it is already enabled, review its
+exposure privately and remove it from the existing deployment's managed
+configuration when no longer needed, without replacing the installation or
+discarding state. Do not test exposure by making a public export.
## Security Features Summary
@@ -844,7 +862,7 @@ JSON
## Troubleshooting
**Account locked?** Wait 15 minutes or contact admin for manual reset
-**Export blocked?** Authenticate with management authority, use a correctly scoped API token, connect directly over loopback on a no-auth installation, or deliberately set `ALLOW_UNPROTECTED_EXPORT=true` for export only<br>
+**Export blocked?** Check the [transfer access and direct-loopback requirements](#exportimport-protection). Do not enable unprotected network export just to clear an error.<br>
**Rate limited?** Wait 1 minute and try again
**Can't login?** Check `PULSE_AUTH_USER` and `PULSE_AUTH_PASS` environment variables
**API access denied?** Verify the token you supplied matches one of the values created in *Settings → API Tokens* (use the original token, not the hash)
diff --git a/scripts/tests/test_security_docs.py b/scripts/tests/test_security_docs.py
index 6e63099aab..77ba7e988d 100644
--- a/scripts/tests/test_security_docs.py
+++ b/scripts/tests/test_security_docs.py
@@ -252,6 +252,37 @@ class SecurityDocsTest(unittest.TestCase):
self.assertIn(boundary, guide)
self.assertNotIn("### What's **Not** Encrypted", guide)
+ def test_transfer_recovery_does_not_recommend_a_network_export_bypass(self):
+ source = DOC.read_text()
+ transfer = source.split("## Export/Import Protection\n", 1)[1].split("\n## ", 1)[0]
+ guide = " ".join(transfer.split())
+ for boundary in ("instance administrator", "owner/admin", "viewer or editor",
+ "trusted-proxy identity", "explicitly supplied token",
+ "no configured authentication", "direct loopback",
+ "server's own network namespace", "your laptop's `localhost`",
+ "Do not change network exposure or remove working authentication",
+ "anyone who can reach the export endpoint",
+ "own passphrase", "provider and SSO secrets",
+ "Export encryption does not authenticate the caller",
+ "private network is not an access-control boundary",
+ "never enables import", "never overrides configured authentication",
+ "Do not test exposure by making a public export"):
+ self.assertIn(boundary, guide)
+ self.assertLess(transfer.index("### Use existing authorised access"),
+ transfer.index("### Recover an installation with no authentication"))
+ self.assertLess(transfer.index("### Recover an installation with no authentication"),
+ transfer.index("### Existing unprotected-export exception"))
+ self.assertIn("docs/MIGRATION.md#confirm-organisation-and-access", transfer)
+ self.assertIn("docs/TROUBLESHOOTING.md#i-forgot-my-password", transfer)
+ # Keep the supported exception visible, but never as a copyable
+ # deployment recipe or a shortcut in the troubleshooting summary.
+ for block in blocks():
+ self.assertNotIn("ALLOW_UNPROTECTED_EXPORT", block)
+ summary = source.split("**Export blocked?**", 1)[1].split("\n", 1)[0]
+ self.assertIn("#exportimport-protection", summary)
+ self.assertNotIn("ALLOW_UNPROTECTED_EXPORT", summary)
+ self.assertNotIn("Allow Unprotected Export (Homelab)", source)
+
def test_encrypted_file_examples_match_the_actual_store_and_data_path(self):
guide = " ".join(DOC.read_text().split())
persistence = (ROOT / "internal/config/persistence.go").read_text()