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
Keep AI control recipes private and bounded
pulse-triage[bot]8359ac4e3964
diff --git a/docs/AI_AUTONOMY.md b/docs/AI_AUTONOMY.mdindex 110e22c5b0..02c8fab836 100644--- a/docs/AI_AUTONOMY.md+++ b/docs/AI_AUTONOMY.md@@ -44,11 +44,19 @@ one-off read, you can instead open the path in your signed-in administratorbrowser without extracting its cookie. There is no shared example passwordto configure or substitute into these commands.-Read the current settings first (curl 7.76 or later, on the Pulse host):+Define the [API guide's `pulse_api` helper](API.md#api-token-recommended)+in the same Bash session before using these examples (curl 7.76 or later).+It is local example code, not an installed Pulse command. Each call sends one+request, prints only the HTTP status and saves the response to a new owner-only+file, preserving earlier responses. It uses a five-second connection limit and+a twenty-second whole-request limit, ignores local curl defaults and does not+follow redirects or retry.++These are separate operations, not a script to run from top to bottom. Read+the current settings first, then inspect the reported private response file:```bash-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \- http://127.0.0.1:7655/api/ai/patrol/autonomy+pulse_api GET /api/ai/patrol/autonomy```The next command **changes Patrol mode**, not just connection health. Use it@@ -56,20 +64,25 @@ only when you intend to enable investigation and queue fixes for approval ona plan with that capability. The API retains `autonomy_level` for compatibility:```bash-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \- --request PUT --header 'Content-Type: application/json' --data-binary @- \- http://127.0.0.1:7655/api/ai/patrol/autonomy <<'JSON'+pulse_api PUT /api/ai/patrol/autonomy <<'JSON'{"autonomy_level":"approval","investigation_budget":15,"investigation_timeout_sec":600}JSON```-For remote use, substitute your Pulse **HTTPS** URL and keep certificate-verification enabled. Do not add `--insecure`, verbose/trace output or redirect-following; keep `--disable` first to ignore local curl defaults. A nonzero exit,-401 or 403 is a failed check, not evidence that a change was saved. Stop and-resolve authentication, permissions or the reported error before proceeding;-after an uncertain write, read the saved settings before retrying. Keep-tokens, cookies and unredacted responses out of reports.+The helper's loopback origin is for requests made on the Pulse host. For remote+use, change the origin and protocol restriction **in the helper** as the API+guide describes, using your Pulse **HTTPS** URL with certificate verification+enabled. Do not add `--insecure`, verbose/trace output or redirect following.++Inspect settings and error bodies privately; share only a relevant redacted+error, never the response file, token or cookie. A nonzero exit, including HTTP+401, 402 or 403, is not evidence that a change was saved. A partial response+is not a complete settings result, and HTTP success is not proof of the+effective mode or completed investigation. After an uncertain write, read the+saved settings before retrying: a timeout or lost response can occur **after+a change was applied**. If that read is unavailable, stop rather than repeat+the write. Check the saved and effective Patrol mode on the Patrol page;+licence and policy enforcement still apply.### License Requirements@@ -104,10 +117,13 @@ permission to change settings. Prefer the UI for one-off changes, and verifythe saved **Chat command mode** there afterwards. Do not use a write as anauthentication test.+Use the same `pulse_api` helper defined above, with its private response file+and request limits. Supporting PUT in the helper grants no additional access.+If the response is lost, check the saved **Chat command mode** in the UI before+deciding whether another change is needed; do not repeat the write blindly.+```bash-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \- --request PUT --header 'Content-Type: application/json' --data-binary @- \- http://127.0.0.1:7655/api/settings/ai/update <<'JSON'+pulse_api PUT /api/settings/ai/update <<'JSON'{"control_level":"controlled"}JSON```diff --git a/frontend-modern/public/docs/AI_AUTONOMY.md b/frontend-modern/public/docs/AI_AUTONOMY.mdindex 110e22c5b0..02c8fab836 100644--- a/frontend-modern/public/docs/AI_AUTONOMY.md+++ b/frontend-modern/public/docs/AI_AUTONOMY.md@@ -44,11 +44,19 @@ one-off read, you can instead open the path in your signed-in administratorbrowser without extracting its cookie. There is no shared example passwordto configure or substitute into these commands.-Read the current settings first (curl 7.76 or later, on the Pulse host):+Define the [API guide's `pulse_api` helper](API.md#api-token-recommended)+in the same Bash session before using these examples (curl 7.76 or later).+It is local example code, not an installed Pulse command. Each call sends one+request, prints only the HTTP status and saves the response to a new owner-only+file, preserving earlier responses. It uses a five-second connection limit and+a twenty-second whole-request limit, ignores local curl defaults and does not+follow redirects or retry.++These are separate operations, not a script to run from top to bottom. Read+the current settings first, then inspect the reported private response file:```bash-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \- http://127.0.0.1:7655/api/ai/patrol/autonomy+pulse_api GET /api/ai/patrol/autonomy```The next command **changes Patrol mode**, not just connection health. Use it@@ -56,20 +64,25 @@ only when you intend to enable investigation and queue fixes for approval ona plan with that capability. The API retains `autonomy_level` for compatibility:```bash-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \- --request PUT --header 'Content-Type: application/json' --data-binary @- \- http://127.0.0.1:7655/api/ai/patrol/autonomy <<'JSON'+pulse_api PUT /api/ai/patrol/autonomy <<'JSON'{"autonomy_level":"approval","investigation_budget":15,"investigation_timeout_sec":600}JSON```-For remote use, substitute your Pulse **HTTPS** URL and keep certificate-verification enabled. Do not add `--insecure`, verbose/trace output or redirect-following; keep `--disable` first to ignore local curl defaults. A nonzero exit,-401 or 403 is a failed check, not evidence that a change was saved. Stop and-resolve authentication, permissions or the reported error before proceeding;-after an uncertain write, read the saved settings before retrying. Keep-tokens, cookies and unredacted responses out of reports.+The helper's loopback origin is for requests made on the Pulse host. For remote+use, change the origin and protocol restriction **in the helper** as the API+guide describes, using your Pulse **HTTPS** URL with certificate verification+enabled. Do not add `--insecure`, verbose/trace output or redirect following.++Inspect settings and error bodies privately; share only a relevant redacted+error, never the response file, token or cookie. A nonzero exit, including HTTP+401, 402 or 403, is not evidence that a change was saved. A partial response+is not a complete settings result, and HTTP success is not proof of the+effective mode or completed investigation. After an uncertain write, read the+saved settings before retrying: a timeout or lost response can occur **after+a change was applied**. If that read is unavailable, stop rather than repeat+the write. Check the saved and effective Patrol mode on the Patrol page;+licence and policy enforcement still apply.### License Requirements@@ -104,10 +117,13 @@ permission to change settings. Prefer the UI for one-off changes, and verifythe saved **Chat command mode** there afterwards. Do not use a write as anauthentication test.+Use the same `pulse_api` helper defined above, with its private response file+and request limits. Supporting PUT in the helper grants no additional access.+If the response is lost, check the saved **Chat command mode** in the UI before+deciding whether another change is needed; do not repeat the write blindly.+```bash-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \- --request PUT --header 'Content-Type: application/json' --data-binary @- \- http://127.0.0.1:7655/api/settings/ai/update <<'JSON'+pulse_api PUT /api/settings/ai/update <<'JSON'{"control_level":"controlled"}JSON```diff --git a/scripts/tests/test_authentication_diagnostic_docs.py b/scripts/tests/test_authentication_diagnostic_docs.pyindex ad7d9c66ea..1d6444ae29 100644--- a/scripts/tests/test_authentication_diagnostic_docs.py+++ b/scripts/tests/test_authentication_diagnostic_docs.py@@ -17,7 +17,8 @@ import threadingimport timeimport unittest-from test_api_auth_docs import ROOT, TEST_TOKEN, exercise_curl, recording_server+from test_api_auth_docs import (ROOT, TEST_TOKEN, exercise_curl, recording_server,+ private_recording_server, request_helper)DOCUMENTS = {name: ROOT / f"docs/{name}.md" for name in ("AI_AUTONOMY", "PROXY_AUTH")}@@ -34,6 +35,14 @@ def blocks(name):return re.findall(r"```bash\n(.*?)```", DOCUMENTS[name].read_text(), re.DOTALL)+def executable_ai_recipe(recipe):+ # Exercise the shared guide helper, not a second implementation. Keep old+ # direct-curl recipes runnable for the exact-parent regression control.+ if "pulse_api " in recipe:+ return request_helper() + "\n" + recipe+ return recipe++def markdown_section(source, heading):# Emoji presentation selectors do not change the heading's meaning. Keep# exact heading identity and uniqueness, rather than matching the whole doc@@ -85,8 +94,13 @@ class AuthenticationDiagnosticDocsTest(unittest.TestCase):shell = "\n".join(blocks(name))self.assertNotRegex(shell, r"(?:admin:admin|\s-u\s|--user\b|X-Proxy-Secret:|\b\w*TOKEN=|--cookie\b)")self.assertNotRegex(shell, r"(?:--insecure|--verbose|--trace\S*|--location|\s-k\b)")- self.assertIn("curl --disable", shell)- self.assertIn("--header \"@", shell)+ if name == "AI_AUTONOMY":+ self.assertEqual(len(blocks(name)), len(EXPECTED_AI))+ self.assertTrue(all(recipe.startswith("pulse_api ") for recipe in blocks(name)))+ self.assertNotIn("curl ", shell)+ else:+ self.assertIn("curl --disable", shell)+ self.assertIn("--header \"@", shell)def test_docs_explain_permission_transport_and_end_to_end_limits(self):ai = DOCUMENTS["AI_AUTONOMY"].read_text()@@ -103,6 +117,19 @@ class AuthenticationDiagnosticDocsTest(unittest.TestCase):for name, doc in DOCUMENTS.items():self.assertEqual(doc.read_bytes(), (ROOT / f"frontend-modern/public/docs/{name}.md").read_bytes())+ def test_ai_guidance_keeps_response_privacy_and_uncertain_writes_explicit(self):+ guide = " ".join(DOCUMENTS["AI_AUTONOMY"].read_text().split())+ for boundary in ("in the same Bash session", "not an installed Pulse command",+ "new owner-only file", "preserving earlier responses",+ "five-second connection", "twenty-second whole-request",+ "does not follow redirects or retry", "not a script to run",+ "in the helper", "redacted error", "partial response",+ "HTTP success is not proof", "after a change was applied",+ "If that read is unavailable, stop", "Supporting PUT in the helper grants no additional access",+ "do not repeat the write blindly"):+ with self.subTest(boundary=boundary):+ self.assertIn(boundary, guide)+def test_ai_recipes_send_only_the_intended_method_path_and_body(self):recipes = blocks("AI_AUTONOMY")self.assertEqual(len(recipes), len(EXPECTED_AI))@@ -111,7 +138,8 @@ class AuthenticationDiagnosticDocsTest(unittest.TestCase):for recipe, (method, path, body) in zip(recipes, EXPECTED_AI):with self.subTest(header=key, method=method, path=path), tempfile.TemporaryDirectory() as temporary:before = len(requests)- result = exercise_curl(self, Path(temporary), f"{key}: {value}", port, recipe)+ result = exercise_curl(self, Path(temporary), f"{key}: {value}", port,+ executable_ai_recipe(recipe), private_response=True)self.assertEqual(result.returncode, 0, result.stderr.decode())self.assertEqual(len(requests), before + 1)sent_path, headers, sent_method, sent_body = requests[-1]@@ -121,15 +149,49 @@ class AuthenticationDiagnosticDocsTest(unittest.TestCase):self.assertEqual(json.loads(sent_body) if body is not None else sent_body,body if body is not None else b"")- def test_ai_recipes_report_401_and_403_without_submitting_a_later_step(self):- for status in (401, 403):- with recording_server(status) as (port, requests):+ def test_ai_recipes_keep_private_http_errors_without_submitting_a_later_step(self):+ for status in (400, 401, 402, 403, 500, 503):+ with private_recording_server(status) as (port, requests):for recipe in blocks("AI_AUTONOMY"):with self.subTest(status=status, recipe=recipe), tempfile.TemporaryDirectory() as temporary:before = len(requests)- result = exercise_curl(self, Path(temporary), f"X-API-Token: {TEST_TOKEN}", port, recipe)+ result = exercise_curl(self, Path(temporary), f"X-API-Token: {TEST_TOKEN}", port,+ executable_ai_recipe(recipe), private_response=True)self.assertEqual(result.returncode, 22)self.assertEqual(len(requests), before + 1)+ self.assertIn(f"HTTP {status}".encode(), result.stdout)++ def test_ai_recipes_keep_private_success_bodies_and_preserve_previous_responses(self):+ with private_recording_server() as (port, requests), tempfile.TemporaryDirectory() as temporary:+ home = Path(temporary)+ for header in (f"X-API-Token: {TEST_TOKEN}", f"Authorization: Bearer {TEST_TOKEN}"):+ for recipe, (method, path, body) in zip(blocks("AI_AUTONOMY"), EXPECTED_AI):+ with self.subTest(method=method, header=header.split(":")[0]):+ before = len(requests)+ result = exercise_curl(self, home, header, port,+ executable_ai_recipe(recipe), private_response=True)+ self.assertEqual(result.returncode, 0, result.stderr.decode())+ self.assertIn(b"HTTP 200", result.stdout)+ self.assertEqual(len(requests), before + 1)+ self.assertEqual((requests[-1][2], requests[-1][0]), (method, path))+ self.assertEqual(json.loads(requests[-1][3]) if body is not None else requests[-1][3],+ body if body is not None else b"")+ # One pre-existing file and one new private response per request.+ self.assertEqual(len(list((home / ".config/pulse").glob("api-response.*"))), 7)++ def test_ai_recipes_do_not_follow_redirects_or_repeat_incomplete_writes(self):+ for status, partial, expected_exit in ((302, False, 1), (200, True, 18)):+ with private_recording_server(status, partial) as (port, requests):+ for recipe, (method, path, body) in zip(blocks("AI_AUTONOMY"), EXPECTED_AI):+ with self.subTest(method=method, status=status, partial=partial), tempfile.TemporaryDirectory() as temporary:+ before = len(requests)+ result = exercise_curl(self, Path(temporary), f"X-API-Token: {TEST_TOKEN}", port,+ executable_ai_recipe(recipe), private_response=True)+ self.assertEqual(result.returncode, expected_exit, result.stderr.decode())+ self.assertEqual(len(requests), before + 1, "must not redirect or repeat a submitted write")+ self.assertEqual((requests[-1][2], requests[-1][0]), (method, path))+ self.assertEqual(json.loads(requests[-1][3]) if body is not None else requests[-1][3],+ body if body is not None else b"")def exercise_proxy(self, home, port, role, *, editor_exit=0, curl_exit=0):recipes = blocks("PROXY_AUTH")