[English](security-hardening.md) | 日本語

# セキュリティ・ハードニングガイド

MAESTRO は LLM 駆動のタスクを実行し、その中でコード実行・Web 取得・ブラウザ操作・（有効なら）SSH コマンドまで行います。**特権サービスとして扱ってください。** このガイドは [SECURITY.md](../SECURITY.md) の基本方針を、「手元で動く」から「他人が到達しても安全」へ移すための実践チェックリストにしたものです。

脆弱性報告の手順は [SECURITY.md](../SECURITY.md)、シークレットの所在とファイル権限は同ファイルの *Secrets and Data* 節を参照。

## 脅威モデル（一段落）

UI/API に到達できる者はタスクを作成でき、タスクはツール（Bash・Web・ブラウザ・ファイル、そして有効なら SSH/MCP）を実行できます。認証が無ければ、ポートに到達できる者は誰でもホスト上でコードを実行できることになります。だから既定のデプロイは**ローカル限定・認証なし**です。以下はそれを安全に広げる手順です。

## 1. ネットワーク公開

- アプリは既定で `127.0.0.1` にバインドし（ベアメタル）、Docker Compose は `127.0.0.1:9876` のみを公開します。認証と TLS が整うまでこのままに。
- 公開する際は、バインド/ポート（`server.port`、Compose のポートマッピング）を意図的に変更し、TLS を前段に置きます（MAESTRO のネイティブ HTTPS `server.tls` か、リバースプロキシ）。

## 2. 認証

認証は**既定で無効**です。ローカル以外へ公開する前に有効化します。

- **OAuth**（Google / Gitea）または**ローカルアカウント**（メール＋パスワード）。`config.yaml` の `auth`、または Settings → Authentication で設定。
- 複数プロバイダを有効にする場合は `auth.primary_provider`（`google` | `gitea` | `local`）を明示し、意図しないログイン経路を防ぐ。
- 管理者になれる範囲を `auth.admin_emails` で制限。
- 安定した `auth.session_secret` を設定（または永続化される `data/secrets/session-secret.key` に委ねる）。複数ノードでは全ノードで共有し、フェイルオーバーでもセッションを維持。

## 3. 認可と可視性

タスク・スケジュール・ジョブは所有者と可視性スコープを持ちます: `private`（所有者＋admin）/ `org`（同一組織のメンバー）/ `public`（全ログインユーザー）。新規リソースは既定を `private` にし、`org`/`public` は意図的にのみ付与。admin は全件閲覧可なので、admin の数は最小に。

## 4. Bash サンドボックス

`Bash` ツールは `safety.bash_sandbox` で制御されるサンドボックス内で動きます。

- `auto`（既定）— bubblewrap があれば使い、無ければ堅牢な許可リスト。
- `always` — **複数ユーザー／信頼できないデプロイでは必須**。bubblewrap が無ければ静かに格下げせず fail-closed。
- `off` — 隔離なし。信頼できる単一運用者のみ。

bubblewrap は非特権ユーザー名前空間を必要とします。[operations/bash-sandbox-provisioning.md](operations/bash-sandbox-provisioning.md)、コンテナは [docker.md](docker.ja.md) を参照。

## 5. 通信のセキュリティ（TLS）

- ネイティブ HTTPS は `server.tls` を有効化、またはリバースプロキシで TLS 終端。
- TLS を前段（プロキシ）で終端する場合は `auth.secure_cookie: true` を設定し、セッションクッキーに `Secure` フラグを付与。ネイティブ TLS では自動で付く。
- 既定の自己署名証明書はブラウザ警告を出すので、他者が使うものには正式な証明書を導入。

## 6. metrics エンドポイント

`/metrics` は運用データを公開します。本番では制限を:

- `bearer_token` を設定（worker / gateway の metrics 設定）、かつ/または
- `allowed_hosts` をスクレイパの送信元 IP に限定。

インターネット公開のデプロイで `/metrics` を開けたままにしないこと。

## 7. ツールと連携

有効化する機能ごとに影響範囲が広がります。信頼できないユーザーへ開放する前に、どのツール・連携が有効かを確認:

- **SSH** — リモートホストでコマンドを実行。資格情報はマスター鍵でエンベロープ暗号化。信頼できる運用者のみ。
- **MCP** — 外部ツールサーバー。資格情報には `MCP_ENCRYPTION_KEY` が必要。
- **ブラウザ** — 実際の Chromium を操作。取得/自動化したコンテンツは信頼できない入力として扱う。

## 8. シークレット

[SECURITY.md](../SECURITY.md) の *Secrets and Data* 節を参照。要点: 生成されるシークレットは `data/secrets/` 配下に `0600` で置かれ、gitignore/dockerignore 済み。コアダンプは復号済みの鍵を含みうるため除外。漏洩が疑われたらローテーションし、監査ログを確認。

## 9. 更新と監視

- リリースを追い、セキュリティ修正を速やかに適用（修正は最新リリースと `main` に入る）。
- 権限・設定変更の後は監査ログを確認。

## 本番チェックリスト

自分以外に公開する前にコピペで確認:

- [ ] 認証を有効化（`auth.*`）、`primary_provider` 設定、`admin_emails` を最小に
- [ ] 安定した `auth.session_secret`（クラスタなら全ノード共有）
- [ ] `safety.bash_sandbox: always`
- [ ] TLS 終端（ネイティブ `server.tls` かプロキシ）＋ `secure_cookie` を整合
- [ ] バインド/ポートを意図したインターフェースに限定
- [ ] `/metrics` を保護（`bearer_token` かつ/または `allowed_hosts`）
- [ ] 新規リソースは既定 `private`、`org`/`public` は意図的に付与
- [ ] SSH/MCP/ブラウザを確認し、必要な分だけ有効化
- [ ] シークレットをバージョン管理・バックアップから除外、ローテーション計画
- [ ] セキュリティ更新を適用する運用体制