dockerfile-validator

Dockerfile バリデーター

決定論的な手順で Dockerfile を検証し、重要度を明確に報告するとともに、ツールやネットワークアクセスに制約がある場合の明示的な代替手段を示します。

トリガーフレーズ

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

• 「この Dockerfile を検証して」
• 「Dockerfile の lint／チェックをして」
• 「Dockerfile のセキュリティスキャンをして」
• 「Docker イメージのサイズ／ビルド時間を最適化して」
• 「マージ前に Dockerfile をレビューして」
• 「Dockerfile.prod／Dockerfile.dev の問題を見つけて」

使用する場合／使用しない場合

次の場合にこのスキルを使用します。

• 構文と lint の検証
• セキュリティとシークレットのチェック
• ベストプラクティスとパフォーマンスのレビュー
• CI/CD または本番環境向けの Dockerfile の強化

次の場合はこのスキルを使用しないでください。

• Dockerfile を新規作成する（dockerfile-generator を使用）
• コンテナの実行、ランタイム動作のデバッグ、イメージレジストリの操作

このスキル内のローカルファイル

• バリデータースクリプト：scripts/dockerfile-validate.sh
• 参照資料：
  • references/security_checklist.md
  • references/optimization_guide.md
  • references/docker_best_practices.md
• Dockerfile の例：examples/*.Dockerfile

決定論的な実行フロー（必須）

以下の手順を順番に実行します。文書化された代替分岐が適用される場合を除き、手順を省略しないでください。

1. 事前確認とパスの設定

リポジトリのルートを作業ディレクトリとします。

cd /path/to/repo
SKILL_DIR="devops-skills-plugin/skills/dockerfile-validator"
TARGET_DOCKERFILE="Dockerfile"   # replace when user provides a path

ツールを実行する前に、入力を検証します。

test -f "$SKILL_DIR/scripts/dockerfile-validate.sh"
test -f "$TARGET_DOCKERFILE"

どちらかのチェックに失敗した場合は停止し、存在しないパスを正確に報告します。

2. 対象の Dockerfile を明示的に読み取る

明示的なファイル読み取りコマンドを使用します（抽象的な「Read tool」という表現は使用しません）。

sed -n '1,220p' "$TARGET_DOCKERFILE"

ファイルが長い場合は、必要に応じて次を使用します。

sed -n '220,440p' "$TARGET_DOCKERFILE"

3. 検証スクリプトを実行する

基本コマンド：

bash "$SKILL_DIR/scripts/dockerfile-validate.sh" "$TARGET_DOCKERFILE"

構造化された報告を行うために、任意で実行結果を取得します。

bash "$SKILL_DIR/scripts/dockerfile-validate.sh" "$TARGET_DOCKERFILE" | tee /tmp/dockerfile-validator.out

4. 検出事項を重要度で分類する（標準）

次の標準的な重要度モデルを使用します。

• Critical
  • ハードコードされたシークレット／認証情報
  • リスクの高いコンテキストでの明示的な root 実行
  • 影響の大きいセキュリティポリシー違反
• High
  • コンテナの強化に関する Checkov の失敗
  • 安全でない／信頼性の低いビルドにつながる可能性が高い hadolint エラー
  • ランタイムユーザー設定（USER）の欠落または不備
• Medium
  • :latest タグ、バージョン固定の欠落、キャッシュ削除の漏れ
  • ビルドキャッシュの非効率性と、レイヤー化されたインストールのアンチパターン
• Low
  • スタイル／情報に関するガイダンスと、ブロックを伴わない最適化の提案

5. 問題がない場合の高速処理（必須）

検証で対応が必要な検出事項がない場合：

• 合格したことを簡潔にまとめて返します。
• 参照ファイルを開かないでください。
• 修正差分を生成しないでください。

以下のすべてに該当する場合は、高速処理を使用します。

• スクリプトが全体として合格を報告している。
• セキュリティ上の失敗がない。
• ユーザーの対応を必要とするエラー／警告がない。

6. 参照資料の読み込み規則（検出事項がある場合のみ）

実際の検出事項に該当する参照資料だけを読み取ります。必要な各ファイルは一度だけ読み取ります。

問題と参照資料の対応：

問題のカテゴリ	該当例	読み取るファイル
シークレット、root ユーザー、公開された機密ポート、強化の不足	CKV_DOCKER_*、ハードコードされたトークン／パスワード、ランタイムの root ユーザー	references/security_checklist.md
イメージサイズ、レイヤー数、マルチステージ化の機会、キャッシュ効率、.dockerignore の不足	RUN が多すぎる、ビルド依存関係がある単一ステージ、キャッシュミス	references/optimization_guide.md
タグの固定、命令の使用方法、COPY と ADD の使い分け、WORKDIR／CMD／ENTRYPOINT の規則	:latest、バージョンが固定されていないパッケージ、命令レベルのベストプラクティス	references/docker_best_practices.md

明示的な読み取りコマンド：

sed -n '1,220p' "$SKILL_DIR/references/security_checklist.md"
sed -n '1,220p' "$SKILL_DIR/references/optimization_guide.md"
sed -n '1,220p' "$SKILL_DIR/references/docker_best_practices.md"

対象を絞って抽出する場合：

rg -n "USER|secrets|EXPOSE|HEALTHCHECK" "$SKILL_DIR/references/security_checklist.md"
rg -n "multi-stage|cache|layer|dockerignore" "$SKILL_DIR/references/optimization_guide.md"
rg -n "FROM|COPY|ADD|WORKDIR|CMD|ENTRYPOINT|latest" "$SKILL_DIR/references/docker_best_practices.md"

7. 標準レポートを出力する

高速処理以外のすべての実行で、次のテンプレートを使用します。

## Dockerfile Validation Report
- Target: <path>
- Command: `bash <skill-script> <target>`
- Overall result: PASS | FAIL | PARTIAL (fallback)

### Critical
- <issue or `None`>

### High
- <issue or `None`>

### Medium
- <issue or `None`>

### Low
- <issue or `None`>

### Recommended Fixes
- <specific code-level fix per actionable issue>

### References Used
- <list only files actually read>

### Fallbacks Used
- `None` or exact fallback branch + reason

8. 修正の適用を提案する

報告の後：

• 修正を適用するかどうか尋ねます。
• ユーザーが承認した場合は、Dockerfile にパッチを適用し、検証を再実行します。

代替動作（明示的）

基本スクリプトを完了できない場合は、決定論的な代替分岐を使用し、その旨を報告します。

フォールバック A：Python／ツールのインストール制約

条件：

• スクリプトがツールのインストール失敗で終了する場合（Python がない、パッケージのインストールがブロックされている、制限された環境など）。

対応：

1. 主な失敗とその理由を報告します。
2. 手動で最低限のチェックを実行します。

# Basic syntax signal (if Docker is available)
DOCKERFILE_DIR="$(dirname "$TARGET_DOCKERFILE")"
docker build --no-cache -f "$TARGET_DOCKERFILE" "$DOCKERFILE_DIR"

# High-value static checks
grep -nEi "^[[:space:]]*FROM[[:space:]]+.*:latest" "$TARGET_DOCKERFILE" || true
grep -nEi "^[[:space:]]*(ENV|ARG)[[:space:]].*(password|secret|token|api[_-]?key)[[:space:]]*=" "$TARGET_DOCKERFILE" || true
grep -nEi "^[[:space:]]*USER[[:space:]]+(root|0(:0)?)$" "$TARGET_DOCKERFILE" || true
grep -nEi "^[[:space:]]*HEALTHCHECK[[:space:]]+" "$TARGET_DOCKERFILE" || true

3. 結果を PARTIAL と分類し、省略したチェックを明確に示します。

フォールバック B：hadolint は利用できないが Docker は利用可能

hadolint のコンテナイメージを使用します。

docker run --rm -i hadolint/hadolint < "$TARGET_DOCKERFILE"

フォールバック C：Docker も hadolint/checkov も利用できない

手動の正規表現ベースのチェック（フォールバック A のステップ 2）のみを実行し、PARTIAL と明記したうえで、省略したスキャナーを記載します。

クイックコマンドセット

1 つの Dockerfile を検証する

cd /path/to/repo
bash devops-skills-plugin/skills/dockerfile-validator/scripts/dockerfile-validate.sh Dockerfile

別のファイルを検証する

cd /path/to/repo
bash devops-skills-plugin/skills/dockerfile-validator/scripts/dockerfile-validate.sh Dockerfile.prod

スキルのサンプルを検証する

cd /path/to/repo/devops-skills-plugin/skills/dockerfile-validator
bash scripts/dockerfile-validate.sh examples/good-example.Dockerfile
bash scripts/dockerfile-validate.sh examples/security-issues.Dockerfile

リグレッションチェックを実行する（CI エントリーポイント）

cd /path/to/repo
bash devops-skills-plugin/skills/dockerfile-validator/scripts/test_validate.sh

ShellCheck の適用が必須の CI 環境向けの、任意の厳格モード：

STRICT_SHELLCHECK=true bash devops-skills-plugin/skills/dockerfile-validator/scripts/test_validate.sh

段階的開示のルール

• 必ず最初に対象の Dockerfile を読みます。
• 指摘事項の確認に必要な場合を除き、参照ファイルは読みません。
• 問題と参照ファイルの対応表から、一致する参照ファイルのみを読みます。
• 新しい問題カテゴリが見つからない限り、同じ参照ファイルを再度読みません。

完了条件

以下の条件をすべて満たした場合にのみ、このスキルの実行が完了したものとします。

• Dockerfile の検証、Lint、セキュリティ、最適化に関するリクエストであることが確認されている。
• 対象の Dockerfile のパスが明示的に確認されている。
• 検証コマンド（または明示されたフォールバック）が実行されている。
• 指摘事項が重要度の区分（Critical、High、Medium、Low）で報告されている。
• 参照ファイルの使用が問題カテゴリに対応しており、その一覧が明示されている。
• 問題がない場合の簡易パスでは、不要な参照ファイルの読み込みが省略されている。
• 修正を適用した場合、検証を再実行し、最終ステータスが報告されている。

リソース

• スクリプト：scripts/dockerfile-validate.sh
• CI／リグレッションのエントリーポイント：scripts/test_validate.sh
• セキュリティのリファレンス：references/security_checklist.md
• 最適化のリファレンス：references/optimization_guide.md
• ベストプラクティスのリファレンス：references/docker_best_practices.md
• サンプル：examples/good-example.Dockerfile、examples/bad-example.Dockerfile、examples/security-issues.Dockerfile、examples/python-optimized.Dockerfile、examples/golang-distroless.Dockerfile

ソースリンク

• Docker ビルドのベストプラクティス
• Dockerfile リファレンス
• Checkov による Dockerfile スキャン
• hadolint