Shellguard

ShellGuard

ターミナルの出力を AI にコピー＆ペーストするのはやめましょう。LLM に SSH でログインさせて、サーバーの中を調べさせましょう。

ShellGuard は、LLM エージェントに SSH 経由でリモートサーバーへの制御された bash アクセスを提供する MCP サーバーです。AI を本番環境、ステージング環境、開発環境のサーバーに接続し、手を動かすことなく、診断の実行、ログの確認、データベースへのクエリ、トラブルシューティングを行えます。

ShellGuard は、Fawdy のチームが開発したオープンソースのセキュリティレイヤーです。平易な英語で根本原因を分析する、Fawdy の AI 搭載 Linux サーバー調査ツールを支えています。

ShellGuard は、MCP 対応の AI エージェントと組み合わせて単体で使用することも、Fawdy で包括的な調査機能を試すこともできます。

ShellGuard を選ぶ理由

AI エージェントは強力ですが、本番サーバーへの制限のないシェルアクセスを許可するのは危険です。ShellGuard は、コマンドレベルで読み取り専用アクセスを徹底することで、この問題を解決します。すべてのコマンドを解析し、許可リストに照らして検証したうえで、再構成してから実行します。エージェントが破壊的な操作を試みると、ShellGuard がそれをブロックし、代わりに何をすべきかをエージェントに伝えます。

コマンドは、厳選された監視・診断ツールに制限されています。破壊的な操作は、LLM が自力で修正して調査を続けられるよう、実行に役立つ提案とともにブロックされます。

• wget -r -> "再帰的なダウンロードは許可されていません"
• tail -f -> "追跡モードはタイムアウトまで終了しません。直近の行を確認するには tail -n 100 を使用してください。"
• sed -> "ストリーム編集ではファイルを変更できるため、読み取り専用アクセスのみ許可されます。検索には grep を使用してください。"
• $HOME/file -> "変数展開は行われません。絶対パスを使用してください。"

クイックスタート

インストール

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 は LLM に 6 つのツールを公開します。

provision、download_file、sleep は、disabled_tools 設定オプションまたは SHELLGUARD_DISABLED_TOOLS 環境変数で無効にできます。

LLM はサーバーに接続してコマンドを実行し、その出力を読み取ります。コンテキストを切り替えることなく、手動で行う場合と同じワークフローを実行できます。

仕組み

すべてのコマンドはリモートホストに届く前に、次のパイプラインを通ります。

1. 解析 — bash を AST に解析します。シェルのトリック（セミコロン、リダイレクト、コマンド置換など）は構文レベルで拒否されます。
2. 検証 — コマンド、フラグ、引数を、厳選されたコマンドの許可リスト（明示的な拒否リストも含む）と照合します。デフォルトでは拒否されます。
3. 再構築 — インジェクションを防ぐため、引数を再度引用符で囲みます。
4. 実行 — コマンドを SSH 経由で実行し、コマンドごとのタイムアウトと出力の切り捨てを適用します。

詳細については、ARCHITECTURE.md を参照してください。

SSH 設定

認証

ShellGuard は次の順序で認証方式を試し、最初に成功した方式で停止します。

パスフレーズで保護された鍵は、デフォルトの鍵の検出時に無視されます。パスフレーズで保護された鍵を identity_file で指定すると、接続は失敗します。まず、次のようにして鍵をエージェントに追加してください。ssh-add ~/.ssh/my_key

SSH モード

ShellGuard は 2 つの 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 ホスト鍵を検証します。利用できるモードは 3 つです。

ホスト鍵が変更された場合は、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 の有無を確認します。不足しているツールがある場合、LLM は provision を呼び出してデプロイできます。

バイナリは SHA-256 検証を行いながら GitHub Releases からダウンロードされ、ローカルにキャッシュされた後、リモートホストの ~/.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
})

カスタム実行バックエンド

SSH 以外のバックエンドを使用するには、server.Executor インターフェースを実装してください。

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をご覧ください。Fawdy は ShellGuard 経由で Linux サーバーに接続し、インシデントを自動で調査します。セットアップは 10 分です。

ライセンス

Apache License 2.0 です。詳細は LICENSE を参照してください。