セキュリティと強化

SnapOtter はファイルを完全にあなたのインフラ上で処理します。プロジェクトの改善に役立てるため、デフォルトで匿名かつ内容を含まないプロダクトアナリティクスとクラッシュレポートを送信します。あなたのファイル、ファイル名、ファイルの内容、OCR の出力、画像のメタデータ、ドキュメントのテキストを送信することは決してありません。任意のフィードバックは、ユーザーが送信したときにのみ、かつアナリティクスが有効な場合にのみ送信され、連絡先フィールドは明示的な連絡先の同意がある場合にのみ含まれます。管理者は Settings > System > Privacy でアナリティクスとフィードバック収集をワンクリックでオフにでき、リビルドは不要です。ファイル処理は常にコンテナ内に留まります。

コンテナは専用の非 root ユーザー（snapotter）として実行され、必要最小限のセットを除くすべての Linux capability が削除されています。完全な脆弱性開示ポリシーとセキュリティアーキテクチャについては、GitHub の SECURITY.md を参照してください。

コンテナの強化

正規の CPU および GPU Compose ファイルが信頼できる情報源です。短縮された例を運用環境にコピーしないでください。確認したリリースタグからファイルをデプロイします。

どちらのスタックも次の制御を適用します。

メモリ、スワップ、CPU、および PID の制限には、暴走したネイティブ処理が含まれています。
すべてのサービスで、すべての Linux 機能が削除されます。アプリケーションは、ボリューム所有権、一方向 gosu ID ドロップ、および正常な信号転送のために CHOWN, SETUID, SETGID, DAC_OVERRIDE, FOWNER, KILL のみを追加し直します。 PostgreSQL と Redis は、公式エントリポイントに必要なサブセットのみを受け取ります。
security_opt: [no-new-privileges:true] は、アプリケーション、PostgreSQL、および Redis コンテナー内のプロセスが追加の権限を取得できないようにします。これは gosu との互換性を維持します。エントリポイントは root として開始され、ボリュームを準備し、専用の snapotter ユーザーにのみドロップされます。
PostgreSQL および Redis のイメージ入力はダイジェストによって固定されます。同様に、アプリケーションは latest ではなく、検証済みのリリースタグまたはダイジェストに固定する必要があります。
ヘルスチェック、制限された JSON ログローテーション、永続的な Redis AOF、および再起動ポリシーは、正規ファイルで一元的に定義されます。

インターネットに接続する展開の場合は、ポート 1349 をループバックにバインドし、維持されているリバースプロキシで TLS を終了します。一意の PostgreSQL および Redis 認証情報を生成し、保護されたファイルまたはシークレットマネージャーにシークレットを保存し、初期管理者パスワードをすぐに変更します。

`read_only` が {#why-read-only-is-not-set} に設定されない理由

PUID/PGID の再マッピングにより起動時に /etc/passwd および /etc/group に書き込まれるため、read_only: true は設定されません。 PUID/PGID の代わりに Docker の --user フラグまたは Kubernetes runAsUser を使用すると、読み取り専用のルートファイルシステムを安全に有効にすることができます。

ネットワーク分離

ファイル処理はローカルですが、デフォルトのインストールは出力のないシステムではありません。テレメトリが有効な場合、匿名の製品分析では PostHog が使用され、クラッシュレポートでは Sentry が使用されます。 SNAPOTTER_TELEMETRY=0 を設定 (または [設定] > [システム] > [プライバシー] で分析を無効に) して両方をオフにします。 SnapOtter は、アップロードされたファイル、ファイル名、OCR 出力、ドキュメントテキスト、またはその他のファイルコンテンツをこれらのイベントに含めることはありません。

その他のアウトバウンドトラフィックは機能主導型です。AI バンドル/モデルのインストールは、署名されたリリース入力をダウンロードします。 URL インポートでは、ユーザーが要求したパブリック URL を取得します。明示的に構成された OIDC、SAML、OpenTelemetry、Webhook、S3 互換ストレージ、または同様の統合は、管理者が選択した宛先に接続します。ランタイムでのモデルのダウンロードはデフォルトで無効です。自動フォールバックダウンロードを明示的に有効にする場合にのみ、SNAPOTTER_ALLOW_MODEL_DOWNLOAD=1 を設定してください。オフラインバンドルインポートは、ランタイムモデルの出力なしで AI 機能をプロビジョニングできます。

ファイアウォールの推奨事項:

シナリオ	アウトバウンドルール
エアギャップ	`SNAPOTTER_TELEMETRY=0` と `SNAPOTTER_ALLOW_MODEL_DOWNLOAD=0` を設定し、オフライン AI バンドルインポートを使用し、URL インポートと外部統合を無効にして、下りをブロックします
デフォルトのテレメトリ	ブラウザ/ネットワークログにリストされている PostHog および Sentry エンドポイントを許可します。ポリシーで許可されていない場合はテレメトリを無効にする
AI バンドルが必要	インストール中に、`huggingface.co, *.xethub.hf.co, cdn-lfs.huggingface.co, github.com, objects.githubusercontent.com, storage.googleapis.com, pypi.org, files.pythonhosted.org` への HTTPS を許可します。次にそれらのホストをブロックします
外部統合	管理者が正確に構成した OIDC/SAML/OTLP/webhook/object-storage 宛先のみを許可します

バンドルアーカイブは、Hugging Face の Xet ストレージから提供されます。これにより、*.xethub.hf.co エンドポイント経由で並行して転送され、複数 GB のバンドルのダウンロードが高速になります。ファイアウォールで huggingface.co は許可されるが *.xethub.hf.co はブロックされる場合でも、インストールは成功しますが、より遅い単一ストリームダウンロードにフォールバックするため、高速パス上に留まるように Xet ホストをホワイトリストに登録します。完全なオフラインインストールでは、これをすべてスキップし、代わりにオフラインバンドルインポートを使用できます。

リバースプロキシ構成 (Nginx、Traefik、Caddy、Cloudflare トンネル) については、導入ガイドを参照してください。

Docker シークレット

本番デプロイでは、シークレットを平文の環境変数として渡すことは避けてください。エントリーポイントは Docker の _FILE 規約をサポートしています。シークレットをファイルとしてマウントし、対応する _FILE 変数にそのパスを設定します。

サポートされるシークレット：

変数	`_FILE` に相当
`DEFAULT_PASSWORD`	`DEFAULT_PASSWORD_FILE`
`COOKIE_SECRET`	`COOKIE_SECRET_FILE`
`OIDC_CLIENT_SECRET`	`OIDC_CLIENT_SECRET_FILE`
`S3_ACCESS_KEY_ID`	`S3_ACCESS_KEY_ID_FILE`
`S3_SECRET_ACCESS_KEY`	`S3_SECRET_ACCESS_KEY_FILE`
`SNAPOTTER_LICENSE_KEY`	`SNAPOTTER_LICENSE_KEY_FILE`

Docker Compose のシークレットを使った例：

yaml

services:
  SnapOtter:
    image: snapotter/snapotter:latest
    environment:
      - AUTH_ENABLED=true
      - DEFAULT_USERNAME=admin
      - DEFAULT_PASSWORD_FILE=/run/secrets/snapotter_password
      - COOKIE_SECRET_FILE=/run/secrets/cookie_secret
    secrets:
      - snapotter_password
      - cookie_secret

secrets:
  snapotter_password:
    file: ./secrets/snapotter_password.txt
  cookie_secret:
    file: ./secrets/cookie_secret.txt

TIP

Docker Compose のシークレット（Swarm なし）には Compose v2.23 以降が必要です。

Kubernetes デプロイ

エントリーポイントは、コンテナがすでに非 root として実行されている（たとえば Kubernetes の runAsUser 経由）ことを検出し、gosu の権限降格を自動的にスキップします。その場合、自らマウントされたボリュームを chown できないため、書き込み可能かどうかを検証し、書き込めない場合は実行可能なガイダンスを出して早期に終了します。fsGroup や外来 UID の構成（TrueNAS、OpenShift）についてはストレージの権限を参照してください。

推奨される Pod の SecurityContext：

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: snapotter
spec:
  replicas: 1
  selector:
    matchLabels:
      app: snapotter
  template:
    metadata:
      labels:
        app: snapotter
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 999
        runAsGroup: 999
        fsGroup: 999
      containers:
        - name: snapotter
          image: snapotter/snapotter:latest
          ports:
            - containerPort: 1349
          securityContext:
            allowPrivilegeEscalation: false
            capabilities:
              drop: [ALL]
          resources:
            requests:
              cpu: "1"
              memory: 2Gi
            limits:
              cpu: "4"
              memory: 6Gi
          livenessProbe:
            httpGet:
              path: /api/v1/health
              port: 1349
            initialDelaySeconds: 60
            periodSeconds: 30
            timeoutSeconds: 5
          readinessProbe:
            httpGet:
              path: /api/v1/health
              port: 1349
            initialDelaySeconds: 10
            periodSeconds: 10
            timeoutSeconds: 5
          volumeMounts:
            - name: data
              mountPath: /data
            - name: workspace
              mountPath: /tmp/workspace
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: snapotter-data
        - name: workspace
          emptyDir:
            medium: Memory
            sizeLimit: 2Gi

runAsUser: 999 が Pod レベルで設定されているため、エントリーポイントは gosu を完全にスキップします。これにより、allowPrivilegeEscalation: false と drop: [ALL] の capability を競合なしに使えます。

リソースのサイジングについては、ハードウェア要件を参照してください。

バックアップとリカバリ

実稼働 Compose スタックは 4 つのボリュームを定義します。 PostgreSQL、Redis、およびファイルの状態が同じ時点を表すように、調整されたバックアップを取得する前にイングレスを停止し、アクティブなジョブを終了させます。

音量	コンテンツ	回復治療
`SnapOtter-pgdata`	PostgreSQL ユーザー、設定、パイプライン、ジョブ、ファイルメタデータ、監査ログ	致命的;ポータブルリカバリにフェイルファスト論理ダンプを使用する
`SnapOtter-data`	保存されたライブラリオブジェクト、ログ、および AI 状態 (`/data/files, /data/logs, /data/ai, /data/ai/venv`)	ボリューム全体をバックアップします。スペースを節約するために、すべての AI 状態を意図的に省略し、そのバンドルを再インストールします
`SnapOtter-redisdata`	耐久性のある BullMQ キュー状態のための Redis AOF	アプリを一時停止して `SAVE` を強制した後、バックアップします。キューに入れられた作業を正確に再開するために必要
`SnapOtter-workspace`	一時オブジェクトストレージキー (`/tmp/workspace/uploads, /tmp/workspace/outputs`)	すべてのジョブがドレインまたはキャンセルされた後はバックアップしないでください。ジョブがアクティブな間は決して破棄しないでください

Compose は通常、ボリューム名の前にプロジェクト名を付けます。 SnapOtter-data などの表示名が Docker ボリューム名であると想定するのではなく、マウントされたコンテナーから実際のソースボリュームを解決します。

データベースのバックアップ

PostgreSQL のカスタムアーカイブ形式を使用し、バックアップが完了したものとして扱う前にアーカイブを検証します。

bash

docker exec SnapOtter-postgres \
  pg_dump --format=custom --no-owner -U snapotter snapotter > snapotter.dump
test -s snapotter.dump
docker exec -i SnapOtter-postgres pg_restore --list < snapotter.dump >/dev/null

# Restore only into a fresh/disposable target first; any SQL error fails the command.
docker exec -i SnapOtter-postgres \
  pg_restore --exit-on-error --clean --if-exists --no-owner \
  -U snapotter -d snapotter < snapotter.dump

すべてのバックアップを分離スタックに復元し、データベースレコードとファイルのチェックサムを確認し、アプリケーションを起動して、すべてのバックアップをテストします。リポジトリの tests/qa/backup-restore-drill.sh は、明示的な QA_IMAGE に対するゲートの解放を自動化します。

代わりにプラットフォームがクラッシュ整合性ボリュームスナップショットを取得する場合は、最初にスタック全体を停止し、すべての重要なボリュームを 1 つのセットとしてスナップショットします。実行中のコンテナからの生の PostgreSQL データディレクトリのコピーは、サポートされている論理バックアップではありません。

ファイルとキューのバックアップ

ファイルとキューのボリュームをキャプチャする前に、アプリケーションを一時停止します。 docker inspect を使用して実際のボリューム名を解決し、Redis に現在の状態を強制的に保持させ、所有権とアクセス許可を保持してアーカイブします。

bash

docker stop SnapOtter
docker exec SnapOtter-redis redis-cli -a "$REDIS_PASSWORD" --no-auth-warning SAVE
docker stop SnapOtter-redis

DATA_VOLUME="$(docker inspect SnapOtter --format '{{range .Mounts}}{{if eq .Destination "/data"}}{{.Name}}{{end}}{{end}}')"
REDIS_VOLUME="$(docker inspect SnapOtter-redis --format '{{range .Mounts}}{{if eq .Destination "/data"}}{{.Name}}{{end}}{{end}}')"

install -d -m 700 backup
docker run --rm -v "$DATA_VOLUME:/source:ro" -v "$PWD/backup:/backup" \
  alpine:3.22@sha256:14358309a308569c32bdc37e2e0e9694be33a9d99e68afb0f5ff33cc1f695dce tar czf /backup/snapotter-data.tar.gz -C /source .
docker run --rm -v "$REDIS_VOLUME:/source:ro" -v "$PWD/backup:/backup" \
  alpine:3.22@sha256:14358309a308569c32bdc37e2e0e9694be33a9d99e68afb0f5ff33cc1f695dce tar czf /backup/snapotter-redis.tar.gz -C /source .
sha256sum backup/snapotter-*.tar.gz > backup/SHA256SUMS

アプリケーションの前に Redis を再起動します。 /data/ai を意図的に除外する場合は、モデルや仮想環境なしで installed.json レコードを保存するのではなく、AI サブツリー全体を削除します。バックアップファイルは暗号化され、アクセスが制御され、SnapOtter を実行しているホストから分離された状態に保たれます。

コンプライアンス成果物

各 SnapOtter リリースには、次のセキュリティアーティファクトが含まれています。

アーチファクト	形式	どこで見つけられますか
件名のバインディングを解放する	正規の JSON + GitHub 証明書	GitHub リリースアセット: `snapotter-v{version}-release-subjects.json`
アーカイブ SBOM	CycloneDX および SPDX JSON	リリースアセット: `snapotter-v{version}-archive-linux-{arch}-sbom.{cdx,spdx}.json`
画像SBOM	CycloneDX および SPDX JSON	リリースアセット: `snapotter-v{version}-image-linux-{arch}-sbom.{cdx,spdx}.json`
脆弱性スキャン	Trivy JSON	`archive-linux-{arch}` または `image-linux-{arch}` プレフィックスが一致するアセットをリリースする
脆弱性スキャン	SARIF	GitHubセキュリティタブ
静的解析	CodeQL (JS/TS + Python)	GitHub セキュリティタブ、毎週 + PR ごとに実行
依存関係のレビュー	GitHub ネイティブ	PR ごとのチェック、重大度の高い追加で失敗する
Python 依存関係の監査	pip-audit	プッシュごとの CI 実行ログ
セキュリティポリシー	Markdown	リポジトリ内の SECURITY.md
依存関係の更新	Dependabot	npm、pip、Docker、アクションの自動化された毎週の PR

独自のスキャンを実行する:

リリース対象のマニフェストをダウンロードし、それがリリースワークフローによって証明されていることを確認します。

bash

gh attestation verify snapotter-v2.2.0-release-subjects.json \
  --repo snapotter-hq/SnapOtter \
  --signer-workflow snapotter-hq/SnapOtter/.github/workflows/release.yml

マニフェストには、releaseTag、releaseCommit、および workflowTriggerCommit が個別に記録されます。 releaseCommit が不変タグから剥がされたコミットであることを確認してから、使用したアーカイブ、イメージ、SBOM、またはスキャンの SHA-256 ダイジェストを subjects のエントリと照合して確認します。この区別は意図的なものです。新しく作成されたリリースコミットをチェックアウトしても、ワークフローの OIDC 資格情報のコミット ID は変更されません。

ダウンロードした SBOM または画像を直接スキャンすることもできます。

bash

# Scan with Grype using the CycloneDX SBOM
grype sbom:snapotter-v2.2.0-image-linux-amd64-sbom.cdx.json

# Scan with Trivy using the SPDX SBOM
trivy sbom snapotter-v2.2.0-image-linux-amd64-sbom.spdx.json

# Scan the Docker image directly
trivy image snapotter/snapotter:2.2.0

INFO

イメージ SBOMs とスキャンは、そのリリース用に公開されたアーキテクチャ固有のイメージを正確に反映しています。アーカイブ SBOMs とスキャンでは、事前構築されたアーカイブを個別に説明します。デプロイメント後にインストールされた AI モデルバンドルは、実行時にダウンロードされるため、これらの SBOMs には含まれません。

基本ツール

最適化

調整

ウォーターマークとオーバーレイ

ユーティリティ

レイアウト

フォーマット

AI ツール

セキュリティと強化

コンテナの強化

`read_only` が {#why-read-only-is-not-set} に設定されない理由

ネットワーク分離

Docker シークレット

Kubernetes デプロイ

バックアップとリカバリ

データベースのバックアップ

ファイルとキューのバックアップ

コンプライアンス成果物

セキュリティと強化 ​

コンテナの強化 ​

read_only が {#why-read-only-is-not-set} に設定されない理由 ​

ネットワーク分離 ​

Docker シークレット ​

Kubernetes デプロイ ​

バックアップとリカバリ ​

データベースのバックアップ ​

ファイルとキューのバックアップ ​

コンプライアンス成果物 ​

セキュリティと強化

コンテナの強化

`read_only` が {#why-read-only-is-not-set} に設定されない理由

ネットワーク分離

Docker シークレット

Kubernetes デプロイ

バックアップとリカバリ

データベースのバックアップ

ファイルとキューのバックアップ

コンプライアンス成果物