shellguard (Jonchun)

ShellGuard

停止将终端输出复制粘贴到您的AI中。让您的LLM SSH进入并四处查看。

ShellGuard是一个 主控程序 该服务器允许LLM代理通过SSH对远程服务器进行受控的bash访问。将您的AI连接到生产、测试或开发服务器，让它运行诊断、检查日志、查询数据库和排除故障——无需手动。

______________________________________________________________________

ShellGuard是由以下团队构建的开源安全层： 福迪它为Fawdy的AI驱动的Linux服务器调查工具提供动力，该工具提供简单的英文根本原因分析。

您可以将ShellGuard与任何兼容MCP的AI代理单独使用，或尝试使用 福迪.

______________________________________________________________________

为什么选择ShellGuard？

人工智能代理功能强大，但让它们不受限制地访问生产服务器是有风险的。ShellGuard通过在命令级别强制执行只读访问来解决这个问题。每个命令在执行前都会被解析、验证并重建。如果代理尝试破坏性的东西，ShellGuard会阻止它，并告诉代理该怎么做。

命令仅限于一组精心策划的观察和诊断工具。破坏性操作被可操作的建议所阻止，因此LLM可以自我纠正并继续调查：

• wget -r -> "Recursive downloading is not allowed"
• tail -f -> "Follow mode hangs until timeout. Use tail -n 100 for recent lines."
• sed -> "Stream editing can modify files -- read-only access only. Use grep for searching."
• $HOME/file -> "Variable expansion will not expand. Use absolute paths."

快速开始

安装

brew install fawdyinc/tap/shellguard

或者下载最新的二进制文件：

curl -fsSL https://raw.githubusercontent.com/fawdyinc/shellguard/main/install.sh | sh

或者使用Go：

go install github.com/fawdyinc/shellguard/cmd/shellguard@latest

使用MCP客户端进行配置

ShellGuard作为stdio MCP服务器启动，无需任何参数。将其添加到您选择的MCP客户端：

Cursor

首选 Settings -> Cursor Settings -> MCP -> Add new global MCP server

或者将此粘贴到您的 ~/.cursor/mcp.json 文件。您还可以通过创建来为每个项目安装 .cursor/mcp.json 在您的项目文件夹中。看 光标MCP文档 了解更多信息。

{
  "mcpServers": {
    "shellguard": {
      "command": "shellguard"
    }
  }
}

Claude Desktop

将以下内容添加到您的Claude Desktop配置文件中。看 克劳德桌面MCP文档 了解更多信息。

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "shellguard": {
      "command": "shellguard"
    }
  }
}

Claude Code

运行此命令。看 克劳德代码MCP文档 了解更多信息。

claude mcp add shellguard -- shellguard

OpenCode

将其添加到您的OpenCode配置文件中。看 OpenCode MCP文档 了解更多信息。

{
  "mcp": {
    "shellguard": {
      "type": "local",
      "command": ["shellguard"],
      "enabled": true
    }
  }
}

VS Code / GitHub Copilot

将以下内容添加到您的VS代码中 settings.json 或 .vscode/mcp.json。参见 VS代码MCP文档 了解更多信息。

用户设置(settings.json)

{
  "mcp": {
    "servers": {
      "shellguard": {
        "type": "stdio",
        "command": "shellguard"
      }
    }
  }
}

工作区配置(.vscode/mcp.json)

{
  "servers": {
    "shellguard": {
      "type": "stdio",
      "command": "shellguard"
    }
  }
}

Zed

将以下内容添加到Zed设置文件中(~/.config/zed/settings.json).看 Zed MCP文件 了解更多信息。

{
  "context_servers": {
    "shellguard": {
      "command": {
        "path": "shellguard",
        "args": []
      }
    }
  }
}

Roo Code

首选 Roo Code Settings -> MCP Servers -> Edit MCP Settings

或者将以下内容添加到Roo Code MCP设置文件中。看 Roo代码MCP文档 了解更多信息。

{
  "mcpServers": {
    "shellguard": {
      "command": "shellguard"
    }
  }
}

它的作用

ShellGuard向LLM公开了6个工具：

provision, download_file，以及 sleep 可以通过禁用 disabled_tools 配置选项或 SHELLGUARD_DISABLED_TOOLS 环境变量。

LLM连接到服务器，运行命令并读取输出——与您手动执行的工作流相同，但不需要上下文切换。

运作原理

每个命令在到达远程主机之前都要经过一个管道：

1. 解析 --bash被解析为AST。Shell技巧（分号、重定向、命令替换等）在语法级别被拒绝。
2. 验证 --命令、标志和参数将根据精心策划的命令列表（使用显式denylist）进行检查。默认拒绝。
3. 重建 --再次引用论点以防止注射。
4. 执行 --该命令在SSH上运行，每个命令都有超时和输出截断。

有关完整详细信息，请参阅 建筑.md.

SSH配置

认证

ShellGuard按以下顺序尝试身份验证方法，在第一次成功时停止：

在默认密钥发现过程中，会自动跳过受密码保护的密钥。如果您通过指定密码保护密钥 identity_file，连接将失败。先将密钥添加到您的代理： ssh-add ~/.ssh/my_key.

SSH模式

ShellGuard支持两种SSH模式：

如果您通过堡垒主机连接，请使用 ProxyJump，或依赖 Match SSH配置中的块，启用系统模式：

ssh:
  mode: system

export SHELLGUARD_SSH_MODE=system

如果 mode 设置为 system 但是 ssh 找不到二进制文件，ShellGuard会记录一个警告并回退到本机模式。

本机模式限制： Match 指令， ProxyJump, ProxyCommand，以及 ForwardAgent 不支持。使用 system 如果您的基础架构需要这些功能，请选择模式。

系统模式说明：

• 主机密钥验证完全由OpenSSH处理。这 host_key_checking 和 known_hosts_file 设置仅适用于本机模式。
• 使用OpenSSH对连接进行多路复用 ControlMaster，因此只有每个主机的第一个连接支付SSH握手成本。

主机密钥验证

ShellGuard使用验证SSH主机密钥 ~/.ssh/known_hosts有三种模式可供选择：

如果主机密钥已更改，请从您的 known_hosts 文件。

配置

可以在YAML配置文件中或通过环境变量指定设置。环境变量优先。

配置文件位置： $XDG_CONFIG_HOME/shellguard/config.yaml （默认值： ~/.config/shellguard/config.yaml)

ssh:
  mode: "native"                   # native | system
  connect_timeout: "10s"           # default 10s
  retries: 2                       # default 2
  retry_backoff: "250ms"           # default 250ms
  host_key_checking: "accept-new"  # accept-new | strict | off (native mode only)
  known_hosts_file: "~/.ssh/known_hosts"  # native mode only

工具包配置

远程服务器并不总是有你想要的工具。开 connectShellGuard探头 rg, jq，以及 yq。如果缺少，LLM可以致电 provision 要部署它们：

二进制文件通过SHA-256验证从GitHub发布版下载，在本地缓存，并部署到 ~/.shellguard/bin/ 在远程主机上。

图书馆使用情况

ShellGuard可以用作Go库：

package main

import (
    "context"
    "log/slog"
    "os"

    "github.com/fawdyinc/shellguard"
)

func main() {
    ctx := context.Background()
    logger := slog.New(slog.NewTextHandler(os.Stderr, nil))

    err := shellguard.RunStdio(ctx, shellguard.Config{Logger: logger})
    if err != nil {
        os.Exit(1)
    }
}

请参阅 自定义配置 和 自定义执行器 以下部分为高级用法。

自定义配置

import (
    "github.com/fawdyinc/shellguard"
    "github.com/fawdyinc/shellguard/manifest"
    "github.com/fawdyinc/shellguard/server"
)

manifests, _ := manifest.LoadEmbedded()
// Add or remove commands as needed

core, err := shellguard.New(shellguard.Config{
    Manifests: manifests,         // Custom registry (nil = embedded defaults)
    Executor:  myCustomExecutor,  // Custom backend (nil = SSH)
    Name:      "my-server",       // MCP server name
    Version:   "1.0.0",          // MCP server version
})

自定义执行器后端

实施 server.Executor 使用非SSH后端的接口：

type Executor interface {
    Connect(ctx context.Context, params ssh.ConnectionParams) error
    Execute(ctx context.Context, host, command string, timeout time.Duration) (ssh.ExecResult, error)
    ExecuteRaw(ctx context.Context, host, command string, timeout time.Duration) (ssh.ExecResult, error)
    SFTPSession(host string) (ssh.SFTPClient, error)
    Disconnect(host string) error
}

测试

make test          # Run all tests
make test-race     # Run with race detector
make lint          # Run go vet

项目结构

shellguard/
  shellguard.go          # Top-level constructor (New, RunStdio)
  cmd/shellguard/        # CLI entrypoint
  server/                # MCP server core, tool registration, Executor interface
  parser/                # Shell AST parser (mvdan.cc/sh/v3)
  validator/             # Command/flag/SQL validation engine
  manifest/              # YAML command registry (embed.FS)
    manifests/           # allowed command manifests
    manifests/denied/    # denied command manifests
  ssh/                   # SSH manager, ShellQuote, ReconstructCommand
  output/                # Output truncation (64KB cap)
  toolkit/               # Diagnostic tool provisioning (rg, jq, yq)

尝试完整体验

ShellGuard本身就很棒，但如果你想用简单的英文根本原因报告进行自动事件调查，请查看 福迪。它通过ShellGuard连接到您的Linux服务器，并自动调查事件。10分钟设置。

许可证

Apache许可证2.0。看 许可证 了解详情。