Evesdropctl

An MCP service and web console for Linux diagnostics over SSH, with optional user-approved automation on lab hosts. Observe mode is read-only by default. Host changes require explicitly armed authority and approval of each job.

This README describes the current implementation. project_context.md and project-phases.md retain the original design and phased roadmap; some early descriptions predate the optional host-script execution path.

Web console authentication

The local console starts with the temporary account admin / admin. Its first login is restricted to changing that password; use at least 12 characters. Passwords and session tokens are salted or hashed in data/audit.db. Sessions use an HttpOnly cookie, CSRF protection, a 30-minute idle timeout, and an 8-hour maximum lifetime. The top navigation provides separate Console and searchable History views plus explicit sign-out.

Conversations are scoped to one VM. Select a VM in Console, choose one of its saved conversations, or use New chat for a fresh conversation (saved with the first message). History includes a VM filter and Continue this chat. Switching VMs cannot reuse a conversation belonging to another VM. On backend startup, older mixed conversations are separated using the host metadata on user messages, retaining their following replies and message order. Messages without host metadata retain their recorded session host. The console uses frosted glass surfaces with an opaque fallback for reduced transparency.

Related MCP server: Linux MCP Server

Current status

Updated September 23, 2026. The project has working diagnostics and an implemented approval-based automation workflow. Fresh Rocky 9 installation acceptance is still pending; implementation and automated tests do not establish production readiness.

Approval and execution contract

Prepare job → Review host, script and verifier → User approves
→ Execute once → Independently verify → Inspect recorded evidence

Arming a mode does not approve a host job. The operator must approve the saved job in the authenticated web UI with password confirmation. MCP can prepare jobs and retrieve their results, but cannot approve or start them itself. Jobs are bound to the operator session, host, script digest and authority lease, with expiry, one-use execution, budgets and concurrency controls.

Host scripts run with the selected SSH account's real permissions; they are not a sandbox. They require a development/disposable-lab host, a root-owned Python 3.11+ helper, a non-root execution account and separately configured noninteractive sudo permissions where needed. Host jobs allow up to 900 seconds; isolated sandbox jobs remain capped at 120 seconds. Failure or stop can leave partial changes; no automatic rollback or mutation retry is promised.

Latest verification

The latest recorded validation is September 21, 2026; these results were not rerun for this documentation update. See the full test report.

• 402 backend tests passed, including 29 installation-specific tests.

• Production UI build, Python wheel build and packaged-template smoke checks passed.

• Lint checks passed for the changed Python code and the new software/script pages.

• Repository-wide checks are not all green: existing TypeScript errors remain in Account and Changes pages, alongside broader Python/frontend lint findings.

• Live checks on the selected Rocky 9.7 VM were read-only: both existing services were running, Nginx configuration validation passed, and their root URLs returned HTTP 403 (Nginx) and 404 (Tomcat). These responses do not prove application health. No installation or VM configuration changes were performed.

Remaining work

1. Complete fresh Nginx and Tomcat installation acceptance on a clean Rocky 9 lab VM through the actual MCP preparation and UI approval workflow. The previously inspected VM already has both applications and lacks Python 3.11 and the host helper.

2. Resolve the repository-wide TypeScript and lint findings.

3. Complete remaining host-hardening deployment and live escape checks before claiming that deployment's security acceptance; see hardening and security review.

4. Implement and validate upgrade preservation/restore, Podman deployment and additional software installers before enabling their execution.

The diagnostic executor still accepts fixed typed requests, not arbitrary shell commands. Exact absolute log paths are configured per host; globs and traversal are rejected. Diagnostic log requests are capped at 500 lines, and command output is capped at 2,000 lines and 256 KiB per stream with an explicit truncation flag. The separately enabled host-script path accepts reviewed Python, which may launch subprocesses under the account's permissions.

Implementation details: MCP server, audit records, host configuration, presentation, and deployment runbook.

Local setup

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
pytest

Run the MCP server after creating the host configuration:

sysadmin-mcp --config config/hosts.toml --audit-db data/audit.db

Local operator UI

The Dynamic scripts workspace adds optional, reviewed Python execution in rootless containers on enrolled lab VMs. Arm Dynamic sandbox, generate or write a script and verifier, prepare their digest, then run once with password reauthentication. It has no VM filesystem/network access and cannot perform host installations. Provision the separate helper before use; see docs/DYNAMIC_SANDBOX.md for limits and setup.

Copy .env.example to .env, then add OPENAI_API_KEY, GEMINI_API_KEY, and the SSH credential environment variable referenced by the selected host. The real .env is Git-ignored and keys are never sent to the browser.

Start the local API and UI in separate terminals:

sysadmin-web
cd ui
npm install
npm run dev

Open http://localhost:3000, or http://<this-PC-LAN-IP>:3000 from another device on the same private network. Both development services listen on all interfaces; the browser automatically targets port 8765 on the same host used for the UI. Credentialed CORS remains restricted to localhost, RFC1918 private addresses, and exact origins optionally listed in AGENT_ALLOWED_ORIGINS. Use HTTPS and set AUTH_COOKIE_SECURE=true before exposing this beyond a trusted test LAN. The provider switch supports ChatGPT, Gemini, and an OpenAI-compatible local LLM server configured with LOCAL_LLM_BASE_URL, LOCAL_LLM_MODEL, and an optional LOCAL_LLM_API_KEY.

Add VMs from the UI

Select VM management, enter an alias, hostname/IP, SSH port, username, password, and exact allowed log paths. The password is encrypted locally with AES-256-GCM and is never written to host configuration, logs, browser storage, or chat history. The first connection shows the SSH key algorithm and SHA-256 fingerprint. Verify it through the VM console or a trusted administrator, then choose Yes, trust key or No, cancel. Acceptance rechecks the key before atomically updating data/known_hosts and config/hosts.toml.

Database backup jobs

The Database backups page runs only typed job IDs enabled for a host. The browser cannot submit commands, script paths, or arguments. The VM's root-owned policy maps an ID such as database-dump to an exact executable such as /root/database-dump.sh. Runs require Administrator access, password reauthentication, an explicit confirmation, and a session-bound one-use approval. Results are bounded and recorded in the SQLite audit history.

See hardening/README.md for host-side installation.

Copy config/hosts.example.toml to config/hosts.toml only after the test host is prepared. config/hosts.toml, private keys, and SQLite files are ignored by Git.

Guided and Autonomous Lab host scripts

Console requests now use the active mode: Guided Lab prepares a script and verifier for one-use approval. Autonomous Lab also requires approval for each generated host job under explicit Host scripts authority. These run on the selected lab VM with its SSH account permissions. A separately provisioned host helper is required. See setup, operation, and limitations.

Approval-based software installation

Use Software management → Native → Fresh install → Prepare installation for approval, or the MCP prepare_software_install tool. Select an exact upstream version available in the target's baseos/appstream repositories. Existing installations and recognized application paths are refused. Required dependencies may be installed or updated, and the packaged service is enabled and started. No firewall changes or application deployment are included.

For the MCP preparation tools, first arm Host scripts and create an MCP connection from the Host scripts page. Set the returned token as SYSADMIN_MCP_EXECUTION_TOKEN in the MCP server environment, then start:

sysadmin-mcp --config config/hosts.toml --audit-db data/audit.db --enable-host-scripts

The web backend must be running on the same machine. Keep the token out of chat and source control. Return the job's review link to the operator; after their approval, read the result with get_host_script_job.

See the installation workflow and host-script setup for provisioning, verification, limits and failure behavior.