agentsh

macOS 注意: ESF（Endpoint Security Framework）+ NE（Network Extension）によるネイティブ macOS の強制適用は Alpha です。ファイル・プロセス・ネットワークイベントがシステム拡張機能から Go ポリシーエンジンへ流れるエンドツーエンドの動作はしますが、リリース間での荒さや破壊的変更が予想されます。本番利用には現時点では Linux を推奨します。

Windows 注意: minifilter ドライバの署名取得に取り組んでいます。それまでは、本番利用では Windows WSL2 モードのみが完全にサポートされます。

AI エージェント向けの、セキュアでポリシー強制型の実行ゲートウェイ。

agentsh はエージェント / ツールの下に位置し、ファイル・ネットワーク・プロセス・シグナルアクティビティ（サブプロセスツリーを含む）を傍受し、定義したポリシーを強制し、構造化監査イベントを出力します。

プラットフォーム注記: Linux は完全な強制適用（セキュリティスコア 100%）を提供します。macOS ESF+NE（スコア 90%）は Alpha で、機能はするものの本番準備はできていません。Windows WSL2 は Linux 相当の完全な強制適用（スコア 100%）を提供します。minifilter ドライバ + AppContainer によるネイティブ Windows（スコア 85%）はドライバ署名待ちです。詳細はプラットフォーム比較マトリクスを参照してください。

agentsh とは？

そのまま使えるシェル / 実行エンドポイント。すべてのコマンド（およびそのサブプロセス）を監査可能なイベントに変換します。
操作単位のポリシーエンジン: allow、deny、approve（人間の承認）、soft_delete、redirect。
完全な I/O 可視性:
- ファイルのオープン / リード / ライト / 削除
- ネットワーク接続 + DNS
- プロセスの開始 / 終了
- PTY アクティビティ
- DLP と使用量追跡を備えた LLM API リクエスト
- 宣言された db_services を介した Postgres 系データベーストラフィック
- シグナルの送信 / ブロック（Linux は強制、macOS/Windows は監査のみ）
- 組み込み PostgreSQL プロキシ を介したデータベースクエリ — ステートメント単位の分類とポリシー適用
- 宣言されたサービス（http_services）を介した送信 HTTP API 呼び出しのルーティング。メソッド単位・パス単位のルール、承認ゲート、フェイルクローズドなホスト強制を備えます
2 つの出力モード:
- 人間にわかりやすいシェル出力
- エージェント / ツール向けのコンパクトな JSON レスポンス

なぜ agentsh なのか？

エージェントのワークフローは、最終的には任意のコード（pip install、make test、python script.py）を実行することになります。従来の「コマンド実行前に承認を求める」方式の制御はツール境界で止まり、そのコマンドの内部で何が起きているかは見えません。

agentsh はポリシーを実行時に強制するため、サブプロセスが行う隠れた作業も管理・記録され、必要に応じて承認されます。

意味のあるブロック: deny → redirect（「steering」のスーパーパワー）

ほとんどのシステムはアクションを deny できます。agentsh はそれを redirect することもできます。

つまり、エージェントが誤ったアプローチ（または力技の回避策）を試みたとき、ポリシーがコマンドを置き換えてガイダンスを返すことで、正しい経路へ誘導できます。これによりエージェントを整備された道に留め、無駄なリトライを減らせます。

例: curl を監査付きラッパーへリダイレクトする```yaml command_rules:

name: redirect-curl commands: [curl, wget] decision: redirect message: "Downloads routed through audited fetch" redirect_to: command: agentsh-fetch args: ["--audit"]

**例: ワークスペース外への書き込みを内部にリダイレクト**```yaml
file_rules:
  - name: redirect-outside-writes
    paths: ["/home/**", "/tmp/**"]
    operations: [write, create]
    decision: redirect
    redirect_to: "/workspace/.scratch"
    message: "Writes outside workspace redirected to /workspace/.scratch"

エージェントは成功した操作を認識します（エラーではありません）が、実際に何がどこに着地するかはあなたが制御します。

コンテナ + agentsh: 組み合わせてこそ効果的

コンテナはホストの攻撃面を隔離します。agentsh はコンテナ内のランタイム可視性とポリシーを追加します。

操作単位の監査（ファイル、ネットワーク、コマンド）により、インストール/ビルド/テスト中に何が発生したかを確認できます。
承認とルールは、最初のコマンドだけでなく、長時間稼働するシェルやサブプロセスツリー全体で維持されます。
マウントされたワークスペース/キャッシュ/認証情報に対するパスレベルの制御。コンテナはネイティブにその粒度を提供しません。
ホストとコンテナで同じ動作をするため、CI とローカル開発は同じポリシーの結果を確認できます。

クイックスタート

インストール

macOS（Homebrew）```bash brew tap canyonroad/tap brew install --cask agentsh

これにより、ESF+NE システム拡張機能を備えた AgentSH アプリバンドルがインストールされます。インストール後、**System Settings > General > Login Items & Extensions** でシステム拡張機能の承認を求められます。

**Linux（GitHub Release から）**

お使いのプラットフォーム用の `.deb`、`.rpm`、または `.apk` を [リリースページ](https://github.com/erans/agentsh/releases) からダウンロードしてください。```bash
# Example for Debian/Ubuntu
sudo dpkg -i agentsh_<VERSION>_linux_amd64.deb

ソースから（Linux）```bash make build sudo install -m 0755 bin/agentsh bin/agentsh-shell-shim /usr/local/bin

**ソースから (macOS)**```bash
# ESF+NE mode (full enforcement — Alpha, requires Xcode 15+)
make build-macos-enterprise

詳細なmacOSビルド手順については、macOSビルドガイドを参照してください。

ローカルで実行```bash

Start the server (optional if using autostart)

./bin/agentsh server --config configs/server-config.yaml

Create a session and run a command (shell output)

SID=$(./bin/agentsh session create --workspace . --json | jq -r .id) ./bin/agentsh exec "$SID" -- ls -la

Structured output for agents

./bin/agentsh exec --output json --events summary "$SID" -- curl https://example.com

### Check what gets enforced

`agentsh detect` はホストを調査し、実際に利用可能な強制プリミティブ — seccomp、Landlock、FUSE、eBPF、ptrace、cgroups — を報告し、ドメインごとの保護スコアと選択されたセキュリティモードにグループ化します。制限されたホスト（Daytona、E2B、Firecracker クラス）で seccomp user-notify リスナーをインストールできない場合、カーネルが単にサポートしているものではなく、*実際に*強制されるモードを報告します。```bash
agentsh detect              # human-readable protection report
agentsh detect config       # emit a config tuned for this host

モードマトリクスと調整用ノブについては、Security Modes を参照してください。

エージェントに使用を指示する (AGENTS.md / CLAUDE.md スニペット)```md

Shell access

Run commands via agentsh, not directly in bash/zsh.
Use: agentsh exec $SID -- <your-command-here>
For structured output: agentsh exec --output json --events summary $SID -- <your-command-here>
Get session ID first: SID=$(agentsh session create --workspace . --json | jq -r .id)

---

### 自動起動（手動デーモン手順は不要）

`agentsh server` を自分で起動する必要は**ありません**。

* 最初の `agentsh exec`（または shim 化された `/bin/sh` / `/bin/bash`）が、`configs/server-config.yaml`（または設定されていれば `AGENTSH_CONFIG`）を使用してローカルサーバーを自動的に起動します。
* そのサーバーは、セッションの存続期間中 FUSE レイヤーとポリシーエンジンを維持します。後続のコマンドはそれを再利用します。
* サーバーのライフサイクルを手動で管理したい場合は、`AGENTSH_NO_AUTO=1` を設定してください。

---

## Docker での使用（シェル shim 付き）

最小限の Debian ベースイメージについては、`Dockerfile.example` を参照してください。

イメージ内でリリースパッケージをインストール（またはビルドをコピー）してから、shim を有効にします。```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --i-understand-this-modifies-the-host

shimをサーバー（サイドカーまたはホスト）に向けてください：```dockerfile ENV AGENTSH_SERVER=http://127.0.0.1:18080

これで、コンテナ内の `/bin/sh -c ...` や `/bin/bash -lc ...` はすべて agentsh を経由します。

### 非対話モードでの強制

デフォルトでは、stdin が TTY でない場合、シムはポリシーをバイパスします（パイプ渡しされるコマンドのバイナリデータを保持するため）。コマンドが常に非対話的でありながら強制適用が必要なプラットフォーム（例: exe.dev、サンドボックス API）では、`--force` を指定してください：```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --force \
  --i-understand-this-modifies-the-host

これは /etc/agentsh/shim.conf を force=true で書き込み、shimは起動時にこれを読み取ります。この設定ファイルは、シェルがどのように起動されても機能します（環境変数やプロファイルスクリプトとは異なります）。プロセス環境内の AGENTSH_SHIM_FORCE=1 も、プロセス単位で同じ効果をもたらします。

推奨パターン: agentsh を同じポッド/サービスのサイドカー（またはPID 1）として実行し、ワークスペースボリュームを共有します。shimはすべてのシェルホップがポリシーの下に留まることを保証します。

ポリシーモデル

決定

allow
deny
approve（人間による承認）
redirect（コマンドを置き換える）
audit（許可＋ログ）
soft_delete（削除を検疫し、復元可能にする）

スコープ

ファイル操作
コマンド
環境変数
ネットワーク（DNS/接続）
データベース（PostgreSQLプロキシ経由のSQLステートメント）
PTY/セッション設定
宣言されたHTTPサービス

評価

最初に一致したルールが優先されます

ルールは名前付きポリシーに格納され、セッションがポリシーを選択します。

デフォルト:

サンプル設定: configs/server-config.yaml
デフォルトポリシー: configs/policies/default.yaml
環境変数による上書き: AGENTSH_POLICY_NAME を許可されたポリシー名（サフィックスなし）に設定します。未設定・無効・許可されていない場合はデフォルトが使用されます。
環境変数ポリシー: ポリシーファイル内の policies.env_policy（allow/deny、max_bytes、max_keys、block_iteration）とコマンドごとの env_* 上書きを設定します。空の許可リストは、組み込みのシークレット拒否リストを備えた最小限の PATH/LANG/TERM/HOME をデフォルトにします。block_iteration を設定すると、env の反復処理を非表示にします（env shim が必要）。
許可リスト: config.yml の policies.allowed を設定します。空の場合はデフォルトのみが許可されます。
オプションの整合性: 読み込み時にポリシーファイルを検証するために、policies.manifest_path にSHA256マニフェストを設定します。

環境変数ポリシーのクイックリファレンス

デフォルト: env_allow がない場合、agentsh は最小限の env（PATH/LANG/TERM/HOME）を構築し、組み込みのシークレットキーを除去します。
上書き: コマンドごとの env_allow/env_deny に加え、env_max_keys/env_max_bytes が実行時に子プロセスの環境を制限・フィルタリングします。
反復のブロック: env_block_iteration: true（グローバルまたはルールごと）は env の列挙を非表示にします。policies.env_shim_path に libenvshim.so を設定すると、agentsh が LD_PRELOAD と AGENTSH_ENV_BLOCK_ITERATION=1 を注入します。
制限: 制限を超えるとエラーになります。env ビルダーはすべてのコマンドの実行前に適用されます。
env_inject: オペレーターが信頼する環境変数をすべてのコマンドに注入し、ポリシーフィルタリングをバイパスします。主な用途: seccomp をバイパスするシェルの組み込みコマンドを無効にするための BASH_ENV。sandbox.env_inject（グローバル）またはポリシーレベルの（グローバルを上書き）で設定します。

ルール例（抜粋）```yaml

version: 1 name: default

file_rules:

name: allow-workspace paths: ["/workspace", "/workspace/**"] operations: [read, open, stat, list, write, create, mkdir, chmod, rename] decision: allow
name: approve-workspace-delete paths: ["/workspace", "/workspace/**"] operations: [delete, rmdir] decision: approve message: "Delete {{.Path}}?" timeout: 5m
name: deny-ssh-keys paths: ["/home//.ssh/", "/root/.ssh/**"] operations: ["*"] decision: deny

network_rules:

name: allow-api domains: ["api.example.com"] ports: [443] decision: allow

command_rules:

name: block-dangerous commands: ["rm", "shutdown", "reboot"] decision: deny

---

### ポリシーの使用```bash
# Start the server with your policy
./bin/agentsh server --config configs/server-config.yaml

# Create a session pinned to a policy
SID=$(./bin/agentsh session create --workspace /workspace --policy default --json | jq -r .id)

# Exec commands; responses include decision + guidance when blocked/approved
./bin/agentsh exec "$SID" -- rm -rf /workspace/tmp

認証

agentsh は複数の認証方式をサポートしています:

タイプ	ユースケース
`api_key`	静的キーを使用したシンプルな導入
`oidc`	エンタープライズ SSO (Okta、Azure AD など)
`hybrid`	両方の方式を受け入れる

承認モード (人間参加型検証用):

local_tty - ターミナルプロンプト (デフォルト)
totp - 認証アプリのコード
webauthn - ハードウェアセキュリティキー (YubiKey)
api - REST によるリモート承認

設定の詳細については SECURITY.md を参照してください。

MCP セキュリティ

ツールのホワイトリスト登録: 許可リスト/拒否リストポリシーにより、どの MCP ツールを呼び出せるかを制御します
バージョンの固定: ツール定義の変更を検出し (ラグプル保護)、応答を設定可能
クロスサーバー検出: データ外部送信パターンをブロックします (サーバー A から読み取り → サーバー B 経由で送信)
レート制限: MCP サーバーとネットワークドメインに対するトークンバケット方式のレート制限

完全な設定オプションについては SECURITY.md を参照するか、MCP 保護デモ を実行してこれらの検出機能の動作を確認してください。

60秒デモ

「理解する」ための最速の方法は、サブプロセスを生成してファイルシステム/ネットワークにアクセスする何かを実行することです。```bash

1) Create a session in your repo/workspace

SID=$(agentsh session create --workspace . --json | jq -r .id)

2) Run something simple (human-friendly output)

agentsh exec "$SID" -- uname -a

→ prints system info, just like normal

3) Run something that hits the network (JSON output + event summary)

agentsh exec --output json --events summary "$SID" -- curl -s https://example.com

→ JSON response includes: exit_code, stdout, and events[] showing dns_query + net_connect

4) Trigger a policy decision - try to delete something

agentsh exec "$SID" -- rm -rf ./tmp

→ With default policy: prompts for approval or denies based on your rules

5) See what happened (structured audit trail)

agentsh exec --output json --events all "$SID" -- ls

→ events[] shows every file operation, even from subprocesses

**JSON出力で確認できる内容：**
- `exit_code`: コマンドの終了ステータス
- `stdout` / `stderr`: 取得された出力
- `events[]`: ポリシー判定を含むすべてのファイル/ネットワーク/プロセス操作
- `policy.decision`: `allow`、`deny`、`approve`、または`redirect`

ヒント：ポリシーをテストするときは、`--output json` を指定したターミナルを開いたままにしておきましょう。何が操作されているかが明確になります。

---

### セッションレポート

セッションのアクティビティをまとめたMarkdownレポートを生成します：```bash
# Quick summary
agentsh report latest --level=summary

# Detailed investigation
agentsh report <session-id> --level=detailed --output=report.md

レポートには以下が含まれます：

決定サマリー（許可、ブロック、リダイレクト）
自動検出（違反、異常）
カテゴリ別のアクティビティ内訳
完全なイベントタイムライン（詳細モード）

パイプラインの例については、CI/CD統合ガイドを参照してください。

ワークスペースチェックポイント

破壊的な操作からの復旧のためにワークスペース状態のスナップショットを作成します:```bash

Create a checkpoint before risky operations

agentsh checkpoint create --session $SID --workspace /workspace --reason "before cleanup"

List checkpoints for a session

agentsh checkpoint list --session $SID

Show what changed since a checkpoint

agentsh checkpoint show --session $SID --workspace /workspace --diff

Preview what rollback would restore (dry-run)

agentsh checkpoint rollback --session $SID --workspace /workspace --dry-run

Restore workspace to checkpoint state

agentsh checkpoint rollback --session $SID --workspace /workspace

Clean up old checkpoints

agentsh checkpoint purge --session $SID --older-than 24h --keep 5

**自動チェックポイント:** 有効にすると、agentsh は危険なコマンド（`rm`、`mv`、`git reset`、`git checkout` など）の実行前に自動的にチェックポイントを作成します。`sessions.checkpoints.auto_checkpoint` で設定します。

完全な設定オプションについては [SECURITY.md](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md#checkpoint-and-rollback) を参照してください。

---

### LLM プロキシと DLP

agentsh には、エージェントからのすべての LLM API リクエストをインターセプトする組み込みプロキシが含まれています:```bash
# Check proxy status for a session
agentsh proxy status <session-id>

# View LLM-specific events
agentsh session logs <session-id> --type=llm

特徴:

自動ルーティング: ANTHROPIC_BASE_URL と OPENAI_BASE_URL を設定し、エージェントSDKがプロキシ経由でルーティングされるようにします
カスタムプロバイダー: LiteLLM、Azure OpenAI、vLLM、または企業ゲートウェイにルーティングします
DLP 秘匿化: PII（メールアドレス、電話番号、APIキーなど）はLLMプロバイダーに到達する前に秘匿化されます
カスタムパターン: 機密データの組織固有のパターンを定義します
使用量トラッキング: コスト帰属のためにトークン数を抽出してログに記録します
監査証跡: すべてのリクエスト/レスポンスがセッションストレージに記録されます

プロバイダー設定:```yaml proxy: mode: embedded providers: anthropic: https://api.anthropic.com # Default Anthropic API openai: https://api.openai.com # Default OpenAI API

# Or use alternative providers:
# openai: http://localhost:8000         # LiteLLM / vLLM
# openai: https://your-resource.openai.azure.com  # Azure OpenAI
# anthropic: https://llm.corp.example.com         # Corporate gateway

**DLP 設定:**```yaml
dlp:
  mode: redact
  patterns:
    email: true
    api_keys: true
  custom_patterns:
    - name: customer_id
      display: identifier
      regex: "CUST-[0-9]{8}"

完全な設定オプションについては、LLMプロキシのドキュメントを参照してください。

同じプロキシは、宣言された http_services エントリ（メソッド単位・パス単位のルールを持つ名前付き API アップストリーム）もディスパッチします。詳細については、宣言済み HTTP サービスと HTTP サービスクックブックを参照してください。

データベースアクセス制御（現在は Postgres のみ）

agentsh は、db_services、database_connection_rules、database_rules を通じて、宣言されたデータベースサービスにポリシーを適用できます。現在の実装は Postgres ファミリーのみです。PostgreSQL がサポート対象で、Aurora Postgres は同じ経路を使用し、Redshift/CockroachDB は Postgres 互換の方言としてベータカバレッジを備えています。MySQL、MongoDB、Snowflake、BigQuery、Databricks、ClickHouse、MSSQL、Cassandra、Redis、Oracle はロードマップ項目であり、現在のランタイムではサポートされていません。

現在の Postgres サポートには以下が含まれます：

接続の許可/拒否/承認/監査判定。
PostgreSQL ワイヤプロトコル v3 のステートメント分類。Simple Query、Extended Query、SQL プリペアドステートメント、COPY、FunctionCall 拒否、トランザクション状態、CancelRequest マッピングを含みます。
拒否を優先する、オブジェクト単位の厳密なポリシーカバレッジ。
解決済みオブジェクトポリシーのためのカタログベースのリレーション/関数セレクター。
読み取り専用 Postgres リレーション置換のための安全なランタイム redirect。
CI でのバイパス検出と、実 Postgres を使用した Docker E2E カバレッジ。

Postgres プロキシのランタイムは、現在のところ Linux 専用のインプロセスコードです。データベースの強制には、ネイティブ Linux、WSL2、または Linux VM 環境を使用してください。

データベースアクセス制御とポリシードキュメントを参照してください。

ポリシー生成

観測されたセッション動作から制限的なポリシーを生成します（「プロファイル作成→ロック」ワークフロー）：```bash

Generate policy from latest session

agentsh policy generate latest --output=ci-policy.yaml

Generate with custom name and threshold

agentsh policy generate abc123 --name=production-build --threshold=10

Quick preview to stdout

agentsh policy generate latest

生成されるポリシー:
- セッション中に観測された操作のみを許可します
- 同じディレクトリに多数のファイルがある場合、パスをグロブにグループ化します
- サブドメインをワイルドカードにまとめます（例: `*.github.com`）
- リスクの高いコマンド（curl、wget、rm）を引数パターンでフラグ付けします
- ブロックされた操作をレビュー用にコメントアウトしたルールとして含めます

**ユースケース:**
- **CI/CD ロックダウン**: ビルド/テスト実行をプロファイリングし、将来の実行をその動作にロックします
- **エージェントサンドボックス化**: AI エージェントにタスクを実行させ、将来の実行用にポリシーを生成します
- **コンテナプロファイリング**: ワークロードをプロファイリングし、本番用の最小ポリシーを生成します

---

## データベースアクセス（PostgreSQL）

agentsh には、データベースアクセスをエージェント対応かつポリシー管理可能にする組み込みの **PostgreSQL プロキシ** が含まれています。これは Postgres ワイヤプロトコルを話し、すべてのステートメントを *エフェクト*（読み取り、書き込み、DDL、DCL、トランザクション/セッション制御、一括 `COPY`/エクスポート、…）のリストに分類し、各エフェクトを `database_rules` に対して評価してから上流に転送します。これにより、`UPDATE`、`DROP`、またはスコープ指定なしの `DELETE` も、ファイル書き込みやネットワーク接続と同じように管理されます。

- **エフェクト単位の複数オブジェクト評価** — ルールは collect-all / **any-deny-wins**（最も制限の厳しい動詞が優先）であり、先頭一致ではありません。
- **判定:** `allow`、`deny`、`approve`（人間による承認）、`audit`、およびステートメントレベルの `redirect`。
- **`require_where` ガード** — `WHERE` 句がないトップレベルの `UPDATE`/`DELETE` を拒否します。
- **接続レベルのルール**（`database_connection_rules`）は、宣言されたどの `db_service` にどのセッションが到達できるかを制御します。
- **認証 + ステートメント監査イベント**をすべての接続とクエリに対して生成します。ステートメントテキストのロギングは設定可能です（`policies.db.log_statements: none | parameters_redacted | full`）。

フェーズ 1 は PostgreSQL v3 ワイヤプロトコルをカバーします（方言: `postgres`、`aurora_postgres`。`redshift` / `cockroachdb` はベータ版）。レプリケーションおよび GSSAPI 暗号化接続はデフォルトで拒否されます。```yaml
database_rules:
  # normal reads + updates on the declared service
  - name: app-read-and-update
    db_service: appdb
    operations: [READ, UPDATE]
    decision: allow

  # allow UPDATE/DELETE only when scoped by a WHERE clause
  - name: app-guard-unscoped-dml
    db_service: appdb
    operations: [UPDATE, DELETE]
    require_where: true
    decision: allow

  # block schema/DDL mutations; terminate the transaction on violation
  - name: app-deny-ddl
    db_service: appdb
    operations: [CREATE, DROP, ALTER, EXPORT]
    decision: deny
    deny_mode_in_tx: terminate
    message: "appdb is read+update only. Requested: {{.Operation}}"

Database Access Control spec の完全な操作分類、影響モデル、接続ルール、および回避不可能性脅威モデルについては、そちらを参照してください。

ネットワークリダイレクト

agentsh は DNS 接続と TCP 接続を透過的にリダイレクトでき、コードを変更せずに API 呼び出しを企業プロキシ経由でルーティングしたり、AI プロバイダーを切り替えたりするユースケースを可能にします。

DNS リダイレクト

DNS 解決を傍受して、設定された IP アドレスを返します：```yaml dns_redirect:

match: "api.anthropic.com" redirect_ip: "10.0.0.50" visibility: audit_only on_failure: fail_closed
match: ".*\.openai\.com" # Regex pattern redirect_ip: "10.0.0.51" visibility: warn

### 接続リダイレクト

TCP接続をオプションのTLS処理付きで別の宛先にリダイレクトします：```yaml
connect_redirect:
  - match: "api.anthropic.com:443"
    redirect_to: "vertex-proxy.internal:8443"
    tls_mode: passthrough          # Forward encrypted traffic unchanged
    visibility: silent

  - match: "api.openai.com:443"
    redirect_to: "azure-proxy.internal:443"
    tls_mode: rewrite_sni          # Modify SNI in TLS ClientHello
    rewrite_sni: "azure-openai.example.com"
    visibility: audit_only

オプション

プラットフォームサポート

ユースケース

APIゲートウェイルーティング: Anthropic/OpenAI の呼び出しを企業の LLM ゲートウェイ経由にルーティングする
プロバイダー切り替え: Claude API を GCP Vertex AI や Azure OpenAI にリダイレクトする
テスト: 本番 API をモックサーバーにリダイレクトする
コンプライアンス: すべての LLM トラフィックを監査プロキシ経由に強制する

シグナルフィルタリング

agentsh はプロセス間で送信されるシグナル（kill, SIGTERM など）をインターセプトし、どのシグナルがどのターゲットに到達できるかをポリシーベースで制御します。

プラットフォームサポート

シグナルルールの例```yaml

signal_rules:

Allow signals to self and children

name: allow-self signals: ["@all"] target: type: self decision: allow
name: allow-children signals: ["@all"] target: type: children decision: allow

Redirect SIGKILL to graceful SIGTERM

name: graceful-kill signals: ["SIGKILL"] target: type: children decision: redirect redirect_to: SIGTERM

Block fatal signals to external processes

name: deny-external-fatal signals: ["@fatal"] target: type: external decision: deny

### シグナルグループ

- `@all` - すべてのシグナル（1〜31）
- `@fatal` - SIGKILL、SIGTERM、SIGQUIT、SIGABRT
- `@job` - SIGSTOP、SIGCONT、SIGTSTP、SIGTTIN、SIGTTOU
- `@reload` - SIGHUP、SIGUSR1、SIGUSR2

### ターゲットタイプ

- `self` - 自身にシグナルを送るプロセス
- `children` - 直接の子プロセス
- `descendants` - すべての子孫プロセス
- `session` - agentsh セッション内の任意のプロセス
- `external` - セッション外の PID
- `system` - PID 1 とカーネルスレッド

完全な設定オプションについては、[ポリシードキュメント](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md#signal-rules) を参照してください。

---

## macOS ファイル I/O モニタリング

macOS では、agentsh は Endpoint Security Framework（ESF）を使用してファイル I/O を監視し、AUTH と NOTIFY の両方のイベントにサブスクライブします。追跡対象の操作には、ファイルのオープン、作成、削除、名前変更、書き込み（close-modified 経由で検出）、および macOS 26 以降では属性変更イベントによる chmod と chown が含まれます。すべてのファイルイベントは PID ベースの解決を通じて発信元のセッションとコマンドに帰属され、サブプロセスツリー全体にわたる完全な監査証跡を提供します。

ESF はカーネルレベルの許可/拒否の強制を提供しますが、Linux FUSE のような透過的なファイルインターセプトはサポートしません。インターセプトを必要とするポリシーアクション（`redirect`（パス書き換え）や `soft_delete`（検疫）など）は、拒否＋ガイダンスとして実装されています。操作は ESF レベルでブロックされ、エージェントは正しいパスで再試行するか、ファイルが保護されていることを認識するよう指示を受け取ります。イベントストリームの詳細は [macOS ESF+NE アーキテクチャドキュメント](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-esf-ne-architecture.md) を、アクションごとの動作は [ポリシードキュメント](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md#file-rule-actions-on-macos-esf) を参照してください。

---

## スターターポリシーパック

すでにデフォルトポリシー（`configs/policies/default.yaml`）があります。これらのオピニオン入りパックは個別のファイルとして提供されているため、チームは任意のものを選択できます:

* **[`policies/dev-safe.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/dev-safe.yaml)**: ローカル開発に安全
  * ワークスペースの読み書きを許可
  * ワークスペース内の削除を承認
  * `~/.ssh/**`、`/root/.ssh/**` を拒否
  * ネットワークを許可リスト登録済みのドメイン/ポートに制限

* **[`policies/ci-strict.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/ci-strict.yaml)**: CI ランナーに安全
  * ワークスペース外のすべてを拒否
  * 成果物レジストリを除く外向きネットワークを拒否
  * 明示的に許可されない限り対話型シェルを拒否
  * すべてを監査（サマリーイベント）

* **[`policies/agent-sandbox.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/agent-sandbox.yaml)**: 「エージェントが未知のコードを実行する」モード
  * デフォルト拒否＋明示的な許可リスト
  * 資格情報/パスへのアクセスをすべて承認
  * ネットワークツールの使用を内部プロキシ/ミラーにリダイレクト
  * 破壊的な操作をソフト削除して簡単に復元可能に

---

## AI アシスタント統合の例

agentsh を使用するように AI コーディングアシスタントを設定するための、すぐに使えるスニペット:

* **[Claude Code](https://github.com/canyonroad/agentsh/blob/HEAD/examples/claude/)** - Claude Code 統合用の CLAUDE.md スニペット
* **[Cursor](https://github.com/canyonroad/agentsh/blob/HEAD/examples/cursor/)** - agentsh 統合用の Cursor ルール
* **[AGENTS.md](https://github.com/canyonroad/agentsh/blob/HEAD/examples/agents/)** - 汎用 AGENTS.md スニペット（複数の AI ツールで動作）

> **注:** これらの例は、AI エージェントをコンテナ内で実行することが現実的ではないローカル開発シナリオ向けです。本番環境や CI/CD 環境では、シェルシムをインストールしたコンテナ内でエージェントを実行することを推奨します—[Docker での使用](#use-in-docker-with-the-shell-shim) を参照してください。

---

## リファレンス

* **MCP 保護デモ:** [`agentsh-mcp-protection-demo`](https://github.com/canyonroad/agentsh-mcp-protection-demo) - クロスサーバー流出検出、ラグプルブロッキング、ポリシー生成のライブデモ
* **セキュリティと脅威モデル:** [`SECURITY.md`](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md) - agentsh が防御する脅威、既知の制限、オペレーターチェックリスト
* **外部 KMS:** [`SECURITY.md#external-kms-integration`](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md#external-kms-integration) - 監査整合性キー用の AWS KMS、Azure Key Vault、HashiCorp Vault、GCP Cloud KMS
* 設定テンプレート: [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/server-config.yaml)
* デフォルトポリシー: [`configs/policies/default.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/default.yaml)
* サンプル Dockerfile（シム付き）: [`Dockerfile.example`](https://github.com/canyonroad/agentsh/blob/HEAD/Dockerfile.example)
* **ポリシードキュメント:** [`docs/operations/policies.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md) - ポリシー変数、シグナルルール、ネットワークリダイレクト
* **データベースアクセス制御:** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/agentsh-db-access-spec.md) - Postgres 専用のデータベース強制スコープ、ポリシーセマンティクス、リダイレクト動作、ロードマップ
* **コマンドポリシークックブック:** [`docs/cookbook/command-policies.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/command-policies.md) - 新しいバイナリを許可する方法、`exec` の代わりに `wrap` を使用するタイミング、拒否のデバッグ方法
* **HTTP サービスクックブック:** [`docs/cookbook/http-services.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/http-services.md) - ルールと承認ゲーティングを使用して、宣言されたサービスを通じて外向き HTTP API 呼び出しをルーティングするレシピ
* **サンドボックス SDK 統合クックブック:** [`docs/cookbook/sandbox-sdk-integrations.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/sandbox-sdk-integrations.md) - agentsh サーバーの兄弟プロセスとしてコマンドが実行される Tensorlake / E2B / Modal / Daytona 向けの `shim_install` 設定
* **ポリシー作成スキル:** [`skills/`](https://github.com/canyonroad/agentsh/blob/HEAD/skills/) - Claude Code、NanoClaw などでポリシーを作成・編集するための AI アシスタントスキル
* **プラットフォーム比較:** [`docs/platform-comparison.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/platform-comparison.md) - プラットフォームごとの機能サポート、セキュリティスコア、パフォーマンス
* **Bubblewrap vs agentsh:** [`docs/bubblewrap-vs-agentsh-comparison.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/bubblewrap-vs-agentsh-comparison.md) - Linux コンテナサンドボックスにおける Bubblewrap との比較
* **データベースアクセス制御:** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/agentsh-db-access-spec.md) - PostgreSQL プロキシの分類、影響モデル、`database_rules`、接続ルール、脅威モデル
* **セキュリティモードと `detect`:** [`docs/security-modes.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/security-modes.md) - 強制モード、保護スコア、および `agentsh detect` がレポートする内容
* **seccomp:** [`docs/seccomp.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/seccomp.md) - システムコールフィルタリング、execve インターセプト、ソケットファミリーブロッキング
* **ptrace モード:** [`docs/ptrace-support.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/ptrace-support.md) - 制限付きコンテナ向けの PTRACE_SEIZE 強制（`attach_mode`、seccomp プリフィルタ）
* **eBPF:** [`docs/ebpf.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/ebpf.md) - eBPF ネットワークトレーシング＆ポリシー強制
* **LLM プロキシと DLP:** [`docs/llm-proxy.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/llm-proxy.md) - 組み込みプロキシ設定、DLP パターン、使用状況トラッキング
* **macOS ビルドガイド:** [`docs/macos-build.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-build.md) - ESF+NE ビルド手順
* **macOS ESF+NE アーキテクチャ:** [`docs/macos-esf-ne-architecture.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-esf-ne-architecture.md) - System Extension、XPC、デプロイメントの詳細
* **macOS XPC サンドボックス:** [`docs/macos-xpc-sandbox.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-xpc-sandbox.md) - サンドボックス化されたプロセスの XPC/Mach IPC 制御
* 環境変数（すべての `AGENTSH_*` オーバーライド、自動起動トグル、トランスポート選択）: [`docs/spec.md` §15.3 "Environment Variables"](https://github.com/canyonroad/agentsh/blob/HEAD/docs/spec.md#153-environment-variables)
* アーキテクチャとデータフロー（FUSE＋ポリシーエンジン＋API）: [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/server-config.yaml) と [`internal/netmonitor`](https://github.com/canyonroad/agentsh/blob/HEAD/internal/netmonitor) のインラインコメント
* CLI ヘルプ: `agentsh --help`、`agentsh exec --help`、`agentsh shim --help`

---

エージェントのために、エージェントの助けを借りて作成されました。

`visibility`	`silent`, `audit_only`, `warn`	リダイレクトがどのように記録・表示されるか
`on_failure`	`fail_closed`, `fail_open`, `retry_original`	リダイレクトが失敗した場合の動作
`tls_mode`	`passthrough`, `rewrite_sni`	接続リダイレクト時のTLS処理

DNSリダイレクト	✅ eBPF	✅ pf/proxy	✅ WinDivert
接続リダイレクト	✅ eBPF	✅ pf/proxy	✅ WinDivert
SNI書き換え	✅	✅	✅

Linux	はい (seccomp user-notify)	はい	はい
macOS	いいえ	いいえ	はい (ES)
Windows	一部	いいえ	はい (ETW)

agentsh

人気

agentsh

agentsh とは？

なぜ agentsh なのか？

意味のあるブロック: deny → redirect（「steering」のスーパーパワー）

コンテナ + agentsh: 組み合わせてこそ効果的

クイックスタート

インストール

ローカルで実行```bash

Start the server (optional if using autostart)

Create a session and run a command (shell output)

Structured output for agents

エージェントに使用を指示する (AGENTS.md / CLAUDE.md スニペット)```md

Shell access

ポリシーモデル

決定

スコープ

評価

環境変数ポリシーのクイックリファレンス

ルール例（抜粋）```yaml

認証

MCP セキュリティ

60秒デモ

1) Create a session in your repo/workspace

2) Run something simple (human-friendly output)

→ prints system info, just like normal

3) Run something that hits the network (JSON output + event summary)

→ JSON response includes: exit_code, stdout, and events[] showing dns_query + net_connect

4) Trigger a policy decision - try to delete something

→ With default policy: prompts for approval or denies based on your rules

5) See what happened (structured audit trail)

→ events[] shows every file operation, even from subprocesses

ワークスペースチェックポイント

Create a checkpoint before risky operations

List checkpoints for a session

Show what changed since a checkpoint

Preview what rollback would restore (dry-run)

Restore workspace to checkpoint state

Clean up old checkpoints

データベースアクセス制御（現在は Postgres のみ）

ポリシー生成

Generate policy from latest session

Generate with custom name and threshold

Quick preview to stdout

ネットワークリダイレクト

DNS リダイレクト

オプション

プラットフォームサポート

ユースケース

シグナルフィルタリング

プラットフォームサポート

シグナルルールの例```yaml

Allow signals to self and children

Redirect SIGKILL to graceful SIGTERM

Block fatal signals to external processes