From 519e898c10291a8b730f61aebfcf2542f176141b Mon Sep 17 00:00:00 2001 From: oss-sync Date: Tue, 16 Jun 2026 03:38:42 +0000 Subject: [PATCH] sync: update from private repo (2eb6723) --- README.ja.md | 1 + README.md | 1 + SECURITY.md | 3 +- docs/security-hardening.ja.md | 86 ++++++++++++++++++++++++ docs/security-hardening.md | 121 ++++++++++++++++++++++++++++++++++ 5 files changed, 211 insertions(+), 1 deletion(-) create mode 100644 docs/security-hardening.ja.md create mode 100644 docs/security-hardening.md diff --git a/README.ja.md b/README.ja.md index 81d2bf5..dc5b3e6 100644 --- a/README.ja.md +++ b/README.ja.md @@ -66,6 +66,7 @@ scripts/server.sh start # http://localhost:9876 - **[AGENTS.md](AGENTS.md)** / **[CONTRIBUTING.md](CONTRIBUTING.md)** — コントリビュータ向け - **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** — コミュニティ行動規範 - **[SECURITY.md](SECURITY.md)** — セキュリティ方針・脆弱性報告 +- **[docs/security-hardening.md](docs/security-hardening.ja.md)** — 本番ハードニングのチェックリスト ## セキュリティ diff --git a/README.md b/README.md index eca1e25..6db35e8 100644 --- a/README.md +++ b/README.md @@ -66,6 +66,7 @@ For detailed instructions, see **[docs/getting-started.md](docs/getting-started. - **[AGENTS.md](AGENTS.md)** / **[CONTRIBUTING.md](CONTRIBUTING.md)** — for contributors - **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** — community standards - **[SECURITY.md](SECURITY.md)** — security policy and vulnerability reporting +- **[docs/security-hardening.md](docs/security-hardening.md)** — production hardening checklist ## Security diff --git a/SECURITY.md b/SECURITY.md index a2823e7..5054e1d 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -15,7 +15,8 @@ within seven days and coordinate disclosure after a fix is available. ## Deployment Baseline MAESTRO can execute tools, browser actions, and optionally SSH commands. Treat -it as a privileged service: +it as a privileged service. For a step-by-step checklist, see +[docs/security-hardening.md](docs/security-hardening.md). - Keep the service bound to localhost until OAuth authentication is configured. - Put internet-facing deployments behind a TLS reverse proxy. diff --git a/docs/security-hardening.ja.md b/docs/security-hardening.ja.md new file mode 100644 index 0000000..9511248 --- /dev/null +++ b/docs/security-hardening.ja.md @@ -0,0 +1,86 @@ +[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/ブラウザを確認し、必要な分だけ有効化 +- [ ] シークレットをバージョン管理・バックアップから除外、ローテーション計画 +- [ ] セキュリティ更新を適用する運用体制 diff --git a/docs/security-hardening.md b/docs/security-hardening.md new file mode 100644 index 0000000..8db38cf --- /dev/null +++ b/docs/security-hardening.md @@ -0,0 +1,121 @@ +English | [日本語](security-hardening.ja.md) + +# Security Hardening Guide + +MAESTRO runs LLM-driven tasks that execute code, fetch the web, drive a browser, +and optionally run SSH commands. **Treat it as a privileged service.** This +guide turns the baseline in [SECURITY.md](../SECURITY.md) into an actionable, +ordered checklist for moving from "works on my laptop" to "safe for others to +reach." + +For how to report a vulnerability, see [SECURITY.md](../SECURITY.md). For where +secrets live and their file permissions, see its *Secrets and Data* section. + +## Threat model in one paragraph + +Anyone who can reach the UI/API can create tasks, and a task can run tools +(Bash, web, browser, files, and — if enabled — SSH/MCP). Without authentication +that means anyone who can reach the port can run code on the host. The default +deployment is therefore **localhost-only and unauthenticated**; everything below +is about safely widening that. + +## 1. Network exposure + +- The app binds to `127.0.0.1` by default (bare metal) and Docker Compose + publishes only `127.0.0.1:9876`. Keep it that way until auth and TLS are in + place. +- When you do expose it, change the bind/port deliberately (`server.port`, the + Compose port mapping) and front it with TLS — either MAESTRO's native HTTPS + (`server.tls`) or a reverse proxy. + +## 2. Authentication + +Authentication is **off by default**. Before exposing the service beyond +localhost, turn it on: + +- **OAuth** (Google / Gitea) or **local accounts** (email + password). Configure + under `auth` in `config.yaml` or via Settings → Authentication. +- Set `auth.primary_provider` (`google` | `gitea` | `local`) when more than one + provider is enabled to avoid an unintended login path. +- Restrict who becomes admin via `auth.admin_emails`. +- Set a stable `auth.session_secret` (or rely on the persisted + `data/secrets/session-secret.key`); share it across nodes in a multi-node + deployment so sessions survive failover. + +## 3. Authorization and visibility + +Tasks, schedules, and jobs carry an owner and a visibility scope: `private` +(owner + admin), `org` (members of the same organization), or `public` (any +logged-in user). Default new resources to `private` and grant `org`/`public` +only deliberately. Admins can see everything — keep the admin set small. + +## 4. The Bash sandbox + +The `Bash` tool runs inside a sandbox controlled by `safety.bash_sandbox`: + +- `auto` (default) — use bubblewrap when available, otherwise a hardened + allowlist. +- `always` — **required for multi-user / untrusted deployments**; fails closed + if bubblewrap is unavailable rather than silently downgrading. +- `off` — no isolation; only for a trusted single operator. + +bubblewrap needs unprivileged user namespaces. See +[operations/bash-sandbox-provisioning.md](operations/bash-sandbox-provisioning.md) +and, for containers, [docker.md](docker.md). + +## 5. Transport security (TLS) + +- Enable `server.tls` for native HTTPS, or terminate TLS at a reverse proxy. +- Set `auth.secure_cookie: true` whenever TLS terminates upstream (behind a + proxy) so the session cookie carries the `Secure` flag. Native TLS sets it + automatically. +- The default self-signed certificate makes browsers warn; install a real + certificate for anything others use. + +## 6. The metrics endpoint + +`/metrics` exposes operational data. In production, restrict it: + +- set a `bearer_token` (worker and/or gateway metrics config), and/or +- limit `allowed_hosts` to the scraper's source IPs. + +Do not leave `/metrics` open on an internet-facing deployment. + +## 7. Tools and integrations + +Each enabled capability widens the blast radius. Before granting access to +untrusted users, review which tools and integrations are on: + +- **SSH** — runs commands on remote hosts; credentials are envelope-encrypted + with the master key. Enable only for trusted operators. +- **MCP** — external tool servers; credentials require `MCP_ENCRYPTION_KEY`. +- **Browser** — drives a real Chromium; treat fetched/automated content as + untrusted input. + +## 8. Secrets + +See the *Secrets and Data* section of [SECURITY.md](../SECURITY.md). In short: +generated secrets live under `data/secrets/` at mode `0600`, are gitignored and +dockerignored, and core dumps are excluded because they can contain decrypted +keys. Rotate after any suspected exposure and review the audit log. + +## 9. Updates and monitoring + +- Track releases and apply security fixes promptly (fixes land on the latest + release and `main`). +- Review the audit log after permission or configuration changes. + +## Production checklist + +Copy-paste before exposing MAESTRO to anyone but yourself: + +- [ ] Authentication enabled (`auth.*`), `primary_provider` set, `admin_emails` minimal +- [ ] Stable `auth.session_secret` (shared across nodes if clustered) +- [ ] `safety.bash_sandbox: always` +- [ ] TLS terminated (native `server.tls` or a proxy) + `secure_cookie` matched +- [ ] Bind/port restricted to the intended interface +- [ ] `/metrics` protected (`bearer_token` and/or `allowed_hosts`) +- [ ] New resources default to `private`; `org`/`public` granted deliberately +- [ ] SSH/MCP/browser reviewed; enabled only as needed +- [ ] Secrets out of version control and backups; rotation plan in place +- [ ] A process to apply security updates