Shellguard

ShellGuard

别再把终端输出复制粘贴到 AI 中了。让你的 LLM 通过 SSH 登录并查看情况。

ShellGuard 是一款 MCP 服务，可让 LLM Agent 通过 SSH 受控地访问远程服务器上的 bash。将 AI 连接到生产、预发布或开发服务器，让它自动运行诊断、检查日志、查询数据库并排查问题。

ShellGuard 是由 Fawdy 团队打造的开源安全层。它为 Fawdy 的 AI Linux 服务器调查工具提供支持，该工具能够以通俗易懂的语言给出根因分析。

你可以将 ShellGuard 单独与任何兼容 MCP 的 AI Agent 搭配使用，也可以通过 Fawdy 体验完整的调查功能。

为什么选择 ShellGuard？

AI Agent 能力强大，但让它们不受限制地访问生产服务器的 shell 存在风险。ShellGuard 通过在命令级别强制执行只读访问来解决这一问题。每条命令都会经过解析、与允许列表进行验证，然后重新构建再执行。如果 Agent 尝试执行具有破坏性的操作，ShellGuard 会拦截命令，并告诉 Agent 应该怎么做。

命令仅限于一组经过筛选的观察和诊断工具。系统会拦截具有破坏性的操作，并提供可行的建议，让 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 客户端：

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

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

claude mcp add shellguard -- shellguard

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

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

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

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

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

ShellGuard 向大模型提供 6 个工具：

可通过 disabled_tools 配置选项或 SHELLGUARD_DISABLED_TOOLS 环境变量禁用 provision、download_file 和 sleep。

大模型连接到服务器、运行命令并读取输出——这与手动操作的工作流相同，但无需在不同上下文之间切换。

工作原理

每条命令到达远程主机前都会经过以下处理流程：

1. 解析——将 bash 解析为 AST。在语法层面拒绝 shell 技巧（分号、重定向、命令替换等）。
2. 验证——根据精选的命令允许列表（并配有明确的拒绝列表）检查命令、标志和参数。默认拒绝。
3. 重构——重新引用参数以防止注入。
4. 执行——通过 SSH 运行命令，并设置每条命令的超时时间和输出截断。

完整详情请参阅 ARCHITECTURE.md。

SSH 配置

身份验证

ShellGuard 按以下顺序尝试身份验证方式，并在首次成功后停止：

在默认密钥发现过程中，加密密钥会被静默跳过。如果通过 identity_file 指定加密密钥，连接将失败。请先将密钥添加到 Agent：ssh-add ~/.ssh/my_key。

SSH 模式

ShellGuard 支持两种 SSH 模式：

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

ssh:
  mode: system

export SHELLGUARD_SSH_MODE=system

如果将 mode 设为 system，但找不到 ssh 二进制文件，ShellGuard 会记录警告并回退到 native 模式。

**Native 模式限制：**不支持 Match 指令、ProxyJump、ProxyCommand 和 ForwardAgent。如果基础设施需要这些功能，请使用 system 模式。

System 模式说明：

• 主机密钥验证完全由 OpenSSH 处理。host_key_checking 和 known_hosts_file 设置仅适用于 native 模式。
• 连接使用 OpenSSH ControlMaster 进行多路复用，因此每台主机仅第一个连接需要承担 SSH 握手开销。

主机密钥验证

ShellGuard 使用 ~/.ssh/known_hosts 验证 SSH 主机密钥。提供三种模式：

如果主机密钥已变更，请从 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

工具集部署

远程服务上不一定有你需要的工具。执行 connect 时，ShellGuard 会检查是否有 rg、jq 和 yq。如果缺少其中任何一个，大模型便可调用 provision 来部署它们：

二进制文件从 GitHub Releases 下载并通过 SHA-256 校验，缓存在本地，然后部署到远程主机的 ~/.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 本身就很好用。如果你希望自动调查事件并生成通俗易懂的根因报告，可以了解一下 Fawdy。它通过 ShellGuard 连接到你的 Linux 服务器，并自动调查事件。10 分钟即可完成设置。

许可证

Apache License 2.0。详情请参阅 LICENSE。