7049a874f3
Open-source release of MAESTRO, an agent orchestration platform that runs LLM-driven tasks through sandboxed tools, with a web UI. Apache-2.0. See README.md and docs/ (getting-started, configuration, architecture).
88 lines
4.7 KiB
Markdown
88 lines
4.7 KiB
Markdown
# Bash ツール
|
||
|
||
シェルコマンド実行ツール。**用途は限定されている**。
|
||
|
||
## 許可される用途
|
||
|
||
- ファイル操作: `cp`, `mv`, `rm`, `mkdir`, `ls`, `find`
|
||
- テキスト処理: `cat`, `grep`, `sed`, `awk`, `head`, `tail`, `sort`, `uniq`, `wc`
|
||
- Python スクリプト実行: `python3 script.py`、`python3 -c "..."` （データ処理・グラフ生成等）
|
||
- Git の参照系: `git log`, `git diff`, `git status` （履歴・差分の確認）
|
||
- アーカイブ: `tar`, `zip`, `unzip`
|
||
|
||
## 禁止される用途
|
||
|
||
❌ **パッケージ・ソフトウェアのインストール一切**
|
||
- `apt install`, `apt-get install`
|
||
- `pip install`, `pip3 install`
|
||
- `npm install`, `yarn add`
|
||
- `curl ... | sh`, `wget ... | bash`
|
||
- `cargo install`, `go install`
|
||
|
||
❌ **永続的システム変更**
|
||
- `systemctl`, `service` の操作
|
||
- `crontab`, `at` の登録
|
||
- `chmod` で権限を緩和する操作
|
||
|
||
❌ **ネットワーク経由のダウンロード（コードや実行可能物）**
|
||
- `curl https://.../install.sh` 系
|
||
- 必要なら DownloadFile ツールを使う
|
||
|
||
## なぜインストールが禁止か
|
||
|
||
- ジョブ実行環境はサンドボックス化されており、永続化されない
|
||
- 必要な機能は専用ツール（`allowed_tools` に列挙されたもの）で提供される
|
||
- インストールが必要 = ツールの設計が足りないので、ユーザーに報告して機能追加を依頼する
|
||
|
||
## 代替
|
||
|
||
「○○ をインストールしたい」と思ったときの代替策:
|
||
|
||
| やりたいこと | 専用ツールで代替 |
|
||
|-------------|------------------|
|
||
| HTTP リクエスト | WebFetch / DownloadFile |
|
||
| HTML パース | BrowseWeb |
|
||
| 画像加工 | AnnotateImage / ReadImage |
|
||
| OCR | OCRTool / BatchOCRTool |
|
||
| Office ファイル読み込み | ReadPdf / ReadExcel / ReadDocx / ReadPPTX |
|
||
| 音声書き起こし | TranscribeAudio |
|
||
| データベース | SQLite |
|
||
| 検索 | WebSearch / SearchKnowledge |
|
||
|
||
## サンドボックス機構 (`safety.bash_sandbox`)
|
||
|
||
Bash 実行の隔離方式を選ぶ。**2 つの設定は直交する**:
|
||
|
||
- `safety.bash_sandbox`: 隔離機構を選ぶ — `auto`（既定）/ `always` / `off`
|
||
- `safety.bash_unrestricted`: コマンドホワイトリストを適用するか否か（`true` で撤廃）。**bwrap が走るかどうかは制御しない**（それは `bash_sandbox` の役割）
|
||
|
||
| `bash_sandbox` | 挙動 |
|
||
|----------------|------|
|
||
| `auto`（既定） | bwrap があれば bwrap サンドボックス、無ければ hardened（whitelist + パススコープ + env スクラブ）にフォールバック |
|
||
| `always` | bwrap を強制。bwrap 不在なら**起動失敗**（本番推奨） |
|
||
| `off` | bwrap を使わず exec（**env スクラブと、unrestricted でなければ whitelist + パススコープは維持**）。デバッグ用・非推奨 |
|
||
|
||
### bwrap サンドボックスの構成
|
||
|
||
| マウント | 種別 |
|
||
|---------|------|
|
||
| タスクの workspace (`{worktreeDir}/local/{taskId}/`) | read-write bind |
|
||
| `/usr`, `/bin`, `/sbin`, `/lib`, `/etc` | read-only bind |
|
||
| `/lib64` (存在する場合) | read-only bind |
|
||
| `/tmp` | private tmpfs |
|
||
| `/proc`, `/dev` | proc / dev |
|
||
|
||
**マウントされないもの**: `/home`, 他タスクの workspace、ホストの `/tmp` など。他ユーザーの workspace にはファイルシステムレベルでアクセス不可。
|
||
|
||
**環境変数**: `--clearenv` で全消去後、`PATH`/`HOME`/`LANG`/`LC_ALL`/`TZ`/`TERM`/`TMPDIR` の最小 allowlist のみ注入する。`MCP_ENCRYPTION_KEY` 等のシークレットはサンドボックス内から見えない。hardened フォールバック経路も同じ allowlist で exec する。
|
||
|
||
**ネットワーク**: `--unshare-net` で隔離（ループバックのみ）。bash からの外向き通信は不可 — Web 取得は SSRF ガード付きの WebFetch / DownloadFile / MCP 経由に一本化されている。
|
||
|
||
**パッケージ**: 各 Bash コールは独立した bwrap サンドボックスで実行され（揮発 `/tmp`・毎回新しい名前空間）、`/usr` は read-only。よって `pip install` / `npm install` は永続せず、全モードで明示的に拒否される。必要な Python パッケージは `runtime/python-requirements.txt` にプリベイクされ、システム python（read-only bind）から import できる。
|
||
|
||
### 前提条件 (`always` / bwrap 経路)
|
||
|
||
- コンテナ/ホストで **user namespace** が有効であること (PVE: `features: nesting=1`)
|
||
- `bwrap` バイナリがインストール済みであること
|
||
- `bash_sandbox: always`（または `bash_unrestricted: true`）では起動時に bwrap の動作確認を行い、失敗時はエラー終了する。`auto` では失敗時に警告ログを出し hardened へフォールバック
|