GitLab Stack Validator

GitLab Stack Validator

このスキルは、GitLab スタックプロジェクトを検証し、適切なアーキテクチャパターンに従っており、デプロイ可能な状態であることを確認します。問題の検出と報告に重点を置き、修正には関連スキル（stack-creator、secrets-manager）と連携します。

このスキルを使用するタイミング

ユーザーから次のような依頼があった場合に、このスキルを有効化します。

• GitLab スタックプロジェクトを検証する
• デプロイ前にスタック構成を確認する
• スタックのアーキテクチャと構造を検証する
• ベストプラクティスへの準拠についてスタックを監査する
• スタックが適切なパターンに従っていることを確認する
• デプロイ前の検証チェックを行う
• スタックの健全性チェックまたは準備状況の検証を行う

検証の基本原則

このスキルでは、次のアーキテクチャ原則に従っているスタックを検証します。

1. 構成管理：すべての構成を docker-compose.yml と ./config ディレクトリで管理します
2. シークレット管理：シークレットを ./secrets に保存し、Docker secrets 経由で参照します
3. 環境変数：.env.example テンプレートと対応する .env ファイルを用意します
4. カスタムスクリプトの最小化：コンテナがネイティブのシークレットに対応していない場合に限り、docker-entrypoint.sh を使用します
5. 適切な所有権：root が所有するファイルがなく、すべてのファイルが Docker ユーザーの所有であること
6. 一時ファイル：使用後にクリーンアップされる一時ファイル用の _temporary ディレクトリ
7. Docker のベストプラクティス：Docker 固有のチェックには docker-validation スキルを活用します

検証ワークフロー

ユーザーからスタックの検証を依頼された場合は、次の包括的なワークフローに従います。

フェーズ 1：事前チェック

ステップ 1：スタックプロジェクトの確認

1. 現在のディレクトリがスタックプロジェクトと思われるかどうかを確認します
2. 次の主な目印を探します。
   • docker-compose.yml が存在する
   • ./config、./secrets、または ./_temporary ディレクトリが存在する
   • .env ファイルが存在する
3. スタックプロジェクトでない場合は、確認結果を報告し、初期化するかどうかをユーザーに尋ねます

ステップ 2：コンテキストの収集

1. 必要に応じて、ユーザーに検証範囲を尋ねます。
   • 全体検証か、対象を絞ったチェックか
   • 厳格モードか、許容モードか
   • 希望する出力形式（テキストレポートと JSON のどちらか）
2. カスタムルール用の .stack-validator.yml が存在するか確認します
3. 報告に使用する作業ディレクトリを記録します

フェーズ 2：ディレクトリ構造の検証

ステップ 1：必須ディレクトリ

1. 必須ディレクトリがあるか確認します。
   • ./config - 構成ファイル用ディレクトリ
   • ./secrets - シークレット保存用ディレクトリ
   • ./_temporary - 一時ファイル用ディレクトリ
2. 各ディレクトリが存在しない場合、次の情報を記録します。
   • ディレクトリ名
   • 用途と必要な理由
   • スタックの機能への影響

ステップ 2：ディレクトリのアクセス権

1. ./secrets のアクセス権が制限されている（700 または 600）ことを確認します
2. その他のディレクトリに適切なアクセス権が設定されているか確認します
3. セキュリティ上の影響を伴うアクセス権の問題を報告します

ステップ 3：ディレクトリの所有権

1. プロジェクト内のすべてのディレクトリについて所有権を調べます
2. root が所有するディレクトリを次の情報とともに指摘します。
   • ディレクトリパス
   • 現在の所有者
   • 想定される所有者（現在のユーザーまたは Docker ユーザー）
3. 想定外の所有者が設定されたファイルを指摘します

ステップ 4：.gitignore の検証

1. .gitignore が存在するか確認します
2. 次の項目が除外されていることを確認します。
   • ./secrets または ./secrets/*
   • ./_temporary または ./_temporary/*
   • .env（Git に含めるべきではありません）
3. 除外設定の不足を、セキュリティ上の影響とともに報告します

フェーズ 3：環境変数の検証

ステップ 1：.env ファイルの検証

1. .env ファイルが存在するか確認します
2. .env ファイルを解析し、以下を確認します：
   • 構文エラー
   • 変数定義の重複
   • 必須の可能性がある値の空欄
3. 見つかったすべての環境変数名を記録します

ステップ 2：.env.example の検証

1. .env.example が存在するか確認します
2. 存在しない場合、これは重大な問題です。必要な理由を記録します
3. .env.example を解析して変数名を取得します

ステップ 3：.env の同期確認

1. .env と .env.example の変数を比較します：
   • .env にはあるが、.env.example にはない変数
   • .env.example にはあるが、.env にはない変数
2. これは重要な検証ポイントです。両者は一致している必要があります
3. 不一致があれば、具体的な変数名とともに報告します

ステップ 4：環境変数のセキュリティ

1. .env をスキャンして、シークレットの可能性がある値を確認します：
   • 名前に password、secret、key、token、api を含む変数
   • Base64 エンコードされたように見える値
   • 長いランダム文字列
2. .env でシークレットが検出された場合、セキュリティ上の問題として警告します
3. ./secrets と Docker secrets を使用するよう提案します

フェーズ 4：Docker 設定の検証

ステップ 1：docker-validation スキルの実行

1. docker-validation スキルを使用して、以下を検証します：
   • docker-compose.yml の構文とベストプラクティス
   • Dockerfile（存在する場合）
   • マルチステージビルド
   • セキュリティ設定
2. docker-validation によるすべての指摘事項を収集します
3. 全体的なスタック検証レポートに統合します

ステップ 2：スタック固有の Docker チェック

1. docker-compose.yml を確認し、スタックのパターンを調べます：
   • シークレットがトップレベルの secrets: セクションで定義されている
   • サービスが環境変数ではなく、secrets: キーを使ってシークレットを参照している
   • ボリュームマウントがパターン（./config、./secrets、./_temporary）に従っている
   • 複数のサービスがある場合、ネットワークが適切に定義されている
   • サービスの依存関係で depends_on が正しく使われている

ステップ 3：バージョンの確認

1. docker-compose.yml の先頭に version フィールドがないことを確認します
2. これは最新の Docker Compose 仕様に準拠するためです
3. version フィールドがある場合は、削除するよう警告します

フェーズ 5：シークレット管理の検証

ステップ 1：シークレットディレクトリの確認

1. ./secrets ディレクトリが存在することを確認します
2. 権限が制限されていること（700）を確認します
3. Git の対象から除外されていることを確認します

ステップ 2：Docker シークレットの検証

1. docker-compose.yml を解析し、シークレットの定義を確認します
2. シークレットの定義ごとに、以下を確認します：
   • ./secrets にシークレットファイルが存在する
   • ファイルの権限（600 または 400）
   • Git で追跡されていない
3. 見つからないシークレットファイルを報告します

ステップ 3：シークレット参照の検証

1. 各サービスの secrets: セクションを確認します
2. 参照されているシークレットがトップレベルの secrets で定義されていることを確認します
3. 定義されていないシークレット参照があれば警告します

ステップ 4：環境変数とシークレットの比較

1. サービスの環境変数をスキャンし、シークレットの可能性がある値を確認します
2. 以下のようなパターンを探します：
   • *_PASSWORD
   • *_SECRET
   • *_KEY
   • *_TOKEN
   • API_*
3. 環境変数に機密データが含まれている場合は、代わりにシークレットを使用するよう提案します

ステップ 5：シークレットの露出確認

1. 以下にシークレットが含まれていないか確認します：
   • docker-compose.yml（ハードコードされた値）
   • .env ファイル（代わりに ./secrets に置く必要があります）
   • ./config 内の設定ファイル
   • シェルスクリプト
2. 露出しているシークレットがあれば、重大なセキュリティ問題として報告します

フェーズ 6：設定ファイルの検証

ステップ 1：設定ディレクトリの構成

1. ./config ディレクトリ内のすべてのファイルを一覧表示します
2. （該当する場合は）サービスごとに整理します
3. 適切に整理されているか確認します

ステップ 2：設定ファイルの検証

1. 一般的な設定ファイル形式について、構文を検証します：
   • YAML ファイル（.yml、.yaml）
   • JSON ファイル（.json）
   • INI ファイル（.ini、.conf）
   • TOML ファイル（.toml）
2. 構文エラーがあれば報告します

ステップ 3：設定とシークレットの分離

1. 設定ファイルをスキャンし、シークレットの可能性がある値を確認します
2. ハードコードされたパスワード、トークン、キーを探します
3. 代わりに ./secrets に置くべきシークレットがあれば警告します

ステップ 4：設定ファイルの所有者

1. すべての設定ファイルの所有者を確認します
2. root が所有する設定ファイルがあれば警告します
3. 想定される所有者（現在のユーザー）を報告します

フェーズ 7：スクリプトの検証

ステップ 1：docker-entrypoint.sh の検出

1. docker-entrypoint.sh ファイルを検索します
2. 見つかったファイルごとに、以下を行います：
   • 場所を記録します
   • 本当に必要か確認します
3. コンテナがネイティブのシークレットに対応していない場合にのみ使用されていることを検証します

ステップ 2：スクリプトの権限

1. docker-entrypoint.sh が実行可能であることを確認します（chmod +x）
2. 所有者を確認します（root であってはなりません）
3. 権限に関する問題を報告します

ステップ 3：スクリプト内容の検証

1. スクリプトをスキャンし、以下を確認します：
   • ハードコードされたシークレット（重大な問題）
   • /run/secrets/ からの適切なシークレット処理
   • エラー処理
   • 構文エラー（bash/sh の場合）
2. 見つかった問題を報告します

ステップ 4：必要性の確認

1. docker-entrypoint.sh が本当に必要か確認します
2. サービスがネイティブの Docker シークレットに対応しているか確認します
3. 不要な場合は削除を提案します

フェーズ 8：一時ディレクトリの検証

ステップ 1：ディレクトリの確認

1. ./_temporary が存在することを確認します
2. .gitignore に含まれていることを確認します
3. 権限を確認します

ステップ 2：内容の確認

1. ./_temporary の内容を一覧表示します
2. 以下を確認します：
   • クリーンアップされるべき残存ファイル
   • 容量を消費している大きなファイル
   • 古いファイル（7 日を超えるもの）
3. 空でない場合は、詳細とともに報告します

ステップ 3：使用状況の検証

1. ./_temporary が docker-compose.yml に適切にマウントされているか確認します
2. サービスが一時ファイルに使用していることを確認します
3. 使用されていない場合は指摘します

フェーズ 9：ファイル所有権の監査

ステップ 1：包括的な所有権スキャン

1. find . -type f -user root 2>/dev/null を使用して、root が所有するファイルを見つけます
2. 想定されるディレクトリ（.git、node_modules、vendor）を除外します
3. 見つかった root 所有のファイルをすべて一覧表示します

ステップ 2：問題の分類

1. ディレクトリごとに分類します：
   • root が所有する ./config ファイル
   • root が所有する ./secrets ファイル
   • root が所有するアプリケーションファイル
2. 具体的なパスとともに報告します

ステップ 3：影響の評価

1. root が所有する各ファイルについて、以下を行います：
   • これが問題となる理由を説明します
   • スタックの操作への影響を示します
   • 発生する可能性があるエラーを示します

フェーズ 10：レポートの生成

ステップ 1：すべての調査結果をまとめる

1. 調査結果をカテゴリ別に整理します：
   • ディレクトリ構造
   • 環境変数（.env の同期）
   • Docker の設定
   • シークレット管理
   • 設定ファイル
   • スクリプト（docker-entrypoint.sh）
   • 一時ディレクトリ
   • ファイル所有権
2. 深刻度を割り当てます：
   • ❌ 重大：セキュリティ上の問題、必須コンポーネントの欠落、.env の不一致
   • ⚠️ 警告：ベストプラクティス違反、潜在的な問題
   • ✅ 合格：問題なし

ステップ 2：検証レポートの生成

次の構成で包括的なレポートを作成します：

🔍 GitLab Stack Validation Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Stack: [directory name]
Date: [timestamp]
Mode: [strict/permissive]

📊 SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Passed: [count]
⚠️  Warnings: [count]
❌ Critical: [count]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 DETAILED FINDINGS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[For each validation category]

[Category Icon] [Category Name]: [STATUS]
[If issues found:]
   ❌ [Issue description]
      Location: [file/directory path]
      Impact: [what this affects]
      Details: [specific information]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 OVERALL STATUS: [PASSED/FAILED/WARNINGS]

[If failures or warnings:]
🔧 RECOMMENDED ACTIONS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[Prioritized list of actions needed]
1. [Most critical action]
2. [Next action]
...

💡 NEXT STEPS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- Use stack-creator skill to fix structural issues
- Use secrets-manager skill to properly configure secrets
- Re-run validation after fixes

ステップ 3：実行可能なガイダンスの提供

1. 各問題について、以下を提供します：
   • 問題の明確な説明
   • 重要である理由
   • 修正に役立つ関連スキル
   • 一般的なガイダンス（ただし、実際の修正コマンドは含めません）
2. 深刻度に応じて問題に優先順位を付けます
3. 関連する問題をまとめます

ステップ 4：エクスポートオプション

1. ユーザーが JSON 出力を要求した場合、次の形式でエクスポートします：

   {
     "stack": "directory-name",
     "timestamp": "ISO-8601",
     "summary": {
       "passed": 5,
       "warnings": 2,
       "critical": 1,
       "status": "failed"
     },
     "findings": [
       {
         "category": "environment-variables",
         "status": "critical",
         "issues": [...]
       }
     ]
   }
   

検証カテゴリのリファレンス

1. ディレクトリ構造

• 必須ディレクトリが存在する
• 適切な権限が設定されている
• .gitignore でカバーされている
• 所有権が正しい

2. 環境変数

• .env ファイルが存在し、有効である
• .env.example が存在する
• 重大：.env と .env.example が同期されている
• .env にシークレットが含まれていない

3. Docker の設定

• docker-compose.yml が有効である（docker-validation スキルを使用）
• version フィールドがない
• シークレットが適切に定義されている
• ボリュームがパターンに従っている
• サービスの依存関係が正しい

4. シークレット管理

• ./secrets ディレクトリが安全である
• 参照されるすべてのシークレットが存在する
• 適切な権限が設定されている
• シークレットが公開されていない
• 環境変数にシークレットが含まれていない

5. 設定ファイル

• 適切に整理されている
• 構文が有効である
• シークレットが埋め込まれていない
• 所有権が正しい

6. スクリプト

• docker-entrypoint.sh が必要な場合にのみ使用されている
• 実行可能な権限が設定されている
• ハードコードされたシークレットがない
• シークレットが適切に処理されている

7. 一時ディレクトリ

• 存在し、.gitignore に含まれていること
• 空であるか、想定される一時ファイルのみが含まれていること
• compose ファイルで適切に使用されていること

8. ファイルの所有権

• root が所有するファイルがないこと
• 所有権に一貫性があること
• ユーザー／グループが適切であること

関連スキルとの連携

stack-creator

• 推奨用途：不足しているディレクトリの作成、構造の初期化
• 対応内容：新しいスタックのセットアップ、構造上の問題の修正

secrets-manager

• 推奨用途：シークレットの設定、シークレットファイルの管理
• 対応内容：シークレットの作成／更新、適切なシークレットのセットアップ

docker-validation

• Docker 固有のチェックのため、検証中に直接使用
• 提供内容：Docker Compose および Dockerfile の検証
• スタック検証レポートに統合

検証モード

標準モード（デフォルト）

• すべての問題を警告またはエラーとして報告
• 包括的な調査結果を提示
• 改善案を提案

厳格モード

• 警告がある場合は失敗
• すべてのベストプラクティスへの準拠を必須とする
• 逸脱を一切許容しない

寛容モード

• 重大な問題がある場合のみ失敗
• 警告を許容
• ベストプラクティスへの準拠について、より寛容に対応

設定のサポート

プロジェクトのルートに .stack-validator.yml が存在する場合は、次の設定を尊重してください。

# Validation mode
strict_mode: false

# Whether warnings should fail validation
fail_on_warnings: false

# Paths to exclude from validation
exclude_paths:
  - ./vendor
  - ./node_modules
  - ./_temporary/cache

# Custom validation scripts to run
custom_checks:
  - ./scripts/custom-validation.sh

# Specific checks to skip
skip_checks:
  - temporary-directory-empty

コミュニケーションスタイル

検証結果を報告する際は、次の点に留意してください。

1. 明確かつ率直に：曖昧な表現を避け、問題をはっきりと伝えます
2. 具体的に：正確なファイルパス、行番号、変数名を含めます
3. 実行可能な形で：必要な対応を説明します（自分で対応は行いません）
4. 役立つ情報を提供：問題を修正できる関連スキルを案内します
5. 整理して伝える：関連する問題をまとめ、深刻度に応じて優先順位を付けます
6. 理解を促す：問題となる理由を説明します
7. 簡潔に：詳細を詰め込みすぎず、必要な情報を漏れなく伝えます

重要な検証項目

本番環境向けのスタックでは、次の基準を必ず満たす必要があります。

1. ✅ .env と .env.example が完全に同期している
2. ✅ docker-compose.yml の環境変数にシークレットが含まれていない
3. ✅ ./secrets ディレクトリが存在し、アクセス権限が制限されている
4. ✅ 参照されているシークレットがすべて存在する
5. ✅ ./secrets と ./_temporary が .gitignore に含まれている
6. ✅ root が所有するファイルがない
7. ✅ docker-compose.yml が docker-validation に合格する
8. ✅ git にシークレットが公開されていない
9. ✅ .env ファイルが git で追跡されていない

重要な注意事項

• 読み取り専用：このスキルはファイルを変更しません。検証のみを行います
• 検出重視：問題を報告し、修正は行いません
• 包括的：すべての項目を体系的にチェックします
• 高速：検証は数秒で完了します
• 連携：Docker のチェックには docker-validation スキルを使用します
• 関連スキルを案内：修正に適したスキルをユーザーに案内します

検証フローの例

User: "Validate my stack"

1. Check if docker-compose.yml exists ✅
2. Verify directory structure
   - ./config ✅
   - ./secrets ✅
   - ./_temporary ⚠️ (not in .gitignore)
3. Validate .env configuration
   - .env exists ✅
   - .env.example exists ❌ CRITICAL
4. Run docker-validation skill
   - docker-compose.yml syntax ✅
   - Secrets configuration ⚠️ (using environment vars)
5. Check secrets management
   - ./secrets permissions ✅
   - Secret files exist ✅
6. Scan for ownership issues
   - Found 3 root-owned files in ./config ❌
7. Generate report with findings
8. Suggest: Use stack-creator to add .env.example and fix .gitignore

---

このスキルは、包括的な検証を通じてスタックの品質、安全性、デプロイ準備状況を確保します。