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.

Make contribution reports safe before diagnostic collection

pulse-triage[bot]34ddb5829d37
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 573a53f7d2..40dd1e21aa 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -46,11 +46,31 @@ and installer tooling.
give the attempted version or release asset (or say "unknown") and identify
the installer or helper when known. Include an image tag or digest only for a
running container, not for a bare-metal or LXC install.
-- Include screenshots, redacted logs, API output, or diagnostics when they
- clarify the problem. If Pulse is running and it is safe to collect, use
- `Settings -> Diagnostics -> Export for GitHub (sanitized)` for connection or
- data failures. Never paste credentials, tokens, private keys, or a command
- line containing them into an issue.
+- Include only evidence relevant to the symptom: a screenshot or exact redacted
+ error may be enough for a visual problem; existing logs or observations may
+ explain a connection or data failure. Diagnostics are optional, not a condition
+ of reporting. If a result is already displayed in **Settings → Diagnostics**,
+ its download buttons reuse that result without running checks again.
+- **Run Diagnostics** can make live API and guest-agent requests. Do not run it
+ during a backup, freeze/thaw or an unresponsive-host incident just to file a
+ report. Keep the original evidence instead; a successful one-off check does
+ not prove that normal monitoring has recovered or a guest has thawed. See
+ [safe diagnostics collection](docs/TROUBLESHOOTING.md#collect-diagnostics-safely).
+- Diagnostics downloads save a local file, not an upload. Choose **GitHub (review
+ first)** (called **Export for GitHub (sanitized)** in older versions), and review
+ files and screenshots locally before posting: a sanitized export is not a
+ guarantee that free-text errors contain no private information. Remove
+ credentials, session cookies, secret URLs and private host, network or personal
+ details, including those echoed in errors. Keep **Full (private)** exports
+ private. Do not attach configuration or `.env` files, private keys, **Copy as
+ cURL** commands or full network exports. Never put credentials in a command
+ line, URL or thread.
+- For CPU, memory or disk-write reports, use existing readings or safe passive
+ observations. Where known, say whether they measure the Pulse process, its
+ container or the whole host, with units, measurement window and uptime.
+ Unavailable readings are valid evidence. Do not restart, create load or change
+ polling or retention just to measure; do not attach raw profiles, heap dumps,
+ databases or full process command lines.
- Lead with one primary bug or operator outcome. If the context also exposes
another actionable topic, put it in the issue form's dedicated field. Triage
will preserve it with a linked disposition; you do not need to refile text
diff --git a/frontend-modern/public/docs/CONTRIBUTING.md b/frontend-modern/public/docs/CONTRIBUTING.md
index 573a53f7d2..40dd1e21aa 100644
--- a/frontend-modern/public/docs/CONTRIBUTING.md
+++ b/frontend-modern/public/docs/CONTRIBUTING.md
@@ -46,11 +46,31 @@ and installer tooling.
give the attempted version or release asset (or say "unknown") and identify
the installer or helper when known. Include an image tag or digest only for a
running container, not for a bare-metal or LXC install.
-- Include screenshots, redacted logs, API output, or diagnostics when they
- clarify the problem. If Pulse is running and it is safe to collect, use
- `Settings -> Diagnostics -> Export for GitHub (sanitized)` for connection or
- data failures. Never paste credentials, tokens, private keys, or a command
- line containing them into an issue.
+- Include only evidence relevant to the symptom: a screenshot or exact redacted
+ error may be enough for a visual problem; existing logs or observations may
+ explain a connection or data failure. Diagnostics are optional, not a condition
+ of reporting. If a result is already displayed in **Settings → Diagnostics**,
+ its download buttons reuse that result without running checks again.
+- **Run Diagnostics** can make live API and guest-agent requests. Do not run it
+ during a backup, freeze/thaw or an unresponsive-host incident just to file a
+ report. Keep the original evidence instead; a successful one-off check does
+ not prove that normal monitoring has recovered or a guest has thawed. See
+ [safe diagnostics collection](docs/TROUBLESHOOTING.md#collect-diagnostics-safely).
+- Diagnostics downloads save a local file, not an upload. Choose **GitHub (review
+ first)** (called **Export for GitHub (sanitized)** in older versions), and review
+ files and screenshots locally before posting: a sanitized export is not a
+ guarantee that free-text errors contain no private information. Remove
+ credentials, session cookies, secret URLs and private host, network or personal
+ details, including those echoed in errors. Keep **Full (private)** exports
+ private. Do not attach configuration or `.env` files, private keys, **Copy as
+ cURL** commands or full network exports. Never put credentials in a command
+ line, URL or thread.
+- For CPU, memory or disk-write reports, use existing readings or safe passive
+ observations. Where known, say whether they measure the Pulse process, its
+ container or the whole host, with units, measurement window and uptime.
+ Unavailable readings are valid evidence. Do not restart, create load or change
+ polling or retention just to measure; do not attach raw profiles, heap dumps,
+ databases or full process command lines.
- Lead with one primary bug or operator outcome. If the context also exposes
another actionable topic, put it in the issue form's dedicated field. Triage
will preserve it with a linked disposition; you do not need to refile text
diff --git a/scripts/tests/test_contribution_report_safety.py b/scripts/tests/test_contribution_report_safety.py
new file mode 100644
index 0000000000..00ea11512f
--- /dev/null
+++ b/scripts/tests/test_contribution_report_safety.py
@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""Keep the existing contribution entrypoint safe before a public report.
+
+These are guidance checks, not diagnostic-runtime or incident-recovery proof.
+"""
+
+from pathlib import Path
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def report_guidance() -> str:
+ text = (ROOT / "CONTRIBUTING.md").read_text(encoding="utf-8")
+ return text.split("## How To Make An Issue Useful\n", 1)[1].split("\n---\n", 1)[0]
+
+
+class ContributionReportSafetyTest(unittest.TestCase):
+ def test_collection_is_optional_and_distinct_from_downloading_a_result(self):
+ text = " ".join(report_guidance().split())
+ for statement in (
+ "Diagnostics are optional, not a condition of reporting",
+ "download buttons reuse that result without running checks again",
+ "Run Diagnostics** can make live API and guest-agent requests",
+ "Do not run it during a backup, freeze/thaw or an unresponsive-host incident",
+ "Keep the original evidence instead",
+ "not prove that normal monitoring has recovered or a guest has thawed",
+ "docs/TROUBLESHOOTING.md#collect-diagnostics-safely",
+ ):
+ self.assertIn(statement, text)
+
+ def test_review_is_required_before_public_attachment_even_for_sanitized_exports(self):
+ text = " ".join(report_guidance().split())
+ for statement in (
+ "local file, not an upload", "GitHub (review first)",
+ "Export for GitHub (sanitized)** in older versions",
+ "review files and screenshots locally before posting",
+ "a sanitized export is not a guarantee", "free-text errors",
+ "credentials", "session cookies", "secret URLs", "private host",
+ "network or personal details", "echoed in errors",
+ "Keep **Full (private)** exports private", "configuration", ".env",
+ "private keys", "Copy as cURL", "full network exports",
+ "Never put credentials in a command line, URL or thread",
+ ):
+ self.assertIn(statement, text)
+
+ def test_performance_evidence_does_not_require_risky_or_private_collection(self):
+ text = " ".join(report_guidance().split())
+ for statement in (
+ "existing readings or safe passive observations", "Where known",
+ "Pulse process", "container or the whole host", "units",
+ "measurement window", "uptime", "Unavailable readings are valid evidence",
+ "Do not restart, create load or change polling or retention just to measure",
+ "do not attach raw profiles, heap dumps, databases or full process command lines",
+ ):
+ self.assertIn(statement, text)
+
+ def test_shipped_contribution_guide_matches_the_repository_entrypoint(self):
+ self.assertEqual(
+ (ROOT / "CONTRIBUTING.md").read_bytes(),
+ (ROOT / "frontend-modern/public/docs/CONTRIBUTING.md").read_bytes(),
+ )
+
+
+if __name__ == "__main__":
+ unittest.main()