diff --git a/README.md b/README.md index f179b9d..0716253 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ Stop copy-pasting terminal output into your AI. Let your LLM SSH in and look around. -ShellGuard is an [MCP](https://modelcontextprotocol.io/) server that gives LLM agents read-only bash access to remote servers over SSH. Connect your AI to production, staging, or dev servers and let it run diagnostics, inspect logs, query databases, and troubleshoot -- hands-free. +ShellGuard is an [MCP](https://modelcontextprotocol.io/) server that gives LLM agents controlled bash access to remote servers over SSH. Connect your AI to production, staging, or dev servers and let it run diagnostics, inspect logs, query databases, and troubleshoot -- hands-free. -Commands are restricted to a curated set of read-only tools. Destructive operations are blocked with actionable suggestions so the LLM can self-correct and keep investigating: +Commands are restricted to a curated set of observation and diagnostic tools. Destructive operations are blocked with actionable suggestions so the LLM can self-correct and keep investigating: - `wget -r` -> `"Recursive downloading is not allowed"` - `tail -f` -> `"Follow mode hangs until timeout. Use tail -n 100 for recent lines."` @@ -186,17 +186,18 @@ Or add the following to your Roo Code MCP settings file. See [Roo Code MCP docs] ## What It Does -ShellGuard exposes 7 tools to the LLM: +ShellGuard exposes 6 tools to the LLM: | Tool | Description | | --------------- | ------------------------------------------------------------- | | `connect` | Establish an SSH connection to a remote host | -| `execute` | Run a read-only shell command on the remote host | -| `list_commands` | List available commands, optionally filtered by category | +| `execute` | Run a validated shell command on the remote host | | `disconnect` | Close SSH connection(s) | +| `sleep` | Wait between diagnostic checks (max 15s) | | `provision` | Deploy diagnostic tools (`rg`, `jq`, `yq`) to the remote host | | `download_file` | Download a file from the remote host via SFTP (50MB limit) | -| `sleep` | Wait between diagnostic checks (max 15s) | + +`provision`, `download_file`, and `sleep` can be disabled via the `disabled_tools` config option or `SHELLGUARD_DISABLED_TOOLS` environment variable. The LLM connects to a server, runs commands, and reads the output -- the same workflow you'd do manually, but without the context-switching. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 0c358f2..8458ce8 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -2,7 +2,7 @@ ## Overview -ShellGuard is a security-first MCP (Model Context Protocol) server that enables LLM agents to execute read-only shell commands on remote servers over SSH. It implements a defense-in-depth pipeline that parses, validates, and reconstructs every command before execution, ensuring only non-destructive operations reach the remote host. +ShellGuard is a security-first MCP (Model Context Protocol) server that enables LLM agents to execute validated shell commands on remote servers over SSH. It implements a defense-in-depth pipeline that parses, validates, and reconstructs every command before execution, ensuring only non-destructive operations reach the remote host. ## System Architecture @@ -141,17 +141,16 @@ Top-level constructor and convenience functions. Provides `New(Config)` to creat ### `server` -The MCP server core. Wires together all packages and registers 7 MCP tools: +The MCP server core. Wires together all packages and registers 6 MCP tools: | Tool | Description | | --------------- | ------------------------------------------------------------------- | | `connect` | Establish SSH connection to a remote host; probes for toolkit tools | | `execute` | Run a command through the security pipeline | -| `list_commands` | List allowed commands, optionally filtered by category | | `disconnect` | Close SSH connection(s) | +| `sleep` | Local sleep (max 15s) for use between diagnostic checks | | `provision` | Deploy diagnostic tools (`rg`, `jq`, `yq`) to remote host via SFTP | | `download_file` | Download a file from remote via SFTP (50MB limit) | -| `sleep` | Local sleep (max 15s) for use between diagnostic checks | The `Executor` interface abstracts the execution backend, enabling non-SSH implementations (Docker exec, local exec, test mocks) without modifying the security pipeline. @@ -236,7 +235,7 @@ Supports `x86_64` and `aarch64`. Binaries are cached locally at `~/.cache/shellg ## Security Model -ShellGuard enforces a **read-only, observational posture** through layered defenses: +ShellGuard enforces an **observational posture** through layered defenses: 1. **Syntax restriction** (parser) -- eliminates shell features that enable code execution, data exfiltration, or state mutation at the syntax level 2. **Command allowlisting** (validator + manifest) -- only explicitly approved commands pass; flags are individually controlled; SQL is validated for read-only semantics