SysAdmin MCP Assistant

A security-first MCP service for read-only diagnostics on approved Linux hosts over SSH. The complete design and delivery plan are in project_context.md and project-phases.md.

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.

Related MCP server: Linux MCP Server

Current status

Phase 1's executor policy is implemented. ReadOnlyCommandPolicy builds a small, fixed set of argument vectors for ports, services, resource snapshots, allowlisted log reads/searches, and active users. ReadOnlyExecutor applies uniform output bounds, while the AsyncSSH implementation remains isolated in the transport module. MCP tools are not implemented yet.

Phase 2's deployable OS hardening is available in hardening/. It uses an OpenSSH forced-command gate with fixed absolute executables, a root-owned log allowlist, disabled interactive/forwarding features, and an adversarial verification checklist. Deployment and live escape testing must be performed on the disposable Linux host before Phase 2 is considered complete.

Phase 3's mandatory append-only SQLite audit sink is implemented. It records a durable attempt before transport execution, a terminal success/error event, and policy denials, with bounded excerpts and full-output hashes. See docs/audit.md for the event and operational model.

Phase 4's typed MCP stdio adapter exposes the six diagnostic capabilities with generated bounded schemas and read-only annotations. It has no raw command or generic SSH tool. See docs/mcp-server.md for runtime and validation instructions.

Phase 5 adds a raw-first presentation model and a replaceable summary boundary. The safe default summary is content-blind, so prompt-like text in logs remains inert. See docs/presentation.md.

Phase 6 provides validated multi-host TOML configuration, per-host log allowlists and resource thresholds, plus an atomic sysadmin-hosts management command. See docs/host-configuration.md.

Phase 7's local adversarial review covers injection, traversal, audit completeness, prompt-like log content, and output amplification. Findings and remaining live-host checks are recorded in SECURITY_REVIEW.md.

Phase 8's MVP cut adds per-session rate limiting, clear safe policy errors, and sysadmin-preflight. The deployment sequence and acceptance criteria are in MVP_RUNBOOK.md.

Host log access is configured with exact absolute paths in config/hosts.toml; globs, relative paths, and paths containing traversal are not accepted. Log line requests are capped at 500 lines, and every command result is capped at 2,000 lines and 256 KiB per output stream, with CommandResult.truncated indicating when a cap was applied.

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

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 run dev

Open http://localhost:3000. The provider switch supports OpenAI and Gemini; Anthropic is intentionally visible but disabled until its adapter is implemented.

Add VMs from the UI

Select Add VM, enter an alias, hostname/IP, SSH port, username, credential environment-variable name, and exact allowed log paths. 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; passwords are never entered in the UI.

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.