SentinelX MCP

sentinelx-cloud-core

Claude.ai または ChatGPT から、Linux、macOS、Windows のサーバーを安全に操作できます。SentinelX は LLM に 許可リストで制限され、監査可能なシェルを提供します。実行できるのは明示的に許可したコマンドだけで、ファイルシステムへのアクセスはパスごとの許可リストで制限され、すべての操作が記録されます。インバウンドポートは不要で、アウトバウンド WebSocket を 1 つ接続するだけです。

セキュリティモデルが重要です。大切なサーバーで LLM に制限のないシェルを渡すことは、SentinelX が防ぐために設計された事態です。信頼境界となるのは許可リストなので、エージェントが実行できるのは許可した内容だけです。許可していない操作を実行したり、勝手に作り出したりすることはできません。これはホストにインストールするエージェントであり、構造化されたファイル編集とサービス管理も利用できます。

_{ChatGPT 上の SentinelX — 許可リストを読み込み、許可された内容（df -h、/proc/meminfo）だけを実行して、結果を報告します。}

インストール

多くのユーザーは、Linux または macOS を自動検出するワンライナーから始めます。

curl -fsSL https://get.sentinelx.app | bash

Windows（PowerShell — Python 3.12 以降と PATH 上の git が必要です）：

サービスとしてインストール — 起動時に LocalSystem として実行します。管理者権限で実行した PowerShell が必要です。

iwr -useb https://get.sentinelx.app/install.ps1 -OutFile "$env:TEMP\sx.ps1"
powershell -ExecutionPolicy Bypass -File "$env:TEMP\sx.ps1"

ユーザーごとにインストール — 管理者権限は不要です。ログオン時にユーザーとして実行します（制限されたマシン向け）。

iwr -useb https://get.sentinelx.app/install.ps1 -OutFile "$env:TEMP\sx.ps1"
powershell -ExecutionPolicy Bypass -File "$env:TEMP\sx.ps1" -User

インストーラーはこのリポジトリを仮想環境にクローンし、エージェントをサービスとして登録（systemd / launchd / Windows サービス）して、登録手続きを案内します。PyPI へのアクセスがブロックされているネットワークでは、最新リリースのホイールバンドルからオフラインでインストールするために -Bundle <zip-or-url> を追加してください。エージェントは OS の信頼ストア（truststore）を使用するため、TLS を検査するプロキシの CA も受け入れられます。ユーザーごとのインストールとサービスとしてのインストール、オフラインバンドル、すべてのフラグ、アンインストールなど、詳しいオプションは sentinelx-cloud-installer をご覧ください。

SentinelX は ChatGPT アプリディレクトリ にも掲載されています。ChatGPT ユーザーは、カスタム MCP URL を使わず、ワンクリックで接続できます。

このリポジトリにはエージェントのソースコードも含まれています。監査や貢献に関心がある場合は、続きをご覧ください。

トラブルシューティング

よくあるエラーとその解決方法は、実際に表示されるメッセージごとに sentinelx.app/troubleshooting に掲載されています。ウイルス対策ソフトの MCP スキャンによるサインイン失敗、再接続を繰り返すホスト、ハブの更新中に発生する -32603 エラー、ChatGPT による安全性ブロック、Manus のセットアップ、オフラインのままになるエージェントなどが対象です。該当するものがない場合は、こちらで issue を作成してください。

アーキテクチャ

                                        Internet
                                            │
   ┌────────────────┐                       │                  ┌─────────────────┐
   │  Claude.ai or  │   MCP over HTTPS      │   WebSocket      │  Your host      │
   │   ChatGPT      │ ◄───────────────────► │ ◄──────────────► │                 │
   │                │   (OAuth via Google)  │                  │  ┌───────────┐  │
   └────────────────┘                       │                  │  │  agent    │  │
                                ┌───────────────────────┐      │  │ (this)    │  │
                                │   mcp.sentinelx.app   │      │  └─────┬─────┘  │
                                │  (SentinelX hub —     │      │        │        │
                                │   closed source)      │      │   shell, edit,  │
                                └───────────────────────┘      │   service mgmt  │
                                                               └─────────────────┘

右側のボックスがエージェントです。インストール時（登録後）にハブへの アウトバウンド WebSocket を 1 つ開き、接続を維持します。インバウンドポート、ポートフォワーディング、リバーストンネルは不要です。

各コンポーネントの実行場所

コンポーネント	場所	役割
sentinelx-cloud-core（このリポジトリ）	ホスト上の /opt/sentinelx-cloud-core	ハブから MCP ツールの呼び出しを受け取り、ローカルで実行して、出力を返します
ハブ	mcp.sentinelx.app（Pensa が運用）	認証、複数ホストへのルーティング、MCP トランスポート
設定	/etc/sentinelx/config.yaml	エージェントが受け付けるコマンド、サービス、パスの許可リスト
ID	/etc/sentinelx/identity.json	エージェントの登録 JWT。WebSocket ハンドシェイクの認証に使用します

対応プラットフォーム： systemd を備えた最新の Linux ディストリビューション（Ubuntu 22.04 / 24.04、Debian 12 でテスト済み）、launchd を備えた macOS（Intel と Apple Silicon）、および Windows。Windows では、サービス（WinSW、管理者権限が必要）または管理者権限不要のユーザーごとのスケジュールタスク（-User）として実行できます。詳しくは、以下の Windows へのインストール をご覧ください。ワンラインインストーラーは Linux と macOS を自動検出します。Windows では PowerShell インストーラーを使用します。エージェントは WSL2 内でも、変更を加えずに実行できます。

公開されるツール

エージェントは、ハブを通じてホストの操作を MCP ツールとして LLM に公開します。

ツール	機能
sentinel_exec	許可リストに登録されたシェルコマンドを実行します
sentinel_script_run	1 回限りの bash または python3 スクリプトを実行します
sentinel_edit	構造化されたファイル編集（replace、regex、replace-block、write、append、prepend）を行います
sentinel_edit_upload_*	大きなファイル編集用の 3 ステップアップロード
sentinel_move	ファイルまたはディレクトリを移動／名前変更します
sentinel_copy	ファイルまたはディレクトリをコピーします
sentinel_delete	ファイルまたはディレクトリを削除します
sentinel_chmod	ファイルのアクセス権を変更します
sentinel_chown	ファイルの所有者／グループを変更します
sentinel_service	systemctl start/stop/restart/reload/status
sentinel_restart	action=restart を指定した sentinel_service のショートカット
sentinel_upload_file	ホストへの単発ファイルアップロード
sentinel_upload_*	大きなファイル用の 3 ステップ分割アップロード
sentinel_read	ファイルの内容を読み取ります。オプションで行範囲を指定できます
sentinel_list	構造化されたディレクトリ一覧（名前、種類、サイズ、mtime）を表示します
sentinel_search	正規表現と glob フィルターを使って、再帰的にコンテンツを検索します
sentinel_capabilities	ホストのポリシー／機能。オプションで範囲を限定した要約を返します
sentinel_help	詳細な案内／ヘルプ。オプションでトピック／パス／単一プレイブックに絞った内容を返します
sentinel_state	デバッグ用のエージェント内部状態
sentinel_ping	軽量な接続確認

段階的なイントロスペクション（エージェント操作コントラクト）

エージェント側の help および capabilities 操作では、応答範囲を絞るオプションのセレクターもサポートしています。Hub/MCP プロファイルでは、使用するモデル向けツールの形式に応じて、これらのフィールドを公開できます。セレクターはバックエンド操作の仕様であり、ツール名が完全形式かコンパクト形式かには依存しません。

• help({"topic":"index"}) — 小規模なトピック一覧と、ページ分割されたプレイブック索引。
• help({"topic":"security"}) — 幅広いヘルプセクションを 1 つ返します。
• help({"path":"security_model.permission_errors"}) — 既存のヘルプツリーから指定したリーフを 1 つ返します。
• help({"playbook":"update_sentinelx_code"}) — プレイブックを 1 つだけ返します。path、offset、limit を指定すると、steps などのサブフィールドを選択／ページ分割できます。
• capabilities({"detail":"summary"}) — コマンド／サービス／場所／プレイブックの本文を含めずに、ホスト／操作／制限のメタデータとポリシー件数を返します。

段階的なヘルプ／プレイブックの応答では、完全プロファイルの sentinel_* 参照を op:<name> という標準的な操作ヒントに正規化します。これにより、1 つのプレイブックに 2 セットの MCP ツール名を教えなくても、コンパクト形式または完全形式のどちらでも同じガイダンスを利用できます。

互換性のため、空の help({}) および capabilities({}) リクエストは、従来どおり完全な応答を返します。コンパクト形式を優先する Hub では、エージェントの従来の空ペイロードの動作を変更せず、コンパクト形式の help/capabilities 分岐を応答範囲を絞るセレクターに対応付けてください。

sentinel_read、sentinel_list、sentinel_search は読み取り専用のファイルシステムプリミティブです。sentinel_edit と変更を行うプリミティブ（sentinel_move、sentinel_copy、sentinel_delete、sentinel_chmod、sentinel_chown）は書き込みを行います。これらはすべて、exec を使って cat／ls／mv／rm を実行することなく、LLM にファイルシステムへの構造化アクセスを提供します。また、コマンド許可リストではなく、同じパス許可リスト（設定内の file_ops。詳細は後述）によって制御されます。許可リスト内の各パスには、アクセスレベルとして r（読み取り専用操作）または rw（読み取り専用操作に加え、書き込み操作）を指定します。既存の対象を上書きまたは削除する破壊的操作では、最初にタイムスタンプ付きのバックアップが作成されます。

ハブではさらに、LLM がエージェントのツールと併用できる、少数のハブ側インテグレーション（Cloudflare DNS、Resend メール、Telegram）を MCP ツールとして公開します。これらはハブ上にあり、このリポジトリには含まれません。sentinelx.app のインテグレーション一覧をご覧ください。

設定（/etc/sentinelx/config.yaml）

インストール時に初期設定が生成されます。編集可能です。サービスの再起動時に再読み込みされます。スキーマ：

# Commands the agent can execute via the `exec` op (exec_mode: allowlist, the
# default). Whole-word match, and every command in a chained line must be
# covered. Empty/missing = nothing allowed (deny by default).
allowed_commands:
  - uptime
  - df -h
  - free
  - systemctl
  - sudo systemctl
  - journalctl
  # See config.example.yaml for the full starter list (file inspection,
  # networking, containers, git, etc.) plus opt-in categories
  # (Cloudflare tunnels, WireGuard, Android tooling, firewalling, SSH).

# Service units the agent is allowed to control via `service` / `restart`.
# Each unit explicitly lists which actions are permitted.
services:
  nginx:
    actions: [status, start, stop, restart, reload]
  docker:
    actions: [status, restart]
  # The agent itself, so the LLM can reload policy after editing the
  # config. Restarting re-reads /etc/sentinelx/config.yaml. Conservative
  # actions only — no start/stop, since the agent can't remotely start
  # itself once stopped.
  sentinelx-cloud-core:
    actions: [status, restart, is-active, is-enabled]
  # postgresql:
  #   actions: [status, start, stop, restart, reload]

# Optional: named playbooks the LLM can read or execute. Two shapes are
# supported and can coexist in the same map:
#
# 1) Diagnostic playbook — a fixed sequence of allowlisted commands the
#    agent can run in order. Useful for "give me a quick health snapshot"
#    type prompts where you want one named entry-point.
#
# 2) Procedure playbook — a structured recipe for the LLM to follow,
#    expressed in `description` / `when` / `steps` / `requires` / `notes`
#    fields. Pure documentation: the agent does NOT execute the steps,
#    the LLM reads them via `capabilities` and then calls the regular
#    tools (sentinel_exec, sentinel_edit, sentinel_service) on its own.
#
# See `config.example.yaml` for the full reference.
playbooks:
  # Diagnostic playbook (shape 1)
  health:
    description: "Show system health summary"
    commands:
      - "uptime"
      - "df -h /"
      - "free -m"

  # Procedure playbook (shape 2) — guides the LLM through extending the
  # allowlist itself. Useful so users can ask "let me run htop here" and
  # the LLM knows the exact procedure (edit config, restart service,
  # verify with capabilities).
  add_allowed_command:
    description: "How to add a new command to this host's allowlist"
    when: "User asks to allow a new command on this host"
    steps:
      - "Read /etc/sentinelx/config.yaml with sentinel_exec"
      - "Insert under allowed_commands with sentinel_edit (sudo, validator_preset=yaml)"
      - "Restart the agent: sentinel_service restart sentinelx-cloud-core"
      - "Verify with sentinel_capabilities"

# Logging
log:
  path: /var/log/sentinelx/core.log
  level: INFO

# SSRF defense for upload_file's file_url. The hostname must be in this
# allowlist AND must resolve to a public-routable IP (no loopback,
# RFC1918, link-local, etc.). Default empty = file_url disabled.
# Only add hosts YOU control — third-party hosts (github.com, pypi,
# random CDNs) expose your agent to supply-chain compromise.
security:
  trusted_fetch_hosts:
    - drop.pensa.ar
    - get.sentinelx.app
  file_url_timeout_seconds: 15

# Filesystem primitives (sentinel_read/list/search + edit, move, copy,
# delete, chmod, chown). Gated by a PATH allowlist, separate from the
# command allowlist above. Empty/missing = all the filesystem primitives
# are effectively disabled (they return path_not_allowed for any input).
#
# Each entry declares an access level:
#   r  = read-only ops (read, list, search) may touch this subtree
#   rw = read-only ops AND writing ops (edit, move, copy, delete,
#        chmod, chown) may touch this subtree
#
# A path is permitted only if, after canonicalization (symlinks
# resolved, .. collapsed), it falls under one of these entries. That
# canonical-resolve-then-prefix-check is what defeats both path
# traversal and symlink escapes. Writing ops additionally require the
# matched entry to be `rw`.
#
# Back-compat: an older `allowed_read_paths:` list is still accepted and
# is interpreted as a set of `r` entries (with a deprecation warning).
file_ops:
  paths:
    - path: /etc/nginx
      access: r
    - path: /var/log
      access: r
    - path: /home/youruser/projects
      access: rw
  max_read_bytes: 65536       # per read; larger files come back truncated
  max_list_entries: 1000      # per list
  max_search_results: 200     # per search

デフォルトの exec_mode: allowlist では、エージェントはコマンドライン内のすべてのコマンドが allowed_commands と完全な単語として一致する場合にのみ実行します（agent 0.23.22+）。そのため、git を許可すると、LLM は git status と git log -1 && git status を実行できます。ls を許可すると ls -lah /var/log は実行できますが、lsof は実行できません。パイプ後の読み取り専用フィルター（| grep x、| head）やシェル構文（for、if など）は、登録する必要はありません。bash や python3 のようなエントリーを許可すると、bash -lc '...' が1つの引数であるため、あらゆる操作が可能になります。exec_mode: strict では、改行、置換、リダイレクトも拒否されます。exec_mode: unrestricted は、信頼できる開発ホスト向けに、エージェントのユーザー権限であらゆる操作を実行します。初期設定は制限的です。初期設定の完全なリストと3つのモードについては、config.example.yaml を参照してください。

互いに独立した許可リストが2つあり、それぞれ異なる操作を保護します。

• allowed_commands は（exec_mode に応じて）exec を制限します。script_run は制限しません。これはエージェントのユーザーとして任意のスクリプトを実行するため、必要に応じて disabled_ops: [script_run] で無効にしてください。
• file_ops.paths は、すべてのファイルシステムプリミティブを制限します。読み取り専用のもの（sentinel_read、sentinel_list、sentinel_search）は r または rw のエントリーが対象で、書き込みを行うもの（sentinel_edit、sentinel_move、sentinel_copy、sentinel_delete、sentinel_chmod、sentinel_chown）は rw のエントリーのみが対象です。

つまり、r として登録されたディレクトリは、LLM による閲覧は許可されますが、変更は許可されません。rw として登録されたディレクトリでは、どちらも許可されます。どちらにも登録されていないディレクトリは、すべてのファイルシステムプリミティブから参照できません（LLM は exec に頼る必要がありますが、こちらは代わりに allowed_commands によって制御されます）。

意図的に設けられた例外が1つあります。sudo=true を指定した sentinel_edit は、file_ops.paths による制限を受けません。sudo を使った編集の信頼境界はパス許可リストではなく、オペレーターの sudoers ポリシーです。これにより、add_allowed_command プレイブックで root 所有の設定ファイルを編集できます。パスの正規化は引き続き行われるため（トラバーサルやシンボリックリンクによる回避はできません）、sudo を使うパスでは rw のメンバーシップチェックのみが免除されます。この例外と残存リスクについては、THREAT_MODEL.md（§4.2.1）に記載されています。

セキュリティモデル

• インバウンドポートはありません。 ハブへのアウトバウンド WebSocket 接続のみを使用します。
• JWT に紐付けられた ID。 identity.json は登録時にハブによって署名されます。 1 台のホストが侵害されても、ほかのホストへのアクセスは許可されません。
• 許可リストによる制限。 config.yaml にないものはすべて command_not_allowed を返します。エージェントが新しいコマンドを合成することはありません。これが 実際のセキュリティ境界であり、Unix ユーザーでも sudo ポリシーでもありません。 コマンドが拒否されると、エージェントは分類されたエラー （複数行入力、bash キーワード、シェルパイプライン、または単に許可リストにないこと）を返します。 これにより、LLM は推測するのではなく、適切なツールを使用できます。
• パス許可リストで制限されたファイルシステムプリミティブ。 構造化ファイルシステム操作はすべて、 file_ops.paths 配下のパスのみを対象とします。読み取り専用操作（sentinel_read、 sentinel_list、sentinel_search）は r および rw エントリで動作します。書き込み 操作（sentinel_edit、sentinel_move、sentinel_copy、sentinel_delete、 sentinel_chmod、sentinel_chown）には rw エントリが必要です。パスは プレフィックスの確認前に正規化されます。シンボリックリンクを解決し、.. を折りたたむため、 パストラバーサルや許可リスト外を指すシンボリックリンクによって制限を回避することはできません。 許可リストが空の場合、プリミティブは無効になります。既存の対象を上書きまたは削除する書き込み操作では、 事前にバックアップ（タイムスタンプ付きの .bak）を作成します。sudo=true を指定した sentinel_edit は rw チェックの例外として文書化されています。THREAT_MODEL.md §4.2.1 を参照してください。
• パスワードなしの sudo を使用する非特権ユーザー。 エージェントは root ではなく、 sentinelx として実行されます。デフォルトでは、サービスの管理やシステムファイルの編集を 可能にするため、インストーラーが sentinelx にパスワードなしの sudo を許可します。ただし、 実行できるのは許可リストにあるものだけです。sudo を使わずに実行するには、 インストール時に SENTINELX_SKIP_SUDO=1 を設定してください。
• SSRF 対策済みの file_url。 URL を指定して upload_file が呼び出されると、 エージェントはホスト名を security.trusted_fetch_hosts と照合し、 IP アドレスに解決したうえで、ループバック／RFC1918／リンクローカルアドレスを拒否します （攻撃者がクラウドメタデータサービスや LAN 内部のホストへアクセスできないようにします）。 リダイレクトは無効で、https のみを使用し、デフォルトのタイムアウトは 15 秒です。 許可リストはデフォルトで空のため、オペレーターが特定のホストを許可するまでは file_url は実質的に無効です。
• パストラバーサル対策済みのアップロード。 すべての target_path 引数は、 safe_path_under() によって upload_base 配下に解決されます。配下から外れる .. や絶対パスは、 処理の開始時点で拒否されます。
• テレメトリーはありません。 エージェントは、明示的に接続したハブ以外の相手に、 ホストやアクティビティに関する情報を一切報告しません。

詳しくは、THREAT_MODEL.md（資産、 攻撃者、信頼境界、脅威ごとの緩和策）と SECURITY.md（脆弱性の報告と開示 ポリシー）を参照してください。

ローカル開発

git clone https://github.com/pensados/sentinelx-cloud-core
cd sentinelx-cloud-core
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
pytest                              # unit tests

本番用以外のハブに接続してエージェントを実行するには、次のようにします。

SENTINELX_HUB_URL=wss://localhost:8000/agent/connect \
  python3 -m sentinelx_core --identity-file /tmp/dev-identity.json

ベンダー提供：pensa-safe-edit

sentinel_edit による実際のファイル変更は、src/sentinelx_core/vendored/pensa_safe_edit.py に ベンダーとして組み込まれた、標準ライブラリのみを使用する小さなモジュールが行います。このモジュールは Python API 経由でプロセス内から呼び出されるため（シェル経由ではありません）、編集処理の中に shell=True は一切ありません。作業には一時ファイルとアトミックな名前変更を使用し、 変更前にタイムスタンプ付きのバックアップを作成して、ファイルのメタデータを保持します。また、 オプションのコミット前バリデーター（json/yaml/toml/python/sh/nginx/systemd のプリセット）を 実行できます。検証に失敗した場合、元のファイルは変更されません。単体または手動で使用できるよう、 pip のコンソールスクリプトエントリポイントとしても登録されています。

関連項目

• sentinelx-cloud-installer — bash + python のインストーラー
• sentinelx-cloud-protocol — ワイヤーフォーマット仕様

ライセンス

Apache License 2.0 — LICENSE を参照してください。