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.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
State credential encryption and log-disclosure limits accurately
pulse-triage[bot]c3ec820087c9
diff --git a/SECURITY.md b/SECURITY.mdindex 6d5ce3bc82..2c73a2e3ff 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -175,12 +175,12 @@ Pulse includes a non-intrusive security warning system that helps youunderstand your security posture.### Security Score-Your instance receives a score from 0‑5 based on:-- ✅ Credentials encrypted at rest (always enabled)-- ✅ Export/import protection-- ⚠️ Authentication enabled-- ⚠️ HTTPS connection-- ⚠️ Audit logging++**Settings → Security → Overview** summarises authentication methods,+API-token configuration, export protection, HTTPS and audit logging. These+indicators describe configuration checks, not a complete security audit. A+strong score does not establish that every file is encrypted, a backup is safe+to share, or stored credentials can be recovered without their encryption key.### Dismissing WarningsIf you're comfortable with your security setup, you can dismiss warnings:@@ -191,21 +191,61 @@ If you're comfortable with your security setup, you can dismiss warnings:## Credential Security### Encrypted at Rest (AES-256-GCM)-- **Node credentials**: passwords and API tokens (`/etc/pulse/nodes.enc`)-- **Email settings**: SMTP passwords (`/etc/pulse/email.enc`)-- **Webhook data**: URLs and auth headers (`/etc/pulse/webhooks.enc`)-- **Encryption key**: auto-generated (`/etc/pulse/.encryption.key`)++Pulse encrypts configuration saved through its credential store. Examples in+the **active data directory** include:++| Stored configuration | File |+| --- | --- |+| Proxmox VE, PBS and PMG connection credentials | `nodes.enc` |+| SMTP settings, including passwords | `email.enc` |+| Webhook URLs and authentication headers | `webhooks.enc` |+| TrueNAS and vSphere connection credentials | `truenas.enc`, `vmware.enc` |+| AI provider credentials and SSO configuration | `ai.enc`, `sso.enc` |++The directory is normally `/etc/pulse` for systemd or `/data` inside Docker;+`PULSE_DATA_DIR` and deployment configuration can select another location.+Use the existing deployment's actual data path, not an assumed default.++### Encryption scope and recovery++The auto-generated **`.encryption.key`** is stored alongside these files. It+is key material, not an encrypted credential file. Anyone with the encrypted+files **and their matching key** can decrypt them. Protect the entire data+directory, mounted volume and recovery copies; encryption does not protect+against an account or process that can read both. Pulse protects its key file+with owner-only permissions (`0600`, with a `0700` parent directory); preserve+the intended service ownership rather than granting wider access to fix a read+failure.++This is not whole-directory or whole-disk encryption. Deployment environment+files, service definitions, agent token files, logs and history can still+contain secrets or identifying details. Quick Security Setup saves a bcrypt+password hash, but hashing an externally supplied plaintext `PULSE_AUTH_PASS`+for use does not rewrite its original deployment source. Keep hashes and raw+client credentials private too; see [private authentication configuration](docs/CONFIGURATION.md#private-docker-authentication-file).++Keep encrypted files and their matching key together in a **private recovery+backup**, not in a public attachment. Do not delete or regenerate the key, mix+files from different instances, or reset the data directory to repair a+decryption error. Preserve the existing files and reconcile the data path and+matching backup first. A file copy alone is not verified recovery; follow the+[server migration and restore guidance](docs/MIGRATION.md).### Security Features-- **Logs**: token values masked with `***` in all outputs+- **Logs**: targeted masking and redaction are not a guarantee that every+ output is safe to share. Free-text errors and historical records can contain+ secrets or private details. Review excerpts locally; follow+ [safe diagnostics collection](docs/TROUBLESHOOTING.md#collect-diagnostics-safely)+ and the [log-sharing precautions](docs/TROUBLESHOOTING.md#inspect-notification-logs).- **API**: ordinary configuration reads redact stored credentials; newly issuedtokens are deliberately revealed for their owner to save securely- **Export**: requires authentication (session, proxy auth, or `X-API-Token`header) to extract credentials- **Migration**: use passphrase-protected export/import (see[Migration Guide](docs/MIGRATION.md))-- **Auto-migration**: unencrypted configs automatically migrate to encrypted- format+- **Auto-migration**: supported legacy credential files migrate when loaded;+ this does not scrub earlier backups or external deployment configuration## Export/Import Protection@@ -244,7 +284,8 @@ for sensitive data.## Security Features Summary### Core Protection-- **Encryption**: credentials encrypted at rest (AES-256-GCM)+- **Encryption**: credential-store files use AES-256-GCM, within the+ [scope and recovery limits](#encryption-scope-and-recovery) above- **Export protection**: exports always encrypted with a passphrase- **Minimum passphrase**: 12 characters required for exports- **Security tab**: check status in *Settings → Security → Overview*@@ -252,14 +293,16 @@ for sensitive data.### Advanced Security (When Authentication Enabled)- **Password security**- Bcrypt hashing with cost factor 12 (60‑character hash)- - Passwords never stored in plain text+ - Quick Security Setup persists the hash, not the password; external+ deployment sources remain separately managed- Automatic hashing during security setup- **Critical**: bcrypt hashes must be exactly 60 characters- **API token security**- 64‑character hex tokens (32 bytes entropy)- SHA3-256 hashed before storage (64‑character hash)- Raw token shown only once- - Tokens never stored in plain text+ - Pulse-issued token records store verification hashes; raw client and agent+ token copies must remain private- Stored in `api_tokens.json` and managed via the UI- API-only mode supported (no password auth required)- **CSRF protection**: session-authenticated state changes require CSRF tokens;diff --git a/frontend-modern/public/docs/SECURITY.md b/frontend-modern/public/docs/SECURITY.mdindex 6d5ce3bc82..2c73a2e3ff 100644--- a/frontend-modern/public/docs/SECURITY.md+++ b/frontend-modern/public/docs/SECURITY.md@@ -175,12 +175,12 @@ Pulse includes a non-intrusive security warning system that helps youunderstand your security posture.### Security Score-Your instance receives a score from 0‑5 based on:-- ✅ Credentials encrypted at rest (always enabled)-- ✅ Export/import protection-- ⚠️ Authentication enabled-- ⚠️ HTTPS connection-- ⚠️ Audit logging++**Settings → Security → Overview** summarises authentication methods,+API-token configuration, export protection, HTTPS and audit logging. These+indicators describe configuration checks, not a complete security audit. A+strong score does not establish that every file is encrypted, a backup is safe+to share, or stored credentials can be recovered without their encryption key.### Dismissing WarningsIf you're comfortable with your security setup, you can dismiss warnings:@@ -191,21 +191,61 @@ If you're comfortable with your security setup, you can dismiss warnings:## Credential Security### Encrypted at Rest (AES-256-GCM)-- **Node credentials**: passwords and API tokens (`/etc/pulse/nodes.enc`)-- **Email settings**: SMTP passwords (`/etc/pulse/email.enc`)-- **Webhook data**: URLs and auth headers (`/etc/pulse/webhooks.enc`)-- **Encryption key**: auto-generated (`/etc/pulse/.encryption.key`)++Pulse encrypts configuration saved through its credential store. Examples in+the **active data directory** include:++| Stored configuration | File |+| --- | --- |+| Proxmox VE, PBS and PMG connection credentials | `nodes.enc` |+| SMTP settings, including passwords | `email.enc` |+| Webhook URLs and authentication headers | `webhooks.enc` |+| TrueNAS and vSphere connection credentials | `truenas.enc`, `vmware.enc` |+| AI provider credentials and SSO configuration | `ai.enc`, `sso.enc` |++The directory is normally `/etc/pulse` for systemd or `/data` inside Docker;+`PULSE_DATA_DIR` and deployment configuration can select another location.+Use the existing deployment's actual data path, not an assumed default.++### Encryption scope and recovery++The auto-generated **`.encryption.key`** is stored alongside these files. It+is key material, not an encrypted credential file. Anyone with the encrypted+files **and their matching key** can decrypt them. Protect the entire data+directory, mounted volume and recovery copies; encryption does not protect+against an account or process that can read both. Pulse protects its key file+with owner-only permissions (`0600`, with a `0700` parent directory); preserve+the intended service ownership rather than granting wider access to fix a read+failure.++This is not whole-directory or whole-disk encryption. Deployment environment+files, service definitions, agent token files, logs and history can still+contain secrets or identifying details. Quick Security Setup saves a bcrypt+password hash, but hashing an externally supplied plaintext `PULSE_AUTH_PASS`+for use does not rewrite its original deployment source. Keep hashes and raw+client credentials private too; see [private authentication configuration](docs/CONFIGURATION.md#private-docker-authentication-file).++Keep encrypted files and their matching key together in a **private recovery+backup**, not in a public attachment. Do not delete or regenerate the key, mix+files from different instances, or reset the data directory to repair a+decryption error. Preserve the existing files and reconcile the data path and+matching backup first. A file copy alone is not verified recovery; follow the+[server migration and restore guidance](docs/MIGRATION.md).### Security Features-- **Logs**: token values masked with `***` in all outputs+- **Logs**: targeted masking and redaction are not a guarantee that every+ output is safe to share. Free-text errors and historical records can contain+ secrets or private details. Review excerpts locally; follow+ [safe diagnostics collection](docs/TROUBLESHOOTING.md#collect-diagnostics-safely)+ and the [log-sharing precautions](docs/TROUBLESHOOTING.md#inspect-notification-logs).- **API**: ordinary configuration reads redact stored credentials; newly issuedtokens are deliberately revealed for their owner to save securely- **Export**: requires authentication (session, proxy auth, or `X-API-Token`header) to extract credentials- **Migration**: use passphrase-protected export/import (see[Migration Guide](docs/MIGRATION.md))-- **Auto-migration**: unencrypted configs automatically migrate to encrypted- format+- **Auto-migration**: supported legacy credential files migrate when loaded;+ this does not scrub earlier backups or external deployment configuration## Export/Import Protection@@ -244,7 +284,8 @@ for sensitive data.## Security Features Summary### Core Protection-- **Encryption**: credentials encrypted at rest (AES-256-GCM)+- **Encryption**: credential-store files use AES-256-GCM, within the+ [scope and recovery limits](#encryption-scope-and-recovery) above- **Export protection**: exports always encrypted with a passphrase- **Minimum passphrase**: 12 characters required for exports- **Security tab**: check status in *Settings → Security → Overview*@@ -252,14 +293,16 @@ for sensitive data.### Advanced Security (When Authentication Enabled)- **Password security**- Bcrypt hashing with cost factor 12 (60‑character hash)- - Passwords never stored in plain text+ - Quick Security Setup persists the hash, not the password; external+ deployment sources remain separately managed- Automatic hashing during security setup- **Critical**: bcrypt hashes must be exactly 60 characters- **API token security**- 64‑character hex tokens (32 bytes entropy)- SHA3-256 hashed before storage (64‑character hash)- Raw token shown only once- - Tokens never stored in plain text+ - Pulse-issued token records store verification hashes; raw client and agent+ token copies must remain private- Stored in `api_tokens.json` and managed via the UI- API-only mode supported (no password auth required)- **CSRF protection**: session-authenticated state changes require CSRF tokens;diff --git a/scripts/tests/test_security_docs.py b/scripts/tests/test_security_docs.pyindex d99520f756..1ac05485ed 100644--- a/scripts/tests/test_security_docs.py+++ b/scripts/tests/test_security_docs.py@@ -156,6 +156,54 @@ class SecurityDocsTest(unittest.TestCase):self.assertIn("docs/TROUBLESHOOTING.md#i-forgot-my-password", guide)self.assertNotIn("### What's **Not** Encrypted", guide)+ 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()+ crypto = (ROOT / "internal/crypto/crypto.go").read_text()+ for filename in ("nodes.enc", "email.enc", "webhooks.enc", "truenas.enc",+ "vmware.enc", "ai.enc", "sso.enc"):+ with self.subTest(filename=filename):+ self.assertIn(f'resolveLeaf("{filename}")', persistence)+ self.assertIn(f"`{filename}`", guide)+ self.assertRegex(crypto, r'encryptionKeyFileName\s*=\s*"\.encryption\.key"')+ for boundary in ("active data directory", "`PULSE_DATA_DIR`", "`/etc/pulse`",+ "`/data`", "existing deployment's actual data path"):+ self.assertIn(boundary, guide)+ self.assertNotIn("/etc/pulse/nodes.enc", guide)++ def test_key_scope_and_recovery_never_imply_safe_public_or_unmatched_copies(self):+ guide = " ".join(DOC.read_text().split())+ for boundary in ("stored alongside", "not an encrypted credential file",+ "matching key", "can decrypt", "entire data directory",+ "private recovery backup", "not in a public attachment",+ "owner-only", "0600", "0700", "service ownership",+ "Do not delete or regenerate the key", "mix files from different instances",+ "Preserve the existing files", "not verified recovery",+ "docs/MIGRATION.md"):+ self.assertIn(boundary, guide)++ def test_deployment_credentials_and_unencrypted_evidence_remain_private(self):+ guide = " ".join(DOC.read_text().split())+ for boundary in ("not whole-directory or whole-disk encryption",+ "environment files", "service definitions", "agent token files",+ "logs and history", "bcrypt", "plaintext `PULSE_AUTH_PASS`",+ "does not rewrite", "original deployment source",+ "hashes and raw client credentials private",+ "does not scrub earlier backups", "external deployment configuration"):+ self.assertIn(boundary, guide)+ for overclaim in ("Passwords never stored in plain text", "Tokens never stored in plain text",+ "Credentials encrypted at rest (always enabled)"):+ self.assertNotIn(overclaim, guide)++ def test_security_score_and_log_masking_are_not_disclosure_guarantees(self):+ guide = " ".join(DOC.read_text().split())+ for boundary in ("not a complete security audit", "every file is encrypted",+ "not a guarantee", "Free-text errors and historical records",+ "Review excerpts locally", "#collect-diagnostics-safely",+ "#inspect-notification-logs"):+ self.assertIn(boundary, guide)+ self.assertNotIn("token values masked with `***` in all outputs", guide)+if __name__ == "__main__":unittest.main()