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
feat(db, basic guardrails, logs, code execution)
karloks2005e4cfea166686
diff --git a/requirements.txt b/requirements.txtindex 1786bb6..7027dfc 100644--- a/requirements.txt+++ b/requirements.txt@@ -1,4 +1,5 @@bcrypt+bashlexemail-validatorfastapigoogle-genaidiff --git a/src/agent/SYSTEM_PROMPT.md b/src/agent/SYSTEM_PROMPT.mdindex 321f7db..934aa06 100644--- a/src/agent/SYSTEM_PROMPT.md+++ b/src/agent/SYSTEM_PROMPT.md@@ -1,17 +1,40 @@-Name: Homie (Homelab sysadmin AI).+Name: Homie (Homelab SysAdmin AI)[ROLE & OUTPUT]Expert Linux SysAdmin AI. Concise, technical, direct.-Structure: 1. Short plain-text explanation. 2. Command block at VERY END (only if execution needed).+Structure:+1. Short plain-text explanation.+2. Command block at VERY END (only if execution needed).[COMMAND PROTOCOL][PARTIAL] (omit on final command)[RUN][RISK]: <VERY LOW|LOW|MEDIUM|HIGH|VERY HIGH>-[COMMAND-LOG]: <reason>+[REASON]: <reason> (why you want to run this command?)[COMMAND]: <single-line bash/docker command>[EOT] (only on final command)+[EXECUTION OUTPUT PROTOCOL]+Messages starting with `[SYSTEM-OUTPUT]` contain the direct result of your executed command.+Format received from the system:+[SYSTEM-OUTPUT]+[EXIT_CODE]: <0 | non-zero>+[STDOUT]:+<command stdout>+[STDERR]:+<command stderr>+[END-OUTPUT]++[BEHAVIOR ON RECEIVING OUTPUT]:+1. SUCCESS (EXIT_CODE: 0):+ - Summarize the result concisely for the user.+ - If a multi-step task was active and [PARTIAL] was used, issue the NEXT command using the [COMMAND PROTOCOL].+ - If the task is finished, inform the user in plain language.++2. FAILURE (EXIT_CODE: != 0 or non-empty STDERR):+ - IMMEDIATELY STOP any pending [PARTIAL] execution pipeline.+ - Analyze STDERR/EXIT_CODE, explain the issue clearly, and propose a fix or next action.+[FILE INPUT PROTOCOL](Append after [COMMAND] if writing files/input)[COMMAND-INPUT]@@ -21,18 +44,23 @@ Structure: 1. Short plain-text explanation. 2. Command block at VERY END (only i[STATE HANDLER]On "[CONTINUE]", resume active task from current state.-[SAFETY & EXECUTION RULES]-1. NON-INTERACTIVE ONLY: No interactive tools (nano, vim, top, htop). Always use non-interactive flags (`apt-get install -y`, `curl -s`, `pip --no-input`).-2. SINGLE-LINE: One command per [COMMAND]. Use `&&` or [PARTIAL] for chains.-3. STRICTLY FORBIDDEN: Piping network scripts (`curl|bash`), destructive cmds (`rm -rf /`, `mkfs`, `dd` to raw disk, `iptables -F`).+[PATH & EXECUTION RULES]+1. ABSOLUTE PATHS ONLY: Always explicitly state the full target path (e.g., /etc/docker/daemon.json). Never rely on relative paths or assume working directory state across turns.+2. IDEMPOTENCY: Prefer idempotent commands (e.g., `mkdir -p`, `systemctl is-active`, `rsync`).+3. NON-INTERACTIVE ONLY: Suppress interactive prompts (`apt-get install -y`, `curl -s`, `DEBIAN_FRONTEND=noninteractive`).+4. SINGLE-LINE: One command per [COMMAND]. Combine logic with `&&` or use [PARTIAL] for sequential steps.++[STRICT SAFETY RULES]+1. FORBIDDEN PATTERNS: Piping network outputs directly to shell (`curl|bash`), recursive root deletion (`rm -rf /`), unverified raw disk operations (`dd`, `mkfs`), or flushing main firewall tables (`iptables -F`).+2. STOP ON REPEATED ERROR: If a command fails twice with similar output, DO NOT repeat the attempt. Request human clarification.-[5-TIER RISK LEVELS]-- VERY LOW: Pure info/metrics read-only (uptime, free -m, whoami, date). Auto-executes instantly.-- LOW: Non-critical reads & container inspection (df -h, docker ps, docker logs, systemctl status). Auto-executes.-- MEDIUM: Safe state changes & non-critical service restarts (systemctl restart nginx, docker run/stop non-core apps, apt update). Requires basic UI approval.-- HIGH: System modifications & core service management (systemctl stop docker, ufw changes, editing system files, apt upgrade). Requires strong UI confirmation.-- VERY HIGH: Destructive/irreversible actions (reboot, shutdown, rm -rf on data dirs, user deletion, raw disk ops). Triggers critical warning & strict UI verification.+[RISK LEVEL CLASSIFICATION]+- VERY LOW: Read-only query commands (uptime, free -m, whoami, date, cat non-sensitive files).+- LOW: Inspection & status checks (df -h, docker ps, docker logs, systemctl status).+- MEDIUM: Safe configuration shifts & service restarts (systemctl restart <app>, docker restart, apt update).+- HIGH: Core system configuration, network rule modifications, editing system files, package upgrades.+- VERY HIGH: Destructive/irreversible operations (deleting volumes/data dirs, user deletion, broad file tree removals).[ERROR & LOG PROTOCOL]-1. HALT on non-zero exit code or stderr. Explain error and offer fix.-2. Log outputs may be truncated. Do not re-run identical broad logs; use targeted tools (grep, tail, jq).\ No newline at end of file+1. HALT immediately on non-zero exit code or critical error output.+2. Avoid re-running general log scans; filter output using targeted tools (`grep`, `tail -n 50`, `jq`).\ No newline at end of filediff --git a/src/agent/main.py b/src/agent/main.pyindex 2b2ab92..dcda6b1 100644--- a/src/agent/main.py+++ b/src/agent/main.py@@ -45,8 +45,6 @@ while True:breakfirstRun = False-- # Slanje poruke u unutar kreirane chat sesijeresponse = chat.send_message(user_input)log_file.write(f"[USER]" + "-"*30 + f"\n {user_input} \n")diff --git a/src/agent/service.py b/src/agent/service.pyindex 7fd85cb..18b6609 100644--- a/src/agent/service.py+++ b/src/agent/service.py@@ -1,13 +1,17 @@from __future__ import annotationsimport os+import re+import subprocessimport threading+from collections.abc import Callablefrom dotenv import load_dotenvfrom google import genaifrom google.genai import typesfrom .prompts import SYSTEM_PROMPT+from ..guardrails.guardrails_engine import GuardrailEngineload_dotenv()@@ -19,6 +23,7 @@ class AgentService:raise RuntimeError("GEMINI_API_KEY is not configured.")self.client = genai.Client(api_key=api_key)self.chats = {}+ self.pending_commands = {}self.lock = threading.Lock()def _get_chat(self, user_id: int, conversation_id: str):@@ -34,16 +39,159 @@ class AgentService:)return self.chats[chat_key]- def send(self, user_id: int, conversation_id: str, message: str) -> str:- response = self._get_chat(user_id, conversation_id).send_message(message)+ def send(+ self,+ user_id: int,+ conversation_id: str,+ message: str,+ command_logger: Callable[[dict], None] | None = None,+ ) -> str:+ chat = self._get_chat(user_id, conversation_id)++ pending_key = (user_id, conversation_id)+ if message.strip().upper() == "[APPROVE]" and pending_key in self.pending_commands:+ pending = self.pending_commands.pop(pending_key)+ self._log_event(command_logger, {+ "event_type": "approval",+ "message": "Human approval granted for command",+ "approval_status": "approved",+ **pending,+ })+ response_text = self._response_text(chat.send_message("[APPROVED] Execute the pending command now."))+ system_output = self._execute_and_log(pending, command_logger)+ return self._response_text(chat.send_message(system_output))++ response_text = self._response_text(chat.send_message(message))++ for _ in range(3):+ command_data = self._extract_command(response_text)+ if not command_data:+ return response_text++ command, risk = command_data+ reason = self._extract_reason(response_text)+ event = {+ "event_type": "command_proposed",+ "message": "Agent proposed a command",+ "command": command,+ "reason": reason,+ "risk": risk,+ "approval_status": "not_required",+ "steps": ["Extracted command, reason, and reported risk from agent response."],+ }+ evaluation = GuardrailEngine(command, risk).evaluate()+ if not evaluation["allowed"]:+ event.update({+ "event_type": "command_blocked",+ "message": "Guardrails blocked the proposed command",+ "approval_status": "blocked",+ "steps": [evaluation["reason"]],+ "level": "WARN",+ })+ self._log_event(command_logger, event)+ return f"{response_text}\n\n[EXECUTION BLOCKED]: {evaluation['reason']}"+ if evaluation.get("requires_human_approval"):+ event.update({+ "approval_status": "pending",+ "steps": [*event["steps"], "Waiting for explicit human approval before execution."],+ })+ self.pending_commands[pending_key] = {+ "command": command,+ "reason": reason,+ "risk": evaluation["effective_risk"],+ "approval_status": "approved",+ }+ self._log_event(command_logger, event)+ return f"{response_text}\n\n[APPROVAL REQUIRED]: This command has {evaluation['effective_risk']} risk and needs explicit approval."++ event["approval_status"] = "not_required"+ self._log_event(command_logger, event)+ system_output = self._execute_and_log({"command": command, "reason": reason, "risk": evaluation["effective_risk"]}, command_logger)+ response_text = self._response_text(chat.send_message(system_output))++ return response_text++ @staticmethod+ def _response_text(response) -> str:return getattr(response, "text", "") or "The agent returned an empty response."+ @staticmethod+ def _extract_command(response_text: str) -> tuple[str, str] | None:+ command_match = re.search(r"^\[COMMAND\]:\s*(.+)$", response_text, re.MULTILINE)+ if not command_match:+ return None+ risk_match = re.search(r"^\[RISK\]:\s*(VERY LOW|LOW|MEDIUM|HIGH|VERY HIGH)\s*$", response_text, re.MULTILINE)+ #Make sure risk defaults to "VERY HIGH" if not specified to ensure safety+ return command_match.group(1).strip(), risk_match.group(1) if risk_match else "VERY HIGH"++ @staticmethod+ def _extract_reason(response_text: str) -> str:+ reason_match = re.search(r"^\[REASON\]:\s*(.+)$", response_text, re.MULTILINE)+ return reason_match.group(1).strip() if reason_match else "No reason provided by agent."++ @staticmethod+ def _log_event(command_logger: Callable[[dict], None] | None, event: dict):+ if command_logger:+ command_logger(event)++ def _execute_and_log(self, command_data: dict, command_logger: Callable[[dict], None] | None) -> str:+ system_output = self._run_command(command_data["command"])+ exit_code = int(re.search(r"^\[EXIT_CODE\]:\s*(-?\d+)$", system_output, re.MULTILINE).group(1))+ stdout = self._extract_output_section(system_output, "STDOUT")+ stderr = self._extract_output_section(system_output, "STDERR")+ self._log_event(command_logger, {+ **command_data,+ "event_type": "command_executed",+ "message": "Command executed",+ "approval_status": command_data.get("approval_status", "not_required"),+ "exit_code": exit_code,+ "stdout": stdout,+ "stderr": stderr,+ "level": "INFO" if exit_code == 0 else "ERROR",+ "steps": [f"Command finished with exit code {exit_code}."]+ })+ return system_output++ @staticmethod+ def _extract_output_section(system_output: str, label: str) -> str:+ match = re.search(rf"\[{label}\]:\n(.*?)(?=\n\[(?:STDOUT|STDERR|END-OUTPUT)\]:|\n\[END-OUTPUT\])", system_output, re.DOTALL)+ return match.group(1).strip() if match else ""++ @staticmethod+ def _run_command(command: str) -> str:+ try:+ completed = subprocess.run(+ command,+ shell=True,+ executable="/bin/bash",+ capture_output=True,+ text=True,+ timeout=int(os.getenv("COMMAND_TIMEOUT_SECONDS", "30")),+ cwd=os.getenv("COMMAND_WORKDIR", "/"),+ check=False,+ )+ exit_code = completed.returncode+ stdout = completed.stdout[-12000:]+ stderr = completed.stderr[-12000:]+ except subprocess.TimeoutExpired as exc:+ exit_code = 124+ stdout = exc.stdout[-12000:] if isinstance(exc.stdout, str) else ""+ stderr = "Command timed out after the configured limit."++ return (+ "[SYSTEM-OUTPUT]\n"+ f"[EXIT_CODE]: {exit_code}\n"+ f"[STDOUT]:\n{stdout}\n"+ f"[STDERR]:\n{stderr}\n"+ "[END-OUTPUT]"+ )+_agent_service = None-def send_agent_message(user_id: int, conversation_id: str, message: str) -> str:+def send_agent_message(user_id: int, conversation_id: str, message: str, command_logger=None) -> str:global _agent_serviceif _agent_service is None:_agent_service = AgentService()- return _agent_service.send(user_id, conversation_id, message)\ No newline at end of file+ return _agent_service.send(user_id, conversation_id, message, command_logger=command_logger)\ No newline at end of filediff --git a/src/backend/auth.py b/src/backend/auth.pyindex 18b9e24..d45c574 100644--- a/src/backend/auth.py+++ b/src/backend/auth.py@@ -45,6 +45,15 @@ def record_audit_log(source: str = "system",task_title: str | None = None,steps: list[str] | None = None,+ conversation_id: str | None = None,+ event_type: str | None = None,+ command: str | None = None,+ command_reason: str | None = None,+ command_risk: str | None = None,+ approval_status: str | None = None,+ exit_code: int | None = None,+ stdout: str | None = None,+ stderr: str | None = None,):log_entry = AuditLog(user_id=user_id,@@ -53,6 +62,15 @@ def record_audit_log(source=source,task_title=task_title,steps=json.dumps(steps or []),+ conversation_id=conversation_id,+ event_type=event_type,+ command=command,+ command_reason=command_reason,+ command_risk=command_risk,+ approval_status=approval_status,+ exit_code=exit_code,+ stdout=stdout,+ stderr=stderr,)db.add(log_entry)db.commit()@@ -66,13 +84,32 @@ def record_audit_log("task_title": log_entry.task_title,"steps": steps or [],"created_at": log_entry.created_at.isoformat(),+ "conversation_id": log_entry.conversation_id,+ "event_type": log_entry.event_type,+ "command": log_entry.command,+ "command_reason": log_entry.command_reason,+ "command_risk": log_entry.command_risk,+ "approval_status": log_entry.approval_status,+ "exit_code": log_entry.exit_code,+ "stdout": log_entry.stdout,+ "stderr": log_entry.stderr,}-def get_recent_logs(db, *, limit: int = 20):+def get_recent_logs(+ db,+ *,+ limit: int = 20,+ user_id: int | None = None,+ conversation_id: str | None = None,+):+ query = db.query(AuditLog).filter(AuditLog.source != "auth")+ if user_id is not None:+ query = query.filter(AuditLog.user_id == user_id)+ if conversation_id:+ query = query.filter(AuditLog.conversation_id == conversation_id)logs = (- db.query(AuditLog)- .filter(AuditLog.source != "auth")+ query.order_by(AuditLog.created_at.desc()).limit(limit).all()@@ -93,6 +130,15 @@ def get_recent_logs(db, *, limit: int = 20):"task_title": log.task_title or log.message,"steps": steps if isinstance(steps, list) else [],"created_at": log.created_at.isoformat(),+ "conversation_id": log.conversation_id,+ "event_type": log.event_type,+ "command": log.command,+ "command_reason": log.command_reason,+ "command_risk": log.command_risk,+ "approval_status": log.approval_status,+ "exit_code": log.exit_code,+ "stdout": log.stdout,+ "stderr": log.stderr,})return resultdiff --git a/src/backend/main.py b/src/backend/main.pyindex 36effb0..35e0aaf 100644--- a/src/backend/main.py+++ b/src/backend/main.py@@ -3,7 +3,7 @@ from __future__ import annotationsfrom typing import Annotatedimport redis-from fastapi import Cookie, Depends, FastAPI, HTTPException, Request, Response, status+from fastapi import Cookie, Depends, FastAPI, HTTPException, Query, Request, Response, statusfrom fastapi.middleware.cors import CORSMiddlewarefrom pydantic import BaseModel, EmailStrfrom sqlalchemy import text@@ -62,6 +62,15 @@ def startup_event():if engine.dialect.name == "postgresql":connection.execute(text("ALTER TABLE audit_logs ADD COLUMN IF NOT EXISTS task_title VARCHAR(255)"))connection.execute(text("ALTER TABLE audit_logs ADD COLUMN IF NOT EXISTS steps TEXT"))+ connection.execute(text("ALTER TABLE audit_logs ADD COLUMN IF NOT EXISTS conversation_id VARCHAR(255)"))+ connection.execute(text("ALTER TABLE audit_logs ADD COLUMN IF NOT EXISTS event_type VARCHAR(50)"))+ connection.execute(text("ALTER TABLE audit_logs ADD COLUMN IF NOT EXISTS command TEXT"))+ connection.execute(text("ALTER TABLE audit_logs ADD COLUMN IF NOT EXISTS command_reason TEXT"))+ connection.execute(text("ALTER TABLE audit_logs ADD COLUMN IF NOT EXISTS command_risk VARCHAR(50)"))+ connection.execute(text("ALTER TABLE audit_logs ADD COLUMN IF NOT EXISTS approval_status VARCHAR(50)"))+ connection.execute(text("ALTER TABLE audit_logs ADD COLUMN IF NOT EXISTS exit_code INTEGER"))+ connection.execute(text("ALTER TABLE audit_logs ADD COLUMN IF NOT EXISTS stdout TEXT"))+ connection.execute(text("ALTER TABLE audit_logs ADD COLUMN IF NOT EXISTS stderr TEXT"))db = SessionLocal()try:ensure_default_user(db)@@ -201,13 +210,14 @@ def dashboard_summary(@app.get("/logs")def list_logs(session_id: Annotated[str | None, Cookie(alias=SESSION_COOKIE_NAME)] = None,+ conversation_id: str | None = Query(default=None),db=Depends(get_db),):user = get_user_from_session(redis_client, session_id)if not user:raise HTTPException(status_code=401, detail="Session is invalid or expired.")- return {"logs": get_recent_logs(db, limit=20)}+ return {"logs": get_recent_logs(db, limit=100, user_id=user["id"], conversation_id=conversation_id)}@app.post("/logs")@@ -228,6 +238,15 @@ def create_log(source=str(payload.get("source", "dashboard")),task_title=str(payload.get("task_title") or payload.get("message", "New task")),steps=[str(step) for step in payload.get("steps", []) if str(step).strip()],+ conversation_id=payload.get("conversation_id"),+ event_type=payload.get("event_type"),+ command=payload.get("command"),+ command_reason=payload.get("command_reason"),+ command_risk=payload.get("command_risk"),+ approval_status=payload.get("approval_status"),+ exit_code=payload.get("exit_code"),+ stdout=payload.get("stdout"),+ stderr=payload.get("stderr"),)@@ -242,7 +261,29 @@ def agent_chat(payload: AgentChatRequest, session_id: Annotated[str | None, Cookraise HTTPException(status_code=400, detail="Message is required.")try:- response_text = send_agent_message(user["id"], payload.conversation_id, message)+ response_text = send_agent_message(+ user["id"],+ payload.conversation_id,+ message,+ command_logger=lambda event: record_audit_log(+ db,+ user_id=user["id"],+ source="command",+ task_title=message[:255],+ steps=event.get("steps", []),+ conversation_id=payload.conversation_id,+ event_type=event.get("event_type"),+ message=event.get("message", "Command event"),+ level=event.get("level", "INFO"),+ command=event.get("command"),+ command_reason=event.get("reason"),+ command_risk=event.get("risk"),+ approval_status=event.get("approval_status"),+ exit_code=event.get("exit_code"),+ stdout=event.get("stdout"),+ stderr=event.get("stderr"),+ ),+ )except Exception as exc:raise HTTPException(status_code=503, detail="Agent is unavailable.") from excdiff --git a/src/backend/models.py b/src/backend/models.pyindex 90ed1ee..0e89748 100644--- a/src/backend/models.py+++ b/src/backend/models.py@@ -41,6 +41,15 @@ class AuditLog(Base):source: Mapped[str] = mapped_column(String(100), default="system", nullable=False)task_title: Mapped[Optional[str]] = mapped_column(String(255), nullable=True)steps: Mapped[Optional[str]] = mapped_column(Text, nullable=True)+ conversation_id: Mapped[Optional[str]] = mapped_column(String(255), nullable=True, index=True)+ event_type: Mapped[Optional[str]] = mapped_column(String(50), nullable=True)+ command: Mapped[Optional[str]] = mapped_column(Text, nullable=True)+ command_reason: Mapped[Optional[str]] = mapped_column(Text, nullable=True)+ command_risk: Mapped[Optional[str]] = mapped_column(String(50), nullable=True)+ approval_status: Mapped[Optional[str]] = mapped_column(String(50), nullable=True)+ exit_code: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)+ stdout: Mapped[Optional[str]] = mapped_column(Text, nullable=True)+ stderr: Mapped[Optional[str]] = mapped_column(Text, nullable=True)created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True),default=lambda: datetime.now(timezone.utc),diff --git a/src/frontend/src/App.jsx b/src/frontend/src/App.jsxindex 1cf342a..06fc81b 100644--- a/src/frontend/src/App.jsx+++ b/src/frontend/src/App.jsx@@ -37,12 +37,15 @@ async function apiRequest(path, options = {}) {function parseAgentMessage(text) {const commandMatch = text.match(/\[COMMAND\]:\s*(.+)/)const riskMatch = text.match(/\[RISK\]:\s*(VERY LOW|LOW|MEDIUM|HIGH|VERY HIGH)/)+ const reasonMatch = text.match(/\[REASON\]:\s*(.+)/)const explanation = text.split('[RUN]')[0].trim() || textreturn {text: explanation,command: commandMatch ? commandMatch[1].trim() : undefined,risk: riskMatch ? riskMatch[1].toLowerCase().replace(' ', '-') : 'low',+ reason: reasonMatch ? reasonMatch[1].trim() : undefined,+ approvalRequired: text.includes('[APPROVAL REQUIRED]'),}}@@ -490,10 +493,26 @@ function LandingPage({ chatThreads, activeThreadId, onSelectChat, user, onLogoutconst [messageInput, setMessageInput] = useState('')const [isSending, setIsSending] = useState(false)const [sendError, setSendError] = useState('')+ const [commandLogs, setCommandLogs] = useState([])+ const [isApproving, setIsApproving] = useState(false)const messageScrollerRef = useRef(null)const scrollAnimationRef = useRef(null)const activeThread = threads.find((thread) => thread.id === activeThreadId) || threads[0]+ const refreshCommandLogs = async () => {+ if (!activeThread) return+ try {+ const data = await apiRequest(`/logs?conversation_id=${encodeURIComponent(activeThread.id)}`, { method: 'GET' })+ setCommandLogs((data.logs || []).filter((entry) => entry.event_type))+ } catch {+ setCommandLogs([])+ }+ }++ useEffect(() => {+ refreshCommandLogs()+ }, [activeThread?.id])+useEffect(() => {const element = messageScrollerRef.currentif (!element) return undefined@@ -561,6 +580,7 @@ function LandingPage({ chatThreads, activeThreadId, onSelectChat, user, onLogout? { ...thread, messages: [...thread.messages, { role: 'agent', ...agentMessage }] }: thread)))+ await refreshCommandLogs()} catch (requestError) {setSendError(requestError.message || 'Agent is unavailable.')} finally {@@ -568,6 +588,30 @@ function LandingPage({ chatThreads, activeThreadId, onSelectChat, user, onLogout}}+ const handleApprove = async () => {+ if (!activeThread || isApproving || isSending) return+ setIsApproving(true)+ setSendError('')+ try {+ const data = await apiRequest('/agent/chat', {+ method: 'POST',+ body: JSON.stringify({ conversation_id: activeThread.id, message: '[APPROVE]' }),+ })+ const agentMessage = parseAgentMessage(data.message)+ setThreads((currentThreads) => currentThreads.map((thread) => (+ thread.id === activeThread.id+ ? { ...thread, messages: [...thread.messages, { role: 'user', text: 'Approved command execution.', risk: 'neutral' }, { role: 'agent', ...agentMessage }] }+ : thread+ )))+ await refreshCommandLogs()+ } catch (requestError) {+ setSendError(requestError.message || 'Approval failed.')+ } finally {+ setIsApproving(false)+ }+ }++return (<AppShell user={user} onLogout={onLogout} fitViewport><div className="flex h-full min-h-0 flex-col gap-5 lg:flex-row">@@ -662,9 +706,20 @@ function LandingPage({ chatThreads, activeThreadId, onSelectChat, user, onLogout</div><div className="text-sm leading-7 md:text-[15px]">{message.text}</div>{message.command && (- <pre className="command-block mt-3 overflow-x-auto rounded-2xl px-3 py-3 text-[11px] leading-6 whitespace-pre-wrap text-emerald-100">- {message.command}- </pre>+ <div className="mt-3">+ <pre className="command-block overflow-x-auto rounded-2xl px-3 py-3 text-[11px] leading-6 whitespace-pre-wrap text-emerald-100">{message.command}</pre>+ {message.reason && <div className="mt-2 text-xs text-[#9aa0a6]">Reason: {message.reason}</div>}+ {message.approvalRequired && (+ <button+ type="button"+ onClick={handleApprove}+ disabled={isApproving || isSending}+ className="mt-3 rounded-xl border border-amber-400/40 bg-amber-500/10 px-3 py-2 text-xs font-medium text-amber-200 transition hover:bg-amber-500/20 disabled:cursor-not-allowed disabled:opacity-50"+ >+ {isApproving ? 'Approving...' : 'Approve and run'}+ </button>+ )}+ </div>)}</div></div>@@ -672,6 +727,24 @@ function LandingPage({ chatThreads, activeThreadId, onSelectChat, user, onLogout})}</div>+ <div className="mt-4 rounded-[24px] border border-[#171b1f] bg-[#0d1013]/80 p-3">+ <div className="mb-2 text-xs uppercase tracking-[0.2em] text-[#9aa0a6]">Command log</div>+ <div className="custom-scroll max-h-36 space-y-2 overflow-y-auto">+ {commandLogs.length === 0 && <div className="text-xs text-[#7f8589]">No command events in this conversation.</div>}+ {commandLogs.map((entry) => (+ <div key={entry.id} className="rounded-xl border border-[#171b1f] bg-[#070809]/70 px-3 py-2 text-xs">+ <div className="flex items-center justify-between gap-2">+ <span className="text-[#cfcfcf]">{entry.event_type.replaceAll('_', ' ')}</span>+ <span className={entry.level === 'ERROR' || entry.level === 'WARN' ? 'text-red-300' : 'text-emerald-300'}>{entry.approval_status || 'recorded'}</span>+ </div>+ {entry.command && <code className="mt-1 block truncate text-emerald-100">{entry.command}</code>}+ {entry.command_reason && <div className="mt-1 text-[#7f8589]">{entry.command_reason}</div>}+ {entry.exit_code !== null && entry.exit_code !== undefined && <div className="mt-1 text-[#7f8589]">Exit code: {entry.exit_code}</div>}+ </div>+ ))}+ </div>+ </div>+<form onSubmit={handleSend} className="mt-4 rounded-[24px] border border-[#171b1f] bg-[#0d1013]/80 p-3"><div className="flex flex-col gap-3 md:flex-row md:items-center"><button type="button" className="rounded-xl border border-[#171b1f] bg-[#111417] px-3 py-2 text-sm text-[#cfcfcf]">Attach</button>@@ -792,12 +865,20 @@ function LogsPage({ onOpenThread, user, onLogout }) {.then((data) => {const mapped = (data.logs || []).map((entry) => ({id: entry.id,- type: entry.level === 'ERROR' || entry.level === 'WARN' ? 'ATTENTION' : 'COMPLETED',+ type: entry.level === 'ERROR' || entry.level === 'WARN' ? 'ATTENTION' : entry.event_type ? 'COMMAND' : 'COMPLETED',taskTitle: entry.task_title || entry.message,message: entry.message,time: new Date(entry.created_at).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', second: '2-digit' }),actor: entry.source || 'system',steps: entry.steps || [],+ eventType: entry.event_type,+ command: entry.command,+ reason: entry.command_reason,+ risk: entry.command_risk,+ approvalStatus: entry.approval_status,+ exitCode: entry.exit_code,+ stdout: entry.stdout,+ stderr: entry.stderr,}))setEntries(mapped)})@@ -822,7 +903,7 @@ function LogsPage({ onOpenThread, user, onLogout }) {<div className="custom-scroll min-h-0 flex-1 space-y-3 overflow-y-auto pr-1">{entries.map((entry) => (<article- key={`${entry.time}-${entry.message}`}+ key={entry.id}className="rounded-2xl border border-[#111417] bg-[#0d1013]/70 transition hover:border-[#1f2326] hover:bg-[#0d1013]"><button@@ -831,7 +912,7 @@ function LogsPage({ onOpenThread, user, onLogout }) {onClick={() => setExpandedId((currentId) => (currentId === entry.id ? null : entry.id))}className="flex w-full items-start gap-3 p-4 text-left">- <div className={`mt-1 h-2.5 w-2.5 shrink-0 rounded-full ${entry.type === 'ATTENTION' ? 'bg-amber-400' : 'bg-emerald-400'}`} />+ <div className={`mt-1 h-2.5 w-2.5 shrink-0 rounded-full ${entry.type === 'ATTENTION' ? 'bg-amber-400' : entry.type === 'COMMAND' ? 'bg-cyan-300' : 'bg-emerald-400'}`} /><div className="min-w-0 flex-1"><div className="flex flex-col gap-2 md:flex-row md:items-center md:justify-between"><div className="min-w-0">@@ -839,16 +920,29 @@ function LogsPage({ onOpenThread, user, onLogout }) {<div className="mt-1 line-clamp-1 text-sm text-[#9aa0a6]">{entry.message}</div></div><div className="flex shrink-0 items-center gap-3">- <span className={`text-xs uppercase tracking-[0.18em] ${entry.type === 'ATTENTION' ? 'text-amber-300' : 'text-emerald-300'}`}>{entry.type}</span>+ <span className={`text-xs uppercase tracking-[0.18em] ${entry.type === 'ATTENTION' ? 'text-amber-300' : entry.type === 'COMMAND' ? 'text-cyan-300' : 'text-emerald-300'}`}>{entry.type}</span><span className="text-xs text-[#7f8589]">{entry.time}</span><span className="text-xs text-[#7f8589]">{expandedId === entry.id ? 'Hide' : 'Details'}</span></div></div>- <div className="mt-2 text-xs uppercase tracking-[0.2em] text-[#7f8589]">Completed by {entry.actor}</div>+ <div className="mt-2 text-xs uppercase tracking-[0.2em] text-[#7f8589]">Recorded by {entry.actor}</div></div></button>{expandedId === entry.id && (<div className="border-t border-[#111417] px-4 pb-4 pt-3 pl-11">+ {(entry.command || entry.reason || entry.approvalStatus || entry.eventType) && (+ <div className="mb-4 space-y-2 rounded-xl border border-cyan-300/15 bg-cyan-300/5 p-3 text-sm">+ <div className="text-xs uppercase tracking-[0.2em] text-cyan-200">Command event</div>+ {entry.eventType && <div className="text-[#cfcfcf]">Event: <span className="text-white">{entry.eventType.replaceAll('_', ' ')}</span></div>}+ {entry.approvalStatus && <div className="text-[#cfcfcf]">Approval: <span className="text-white">{entry.approvalStatus}</span></div>}+ {entry.risk && <div className="text-[#cfcfcf]">Risk: <span className="text-white">{entry.risk}</span></div>}+ {entry.reason && <div className="text-[#cfcfcf]">Reason: <span className="text-white">{entry.reason}</span></div>}+ {entry.command && <pre className="command-block overflow-x-auto rounded-xl px-3 py-2 text-xs leading-5 whitespace-pre-wrap text-emerald-100">{entry.command}</pre>}+ {entry.exitCode !== null && entry.exitCode !== undefined && <div className="text-[#cfcfcf]">Exit code: <span className={entry.exitCode === 0 ? 'text-emerald-300' : 'text-red-300'}>{entry.exitCode}</span></div>}+ {entry.stdout && <pre className="max-h-40 overflow-auto rounded-xl bg-[#070809] p-2 text-xs whitespace-pre-wrap text-[#cfcfcf]">STDOUT:\n{entry.stdout}</pre>}+ {entry.stderr && <pre className="max-h-40 overflow-auto rounded-xl bg-red-950/20 p-2 text-xs whitespace-pre-wrap text-red-200">STDERR:\n{entry.stderr}</pre>}+ </div>+ )}<div className="mb-2 text-xs uppercase tracking-[0.2em] text-[#9aa0a6]">What Homie did</div><ul className="space-y-2 text-sm leading-6 text-[#cfcfcf]">{entry.steps.length > 0 ? entry.steps.map((step) => <li key={step} className="flex gap-2"><span className="text-emerald-300">•</span><span>{step}</span></li>) : <li className="text-[#9aa0a6]">No step details were recorded for this task.</li>}diff --git a/poem.txt b/src/guardrails/__init__.pysimilarity index 100%rename from poem.txtrename to src/guardrails/__init__.pydiff --git a/src/guardrails/guardrails_engine.py b/src/guardrails/guardrails_engine.pynew file mode 100644index 0000000..905720f--- /dev/null+++ b/src/guardrails/guardrails_engine.py@@ -0,0 +1,234 @@+import os+import re+import shlex+import bashlex++# ---------------------------------------------------------------------------+# RISK CONSTANTS+# ---------------------------------------------------------------------------+RISK_LEVELS = {+ "VERY LOW": 1,+ "LOW": 2,+ "MEDIUM": 3,+ "HIGH": 4,+ "VERY HIGH": 5+}++# ---------------------------------------------------------------------------+# LAYER 2: WHITELISTS & POLICY REGISTRIES+# ---------------------------------------------------------------------------+KNOWN_READ_ONLY = {+ "uptime", "free", "whoami", "date", "cat", "ls", "pwd",+ "grep", "tail", "head", "jq", "ps", "awk", "hostname", "uname", "wc"+}++KNOWN_INSPECTION = {+ "df", "du", "docker", "systemctl", "ip", "ss", "netstat", "find", "journalctl", "dmesg"+}++KNOWN_MUTATORS = {+ "apt", "apt-get", "yum", "dnf", "cp", "mv", "touch", "mkdir",+ "sed", "ufw", "iptables", "rsync", "chmod", "chown", "nano", "vim"+}++KNOWN_DESTRUCTIVE = {+ "rm", "dd", "mkfs", "fdisk", "parted", "userdel", "groupdel",+ "reboot", "shutdown", "poweroff", "kill", "pkill", "systemctl"+}++BANNED_SHELL_BUILTINS = {+ "eval", "exec", "source", ".", "alias", "unalias", "builtin"+}++INTERPRETER_BINARIES = {+ "python", "python3", "perl", "ruby", "php", "node", "bash", "sh", "zsh"+}++# ---------------------------------------------------------------------------+# LAYER 3: APPROVED EXECUTABLE PATHS+# ---------------------------------------------------------------------------+APPROVED_SYSTEM_PATHS = {+ "/usr/bin",+ "/bin",+ "/usr/sbin",+ "/sbin",+ "/usr/local/bin",+ "/opt/homie/approved_scripts" # Admin-approved custom folder+}+++class GuardrailEngine:+ def __init__(self, raw_command: str, llm_reported_risk: str = "VERY LOW"):+ self.raw_command = raw_command.strip()+ self.llm_risk_str = llm_reported_risk.upper()+ self.llm_risk_val = RISK_LEVELS.get(self.llm_risk_str, 5)++ def evaluate(self) -> dict:+ """Runs the multi-layered evaluation pipeline."""++ # --- PRE-CHECK: Hard Deny Regex (Immediate Reject) ---+ hard_deny = self._check_hard_denylist()+ if hard_deny:+ return {+ "allowed": False,+ "action": "BLOCKED",+ "reason": f"Hard Deny Rule Triggered: {hard_deny}",+ "effective_risk": "VERY HIGH"+ }++ # --- LAYER 1 & 2: Parse AST & Analyze Nodes ---+ try:+ ast_nodes = bashlex.parse(self.raw_command)+ except Exception as e:+ # If bashlex fails to parse the command (malformed/obfuscated syntax), lock it down.+ return {+ "allowed": False,+ "action": "BLOCKED",+ "reason": f"Syntax Parsing Error (Possible Obfuscation Attempt): {str(e)}",+ "effective_risk": "VERY HIGH"+ }++ max_calculated_risk = RISK_LEVELS["VERY LOW"]+ eval_reasons = []++ for node in ast_nodes:+ risk_score, reasons = self._visit_node(node)+ eval_reasons.extend(reasons)+ if risk_score > max_calculated_risk:+ max_calculated_risk = risk_score++ # --- LAYER 1: Anomaly Sentinel (LLM vs Calculated Risk) ---+ risk_delta = max_calculated_risk - self.llm_risk_val+ if risk_delta >= 2 and max_calculated_risk >= RISK_LEVELS["HIGH"]:+ return {+ "allowed": False,+ "action": "QUARANTINE_SESSION",+ "reason": (+ f"SECURITY ANOMALY DETECTED: LLM reported '{self.llm_risk_str}' risk, "+ f"but system evaluated risk level to {max_calculated_risk}. "+ "Possible prompt injection or context drift."+ ),+ "effective_risk": "VERY HIGH"+ }++ # Final Effective Risk is the HIGHER of LLM or System calculation+ effective_val = max(self.llm_risk_val, max_calculated_risk)+ effective_str = [k for k, v in RISK_LEVELS.items() if v == effective_val][0]++ return {+ "allowed": True,+ "action": "PROCEED",+ "effective_risk": effective_str,+ "reasons": eval_reasons,+ "requires_human_approval": effective_val >= RISK_LEVELS["MEDIUM"]+ }++ def _check_hard_denylist(self) -> str | None:+ """Immediate regex check for unrecoverable destructive commands."""+ patterns = [+ (r"rm\s+(-[rRfF]+\s+)?/", "Recursive root/system path deletion attempt"),+ (r">\s*/dev/sd[a-z]", "Direct raw block device overwrite"),+ (r"mkfs(\.\w+)?\s+", "Filesystem formatting command"),+ (r"dd\s+if=", "Raw block copy/write operation"),+ (r"curl\s+.*\|\s*(bash|sh)", "Network pipeline to shell execution"),+ (r"chmod\s+(-R\s+)?777\s+/", "Global system permissions modification"),+ (r"iptables\s+-F", "Flushing main firewall tables")+ ]+ for pattern, reason in patterns:+ if re.search(pattern, self.raw_command):+ return reason+ return None++ def _visit_node(self, node) -> tuple[int, list[str]]:+ """Recursively traverses AST nodes to evaluate executables and flags."""+ node_risk = RISK_LEVELS["VERY LOW"]+ reasons = []++ if node.kind == "command":+ # Extract word tokens from command node+ words = [self.raw_command[w.pos[0]:w.pos[1]] for w in node.parts if w.kind == "word"]+ if not words:+ return node_risk, reasons++ raw_binary = words[0]+ args = words[1:]++ # ---------------------------------------------------------------+ # LAYER 1: Check Banned Shell Built-ins+ # ---------------------------------------------------------------+ if raw_binary in BANNED_SHELL_BUILTINS:+ return RISK_LEVELS["VERY HIGH"], [f"Banned shell built-in executed: '{raw_binary}'"]++ # ---------------------------------------------------------------+ # LAYER 3: PATH Boundary & Resolution Verification+ # ---------------------------------------------------------------+ binary_name = os.path.basename(raw_binary)++ # If command specifies a path (e.g. ./script.sh or /tmp/tool)+ if "/" in raw_binary:+ resolved_path = os.path.realpath(raw_binary)+ parent_dir = os.path.dirname(resolved_path)++ if parent_dir not in APPROVED_SYSTEM_PATHS:+ return RISK_LEVELS["VERY HIGH"], [+ f"PATH VIOLATION: Binary '{raw_binary}' resolves to non-approved directory '{parent_dir}'"+ ]++ # ---------------------------------------------------------------+ # LAYER 1: Detect Inline Interpreter Abuses (e.g., python -c "...")+ # ---------------------------------------------------------------+ if binary_name in INTERPRETER_BINARIES:+ if any(flag in args for flag in ["-c", "-e", "--eval"]):+ return RISK_LEVELS["VERY HIGH"], [+ f"INLINE INTERPRETER DETECTED: '{binary_name}' with inline execution flags"+ ]++ # ---------------------------------------------------------------+ # LAYER 2: Deterministic Classification & Strict Fallback+ # ---------------------------------------------------------------+ if binary_name in KNOWN_READ_ONLY:+ node_risk = max(node_risk, RISK_LEVELS["VERY LOW"])+ reasons.append(f"Known read-only command: '{binary_name}'")++ elif binary_name in KNOWN_INSPECTION:+ if binary_name == "docker" and any(a in args for a in ["run", "rm", "stop", "exec", "system"]):+ node_risk = max(node_risk, RISK_LEVELS["MEDIUM"])+ reasons.append("Docker state modification flag detected")+ elif binary_name == "systemctl" and any(a in args for a in ["stop", "disable"]):+ node_risk = max(node_risk, RISK_LEVELS["HIGH"])+ reasons.append("Systemctl service stopping/disabling flag detected")+ else:+ node_risk = max(node_risk, RISK_LEVELS["LOW"])+ reasons.append(f"Known inspection tool: '{binary_name}'")++ elif binary_name in KNOWN_MUTATORS:+ if binary_name in ["ufw", "iptables"]:+ node_risk = max(node_risk, RISK_LEVELS["HIGH"])+ reasons.append("Network rule modification command")+ else:+ node_risk = max(node_risk, RISK_LEVELS["MEDIUM"])+ reasons.append(f"Known state mutator command: '{binary_name}'")++ elif binary_name in KNOWN_DESTRUCTIVE:+ if binary_name in ["rm", "dd", "mkfs"]:+ node_risk = max(node_risk, RISK_LEVELS["VERY HIGH"])+ else:+ node_risk = max(node_risk, RISK_LEVELS["HIGH"])+ reasons.append(f"Known critical/destructive binary: '{binary_name}'")++ else:+ # -----------------------------------------------------------+ # DEFAULT-DENY FALLBACK: Unrecognized Binary+ # -----------------------------------------------------------+ node_risk = max(node_risk, RISK_LEVELS["VERY HIGH"])+ reasons.append(f"DEFAULT-DENY: Unrecognized binary/command '{binary_name}'")++ # Recurse down sub-trees (pipelines `|`, chainers `&&`, logical lists)+ if hasattr(node, "parts"):+ for child in node.parts:+ child_risk, child_reasons = self._visit_node(child)+ reasons.extend(child_reasons)+ if child_risk > node_risk:+ node_risk = child_risk++ return node_risk, reasons\ No newline at end of filediff --git a/tests/test_agent_service.py b/tests/test_agent_service.pynew file mode 100644index 0000000..61d17b4--- /dev/null+++ b/tests/test_agent_service.py@@ -0,0 +1,70 @@+import threading++from src.agent.service import AgentService+++class FakeResponse:+ def __init__(self, text):+ self.text = text+++class FakeChat:+ def __init__(self, responses):+ self.responses = iter(responses)+ self.messages = []++ def send_message(self, message):+ self.messages.append(message)+ return FakeResponse(next(self.responses))+++def make_service(fake_chat):+ service = AgentService.__new__(AgentService)+ service.chats = {(1, "conversation"): fake_chat}+ service.pending_commands = {}+ service.lock = threading.Lock()+ return service+++def test_low_risk_command_executes_and_logs(monkeypatch):+ chat = FakeChat([+ "Check the current user.\n[RUN]\n[RISK]: VERY LOW\n[REASON]: Identify the process user.\n[COMMAND]: whoami\n[EOT]",+ "The command completed successfully.",+ ])+ service = make_service(chat)+ events = []+ monkeypatch.setattr(service, "_run_command", lambda command: "[SYSTEM-OUTPUT]\n[EXIT_CODE]: 0\n[STDOUT]:\nhomie\n[STDERR]:\n\n[END-OUTPUT]")++ result = service.send(1, "conversation", "Who am I?", events.append)++ assert result == "The command completed successfully."+ assert [event["event_type"] for event in events] == ["command_proposed", "command_executed"]+ assert events[0]["reason"] == "Identify the process user."+ assert events[1]["exit_code"] == 0+ assert events[1]["stdout"] == "homie"+++def test_medium_risk_command_waits_for_approval_then_executes(monkeypatch):+ chat = FakeChat([+ "Restart the service.\n[RUN]\n[RISK]: MEDIUM\n[REASON]: Apply the requested service change.\n[COMMAND]: systemctl restart homie\n[EOT]",+ "Approved command output received.",+ "The service restart completed.",+ ])+ service = make_service(chat)+ events = []+ monkeypatch.setattr(service, "_run_command", lambda command: "[SYSTEM-OUTPUT]\n[EXIT_CODE]: 0\n[STDOUT]:\nactive\n[STDERR]:\n\n[END-OUTPUT]")++ pending = service.send(1, "conversation", "Restart the service.", events.append)+ result = service.send(1, "conversation", "[APPROVE]", events.append)++ assert "[APPROVAL REQUIRED]" in pending+ assert result == "The service restart completed."+ assert [event["event_type"] for event in events] == [+ "command_proposed",+ "approval",+ "command_executed",+ ]+ assert events[0]["approval_status"] == "pending"+ assert events[1]["approval_status"] == "approved"+ assert events[2]["approval_status"] == "approved"+ assert chat.messages[-2] == "[APPROVED] Execute the pending command now."diff --git a/tests/test_auth_backend.py b/tests/test_auth_backend.pyindex 6f9f77a..087e597 100644--- a/tests/test_auth_backend.py+++ b/tests/test_auth_backend.py@@ -111,6 +111,30 @@ def test_record_audit_log_persists_database_entries():source="dashboard",)+ record_audit_log(+ db=session,+ user_id=user["user"]["id"],+ level="INFO",+ message="Command executed",+ source="command",+ conversation_id="conversation-1",+ event_type="command_executed",+ command="whoami",+ command_reason="Identify the process user.",+ command_risk="VERY LOW",+ approval_status="not_required",+ exit_code=0,+ stdout="homie",+ stderr="",+ )+logs = session.query(AuditLog).order_by(AuditLog.created_at.desc()).all()- assert len(logs) >= 2- assert logs[0].message == "Dashboard opened"+ assert len(logs) >= 3+ command_log = logs[0]+ assert command_log.message == "Command executed"+ assert command_log.conversation_id == "conversation-1"+ assert command_log.command == "whoami"+ assert command_log.command_reason == "Identify the process user."+ assert command_log.approval_status == "not_required"+ assert command_log.exit_code == 0+ assert command_log.stdout == "homie"