Self-hosted monitoring for homelabs: host and container metrics and uptime checks from all your machines in one dashboard, with an optional AI agent that diagnoses incidents and suggests fixes.
Python ai-agentsaiopsdashboarddockerfastapihomelabincident-managementllmmonitoringopenaireactroot-cause-analysisself-hosteduptime-monitoring
fix(agent): keep destructive or disguised commands from being recommended and tie checks to the incident's container (#217)
Karlo Kajba Šimanić23d8d4cd1bea
diff --git a/SECURITY.md b/SECURITY.mdindex 87e81b5..76d4deb 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -80,7 +80,10 @@ the containers' names, images and figures, and similar incidents before it. Befomasked for secrets (tokens, keys, passwords, credentials in URLs, private keys; `src/agent/masking.py`), and themodel is told the pack is untrusted data. Its answer is checked before anyone sees it: claims that cite no factfrom the pack are dropped, and fix commands that could destroy data or open the machine up are flagged and never-marked recommended (`src/agent/safety.py`). Nothing the model writes is run. Requests to OpenAI are sent with+marked recommended (`src/agent/safety.py`). So is a command with a line break or hidden characters, which could+paste as something other than what the page shows; the page shows every command exactly as it is copied. Any+other command that removes something (`rm`, `prune`, `-delete`, `DROP` …) is offered with a note but never marked+recommended either, because a list of dangerous patterns is never complete. Nothing the model writes is run. Requests to OpenAI are sent with`store: false`, so OpenAI keeps no copy of the conversation for later retrieval (its own abuse-monitoring retentionstill applies). Turn off "Diagnose new incidentsautomatically" in Admin › Incident agent to send nothing unless someone asks; without a key nothing is sentdiff --git a/TESTS.md b/TESTS.mdindex d26d598..270f63f 100644--- a/TESTS.md+++ b/TESTS.md@@ -150,7 +150,7 @@ The chart helper tests for the frontend are separate, in `src/frontend/tests/`.| [`test_agent_service.py`](#test_agent_servicepy) | 11 | The chat's reply is one message; secrets in the question and incident context are masked; Test connection trying a real request; the Chat Completions provider and conversation history. || [`test_agent_providers.py`](#test_agent_providerspy) | 12 | The Claude provider, and how the chosen provider, model and encrypted API key are stored. || [`test_agent_tool_calls.py`](#test_agent_tool_callspy) | 30 | Tool calling with Claude, OpenAI (Responses API) and Gemini: calls, several at once, errors, masking, append-only history, forcing an answer, reasoning carried over, nothing stored at OpenAI. |-| [`test_agent_diagnosis.py`](#test_agent_diagnosispy) | 42 | The agent's diagnosis: the evidence pack, secret masking, dangerous commands, checking the model's answer, saving reports. |+| [`test_agent_diagnosis.py`](#test_agent_diagnosispy) | 53 | The agent's diagnosis: the evidence pack, secret masking, dangerous commands, checking the model's answer, saving reports. || [`test_agent_investigation.py`](#test_agent_investigationpy) | 27 | The agent looking things up: the budget of tool calls per diagnosis and chat message, forced final answers, errors, the audit log, citations from tool results. || [`test_agent_steps.py`](#test_agent_stepspy) | 34 | The agent's look-ups in plain words: what each tool asked and found, no raw results or secrets, windows left for the page, odd entries never failing. || [`test_agent_tools.py`](#test_agent_toolspy) | 52 | The agent's read-only tools: a closed list with strict schemas, checked arguments, bounded and masked results with fact IDs, no secrets or IP addresses, nothing written. |@@ -379,13 +379,15 @@ request.|---|---|| `test_secrets_are_masked` | Passwords, tokens, keys, credentials in URLs, JWTs and private keys are replaced with `[masked]` (8 cases). || `test_ordinary_text_is_left_alone` | Ordinary event text, even with words like "token", is not masked. |-| `test_destructive_commands_are_flagged` | `rm -rf`, volume pruning, `DROP DATABASE`, `mkfs`, `chmod 777`, `curl \| sh`, `ufw disable` and more are flagged (9 cases). |+| `test_destructive_commands_are_flagged` | `rm -rf` however its flags are written, `find -delete`, volume pruning, `DROP DATABASE`, `mkfs`, `chmod 777`, `curl \| sh`, `ufw disable`, and a command with a line break or hidden characters are flagged (18 cases, #208). || `test_reading_and_ordinary_commands_are_not` | Reading commands and ordinary fixes are not flagged (7 cases). || `test_the_pack_has_an_id_on_every_fact_and_stays_small` | Every fact in the evidence pack has an ID, series stay within 40 points, similar incidents carry their resolution. || `test_the_pack_is_masked_and_the_same_every_time` | A secret in an event never reaches the pack, and the same data gives the same pack. || `test_signals_keep_only_the_evidence_that_exists` | References to facts that aren't in the pack are removed from a signal. || `test_a_signal_with_no_real_evidence_is_dropped_and_confidence_follows` | A signal citing nothing real is dropped and counted, and confidence falls to low. || `test_a_dangerous_step_is_flagged_and_never_recommended` | A destructive fix gets a warning and loses "recommended"; the first safe step may keep it. |+| `test_a_step_that_removes_something_is_never_recommended_but_stays_offered` | A command that removes something but isn't flagged (`docker image prune -a`) is offered with a note and never recommended; the next step may be (#208). |+| `test_a_fix_is_only_verified_on_the_incidents_own_container_for_at_least_five_minutes` | A "container runs N minutes" condition must name the incident's own container, lasts at least 5 minutes, and becomes manual otherwise (#208). || `test_only_one_step_is_recommended` | At most one fix step is recommended. || `test_a_verify_condition_on_an_unknown_metric_becomes_manual` | A condition on a metric that isn't in the pack is not watched. || `test_an_unusable_answer_is_rejected` | Answers that aren't JSON, aren't an object or have no summary are rejected (3 cases). |diff --git a/docs/agent-investigation.md b/docs/agent-investigation.mdindex f9952ba..2258e21 100644--- a/docs/agent-investigation.md+++ b/docs/agent-investigation.md@@ -178,7 +178,10 @@ into the conversation.- A "metric stays below a threshold" condition must name a metric from the evidence pack, because only those can bewatched by `verify.py`. A condition on a metric the agent found with a tool becomes one a person confirms.- Fix commands are checked for destructive patterns (`safety.py`); a flagged step gets a warning and is never- recommended.+ recommended. A line break or hidden characters in a command flag it too, and any command that removes something+ (`rm`, `prune`, `-delete`, `DROP` …) gets a note and is never recommended either.+- A "container runs N minutes without a restart" condition must name the incident's own container, and every+ watched condition lasts at least 5 minutes; anything else becomes one a person confirms.- An answer that doesn't parse is asked for once more in the same conversation, without tools, so the look-upsaren't paid for twice; after that the report is saved as failed.diff --git a/docs/assistant.md b/docs/assistant.mdindex f5dc577..fa8bbf0 100644--- a/docs/assistant.md+++ b/docs/assistant.md@@ -59,7 +59,7 @@ When a warning or critical incident opens, or gets worse, the backend queues a jsignals that each cite fact IDs, up to five fix steps and a condition that shows the incident is over.4. **Checks** before anyone sees it: signals that cite no fact from the pack or from a tool result are dropped andcounted ("1 unsupported claim left out"), fix commands that could destroy data are flagged and never recommended- (`safety.py`), and an answer that doesn't parse is asked for once more, in the same conversation and without+ (`safety.py`), no command that removes something is recommended, and an answer that doesn't parse is asked for once more, in the same conversation and withouttools (so the look-ups aren't paid for twice), then saved as a failed report.Each diagnosis is a new version in `agent_reports`, with the evidence pack and every look-up it made (tool,@@ -83,10 +83,12 @@ incident says so and links to the earlier one. Getting worse and **Diagnose agaiEach diagnosis ends with a condition that shows the incident is over. Two kinds are checked against the dataevery minute, without the model (`verify.py`):-- **a container runs N minutes without a restart**;+- **a container runs N minutes without a restart** (only the incident's own container);- **a metric stays under a threshold for N minutes** (memory, swap, load, CPU, a disk). Only a metric from theevidence pack can be watched; a condition on a metric the agent found with a tool becomes one a person confirms.+A condition lasts at least 5 minutes; a shorter one is stretched to 5.+The incident shows the progress ("Watching: resolves itself once gitlab runs 15 min without a restart. Held for 9of 15 min."). When the condition holds, the agent resolves the incident with "Resolved by the agent: …", which iswhat the resolved list shows. Data older than 5 minutes is never taken as proof.diff --git a/src/agent/diagnosis.py b/src/agent/diagnosis.pyindex 7150d98..8775b3d 100644--- a/src/agent/diagnosis.py+++ b/src/agent/diagnosis.py@@ -34,6 +34,7 @@ VERIFY_TYPES = ("container_running_for", "metric_below_for", "incident_quiet_forMAX_SIGNALS = 6MAX_STEPS = 5MAX_ATTEMPTS = 2+MIN_WATCH_MINUTES = 5# A diagnosis of the same rule on the same server (so the same container, mount or check) this recent is reused for a# new incident instead of asking the model again.REUSE_WITHIN = timedelta(hours=24)@@ -73,10 +74,11 @@ def _clip(text, limit: int) -> str:return text if len(text) <= limit else text[: limit - 1] + "…"-def check_answer(raw: str, labels: dict[str, str], watchable: dict[str, str] | None = None) -> dict:+def check_answer(raw: str, labels: dict[str, str], watchable: dict[str, str] | None = None, container: str | None = None) -> dict:"""The model's answer, checked against the evidence. ``labels`` are the facts it may cite (the pack's and the- tools'), ``watchable`` the metrics a fix may be verified on (the pack's; default ``labels``). Raises InvalidAnswer- when the answer isn't usable at all."""+ tools'), ``watchable`` the metrics a fix may be verified on (the pack's; default ``labels``), ``container`` the+ incident's own container (None when it isn't about one), the only one a fix may be verified on. Raises+ InvalidAnswer when the answer isn't usable at all."""watchable = labels if watchable is None else watchabletry:answer = json.loads(raw)@@ -102,15 +104,26 @@ def check_answer(raw: str, labels: dict[str, str], watchable: dict[str, str] | Ncontinuecommand = _clip(step.get("command"), 500) if isinstance(step.get("command"), str) and step["command"].strip() else Nonereasons = safety.check(command)- recommended = bool(step.get("recommended")) and not reasons and not recommended_given+ removes = safety.removes_data(command)+ recommended = bool(step.get("recommended")) and not reasons and not removes and not recommended_givenrecommended_given = recommended_given or recommended+ warning = f"Careful: this {', and '.join(reasons)}." if reasons else "This removes data." if removes else Nonesteps.append({"title": _clip(step["title"], 120), "text": _clip(step.get("text"), 500), "command": command, "recommended": recommended,- "dangerous": bool(reasons), "warning": f"Careful: this {', and '.join(reasons)}." if reasons else None})+ "dangerous": bool(reasons), "warning": warning})verify = answer.get("verify") if isinstance(answer.get("verify"), dict) else {}if verify.get("type") not in VERIFY_TYPES:verify = {"type": "manual", "target": None, "threshold": None, "minutes": None}if verify["type"] == "metric_below_for" and verify.get("target") not in watchable:verify = {"type": "manual", "target": None, "threshold": None, "minutes": None}+ # Only the incident's own container can show that its fix held; any other running container would resolve it (#208).+ if verify["type"] == "container_running_for" and (container is None or verify.get("target") != container):+ verify = {"type": "manual", "target": None, "threshold": None, "minutes": None}+ if verify["type"] != "manual":+ minutes = verify.get("minutes")+ if not isinstance(minutes, int) or isinstance(minutes, bool):+ verify = {"type": "manual", "target": None, "threshold": None, "minutes": None}+ else:+ verify = {**verify, "minutes": max(MIN_WATCH_MINUTES, minutes)} # a minute of quiet proves nothingconfidence = answer.get("confidence") if answer.get("confidence") in CONFIDENCE else "low"if not signals:confidence = "low" # a cause with nothing in the data behind it can't be more than a guess@@ -151,6 +164,7 @@ def diagnose(db, incident: IncidentAlert, provider: Provider, trigger: str = "inpack_labels = evidence_pack.index(pack)model = getattr(provider, "model", "unknown")budget = settings.tool_budget(db, "diagnosis")+ container = pack["incident"]["subject"] if str(pack["incident"]["kind"]).startswith("container:") else Nonedef record(completion, duration_ms: int) -> None:nonlocal model@@ -165,7 +179,7 @@ def diagnose(db, incident: IncidentAlert, provider: Provider, trigger: str = "incompletion = found.completionfor attempt in range(MAX_ATTEMPTS):try:- answer = check_answer(completion.text, labels, pack_labels)+ answer = check_answer(completion.text, labels, pack_labels, container)except InvalidAnswer as exc:reason = str(exc)if attempt + 1 < MAX_ATTEMPTS:diff --git a/src/agent/safety.py b/src/agent/safety.pyindex 9ec87cd..8b3ea3d 100644--- a/src/agent/safety.py+++ b/src/agent/safety.py@@ -2,15 +2,19 @@The agent never runs anything; people copy its commands into a shell. A suggestion such as ``docker system prune -a--volumes`` is sometimes right, but it must never look like the obvious next step. A flagged step is shown with a-warning and is never marked recommended. The list is about catching the dangerous cases, not about being complete.+warning and is never marked recommended. The list is about catching the dangerous cases, not about being complete,+so any command that removes something (``removes_data``) is never marked recommended either, only shown with a note."""from __future__ import annotationsimport re_RULES: list[tuple[re.Pattern, str]] = [- (re.compile(r"\brm\s+(-[a-zA-Z]*r[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*r|--recursive\s+--force|--force\s+--recursive)\b"), "deletes files recursively without asking"),- (re.compile(r"\bdocker\s+(system|volume)\s+prune\b[^\n]*(--volumes|\bvolume\s+prune)|\bdocker\s+volume\s+(prune|rm)\b"), "deletes Docker volumes, which hold container data"),+ # Any recursive rm, however its flags are written (-rf, -r -f, -R --force, --recursive).+ (re.compile(r"(?<![\w-])rm\b[^\n;|&]*\s(-[a-zA-Z]*[rR]|--recursive\b)"), "deletes files recursively"),+ (re.compile(r"\bfind\b[^\n;|&]*\s(-delete\b|-exec\s+rm\b)"), "deletes every file it finds"),+ (re.compile(r"\bdocker\s+(system|volume)\s+prune\b[^\n]*(--volumes|\bvolume\s+prune)|\bdocker\s+volume\s+(prune|rm)\b"+ r"|\bdocker\s+(container\s+)?rm\b[^\n;|&]*\s(-[a-zA-Z]*v|--volumes\b)"), "deletes Docker volumes, which hold container data"),(re.compile(r"\bdocker\s+system\s+prune\b[^\n]*(-a\b|--all\b)"), "removes every image no container uses right now"),(re.compile(r"\bdocker\s+(compose\s+down|-compose\s+down)\b[^\n]*(-v\b|--volumes\b)"), "removes the stack's volumes, which hold its data"),(re.compile(r"(?i)\b(drop\s+(database|table|schema)|truncate\s+table)\b"), "deletes database data"),@@ -27,8 +31,23 @@ _RULES: list[tuple[re.Pattern, str]] = []+# A line break runs the first line as soon as it is pasted into a shell, and control, direction (bidi) and invisible+# characters can make a command read differently from what is copied (#208).+_HIDDEN = re.compile("[\x00-\x08\x0a-\x1f\x7f-\x9f\u061c\u200b-\u200f\u2028-\u202e\u2060-\u2069\ufeff]")+HIDDEN_REASON = "contains a line break or hidden characters, so what you copy isn't what you see"++# Commands that remove something. Often the right fix (a full disk), but never the obvious next step to copy: they+# are not marked recommended even when no rule above calls them dangerous.+_REMOVES = re.compile(r"(?i)(?<![\w-])(rm|rmdir|unlink|shred|prune|drop|truncate)\b|\s-delete\b") # not the --rm of docker run++def check(command: str | None) -> list[str]:"""Why ``command`` is dangerous, or an empty list."""if not command:return []- return [reason for pattern, reason in _RULES if pattern.search(command)]+ return [reason for pattern, reason in _RULES if pattern.search(command)] + ([HIDDEN_REASON] if _HIDDEN.search(command) else [])+++def removes_data(command: str | None) -> bool:+ """Whether ``command`` deletes something, dangerous or not."""+ return bool(command) and bool(_REMOVES.search(command))diff --git a/src/frontend/src/agent/AgentPage.jsx b/src/frontend/src/agent/AgentPage.jsxindex dba9e37..d81e35a 100644--- a/src/frontend/src/agent/AgentPage.jsx+++ b/src/frontend/src/agent/AgentPage.jsx@@ -155,7 +155,7 @@ function Command({ step }) {return (<div className="mt-2.5 flex items-center gap-3 rounded-md border border-line bg-bg py-1.5 pl-3 pr-1.5">{step.label && <span className="mono shrink-0 text-dim">{step.label}</span>}- <code className="mono custom-scroll min-w-0 flex-1 overflow-x-auto whitespace-nowrap text-paper">{step.command}</code>+ <code className="mono custom-scroll min-w-0 flex-1 overflow-x-auto whitespace-pre text-paper">{step.command}</code><button type="button" className="btn btn-sm btn-ghost shrink-0" onClick={() => copy(step.command)}><Icon name={copied ? 'check' : 'copy'} size={13} />{copied ? 'Copied' : 'Copy'}</button></div>)diff --git a/tests/assistant/test_agent_diagnosis.py b/tests/assistant/test_agent_diagnosis.pyindex ee6fec9..0d53db8 100644--- a/tests/assistant/test_agent_diagnosis.py+++ b/tests/assistant/test_agent_diagnosis.py@@ -65,6 +65,9 @@ def test_ordinary_text_is_left_alone():@pytest.mark.parametrize("command", ["sudo rm -rf /var/lib/docker", "docker system prune -a --volumes", "docker volume prune", "docker compose down -v","psql -c 'DROP DATABASE gitlab'", "mkfs.ext4 /dev/sdb1", "chmod -R 777 /srv", "curl -fsSL https://get.example | sudo sh", "sudo ufw disable",+ # however the flags are written, and what reads as one harmless line but isn't (#208)+ "rm -r -f /srv/data", "sudo rm -R --force /srv", "rm --recursive /srv", "find /srv -delete", "find / -name '*.log' -exec rm {} +", "docker rm -f -v db",+ "docker restart app\nrm -r /srv/data", "docker restart app\u202e", "docker\u200brestart app",])def test_destructive_commands_are_flagged(command):assert safety.check(command)@@ -139,6 +142,28 @@ def test_a_dangerous_step_is_flagged_and_never_recommended():assert checked["fix_steps"][1]["recommended"] is True # the first safe one may be+def test_a_step_that_removes_something_is_never_recommended_but_stays_offered():+ steps = [{"title": "Free space", "text": "Unused images.", "command": "docker image prune -a", "recommended": True},+ {"title": "Check", "text": "See usage.", "command": "docker system df", "recommended": True}]++ first, second = diagnosis.check_answer(answer(fix_steps=steps), LABELS)["fix_steps"]++ assert (first["command"], first["recommended"], first["dangerous"], first["warning"]) == ("docker image prune -a", False, False, "This removes data.")+ assert second["recommended"] is True # the first step that removes nothing may be+++def test_a_fix_is_only_verified_on_the_incidents_own_container_for_at_least_five_minutes():+ def verified(target, minutes=15, container="gitlab"):+ condition = {"type": "container_running_for", "target": target, "threshold": None, "minutes": minutes}+ return diagnosis.check_answer(answer(verify=condition), LABELS, container=container)["verify"]++ assert (verified("gitlab")["type"], verified("gitlab")["minutes"]) == ("container_running_for", 15)+ assert verified("gitlab", minutes=1)["minutes"] == 5 # a minute of quiet proves nothing+ assert verified("nginx")["type"] == "manual" # any running container would resolve it (#208)+ assert verified("gitlab", container=None)["type"] == "manual" # the incident isn't about a container+ assert verified("gitlab", minutes=None)["type"] == "manual"++def test_only_one_step_is_recommended():assert [step["recommended"] for step in diagnosis.check_answer(answer(), LABELS)["fix_steps"]] == [True, False]