コンテンツにスキップ

Webhookの修正計画のベースイメージのフィールド

このページでは、汎用Webhookのremediationに含まれるベースイメージの修正計画、稼働イメージごとの結果、再ビルドの見込みのフィールドを説明します。 修正計画全体の構造は修正計画の全体像を参照してください。

表の読み方はレポートのフィールドを参照してください。 JSON例は、出力の一部を抜粋したものです。

ベースイメージのフィールド

remediationのベースイメージに関するフィールドは次のとおりです。

フィールド名 型 意味 値がないとき
dockerfile_summary object 分類別のベースイメージの項目数 項目がなければ省略
dockerfile_items objectの配列 Dockerfileのベースイメージに関する修正計画の項目 項目がなければ省略

dockerfile_summaryは、dockerfile_items[]をcategoryごとに数えます。 キーはpr_candidate・pull_again・manual・not_comparable・deferred・no_candidate・excluded・failedで、項目がある場合は0件のキーも出力します。

各分類の意味は計画の分類値を参照してください。

{
  "dockerfile_summary": {
    "deferred": 0,
    "excluded": 0,
    "failed": 0,
    "manual": 1,
    "no_candidate": 1,
    "not_comparable": 1,
    "pr_candidate": 1,
    "pull_again": 0
  }
}

項目の単位とフィールド

dockerfile_items[]には、ベースイメージを更新するときに書き換えるFROMの行1つにつき1項目を作ります。 リポジトリ・ブランチ・Dockerfileのパスでファイルを特定し、その中のステージで書き換えるFROMの行を特定します。

項目をまとめる場合と分ける場合は次のとおりです。

  • 同じFROMの行からビルドされる複数のビルド対象やワークロードは1項目にまとめる
  • 同じベースイメージ名でも、別のFROMの行なら別項目にする

Dockerfileの取得や解析に失敗してFROMを特定できない場合は、取得できたファイルやビルド対象などの単位で失敗を記録します。 受信側で項目を識別するときはkeyを使い、ベースイメージ名だけで統合しないでください。

次は、ベースイメージの更新候補となった項目の抜粋です。

{
  "key": "dockerfile:ex/app@main:docker/Dockerfile#stages[0]:runtime",
  "kind": "dockerfile",
  "fix_class": "base_image",
  "verification": "base_image_comparison",
  "final_image_verified": false,
  "category": "pr_candidate",
  "reason": "adopted",
  "priority": "act_now",
  "workloads": [
    "compose/shop/app"
  ],
  "base_ref": "python:3.12.3-slim",
  "base_kind": "pinned"
}

dockerfile_items[]の1要素のフィールドは次のとおりです。

フィールド名 型 意味 値がないとき
key string 修正計画内で項目を識別するキー —
kind string 修正対象の種類 —
fix_class string 修正の種類 —
verification string 検証の対象 —
final_image_verified boolean 再ビルド後の完成イメージを検証したかを示す値 false
category string 項目全体の計画の分類値 —
reason string 分類の根拠となる理由コード 省略
detail string 分類や理由に関する補足の説明文 省略
priority string 対象ワークロードの稼働イメージの修正可能な所見で最も高い優先度 省略
workloads stringの配列 対象のワークロードキーの一覧 []
source object Dockerfileと書き換えるFROMの行を示すソース情報 —
base_ref string FROMに書かれた現在のベースイメージの参照名 省略
base_kind string 現在のベースイメージのタグの分類 省略
candidate object 更新候補のベースのイメージ情報 省略
counts object 稼働イメージごとの比較をまとめた件数 —
rebuild_runtimes objectの配列 項目全体のランタイムの再ビルドの見込み 省略
rebuild_check object 項目全体の現在のベースとの突き合わせ 省略
entities objectの配列 稼働イメージごとの結果 省略
pull_request object 項目に対応するPR処理の結果 省略
newer_series object 稼働イメージ全体をまとめた新しい系列の確認結果 省略
awaiting_deploy object 稼働イメージへの反映を待つマージ済みPRの情報 省略

dockerfile_items[].kindの値は次のとおりです。

値 意味
dockerfile Dockerfileの変更に関する項目

dockerfile_items[].fix_classの値は次のとおりです。

値 意味
base_image ベースイメージの更新

dockerfile_items[].verificationの値は次のとおりです。

値 意味
base_image_comparison 現在のベースイメージと候補のベースイメージの比較

dockerfile_items[].base_kindの値は次のとおりです。

値 意味
pinned 1.25.3など、1つのリリースを指す固定タグ
floating 1.25やlatestなどの追従タグ
excluded 候補探索の対象外となる参照

次のフィールドには補足があります。

  • priority
    • 修正状態がfixedで、修正版の情報がある所見だけを対象とする
  • final_image_verified
    • 完成イメージのビルドとスキャンは行わないため、常にfalse
    • 検証の範囲は対象別の検証範囲を参照
  • candidate
    • dockerfile_items[].entities[]の並び順で最初に見つかったcandidate_baseをコピーする
    • 候補の情報があっても、categoryがpr_candidateになるとは限らない
    • 項目全体のcategoryがpr_candidateなら、すべてのentities[].candidate_baseのtagとtop_digestはcandidateと一致する
    • platform・config_digest・manifest_digestはプラットフォームによって異なることがあるため、個別の値はdockerfile_items[].entities[].candidate_baseを参照
  • newer_series
    • 項目全体のdockerfile_items[].newer_series.candidates[]にはcomparisonとscansを付けない
    • 個別の比較とスキャン記録はdockerfile_items[].entities[].newer_seriesに含める

ソース情報

dockerfile_items[].sourceのフィールドは次のとおりです。

フィールド名 型 意味 値がないとき
repository string Dockerfileがあるリポジトリの所有者/リポジトリ名 —
base_branch string Dockerfileを読み取る基準ブランチ —
commit_sha string Dockerfile側の基準ブランチで確認したコミットSHA 省略
path string リポジトリのルートからのDockerfileの相対パス ""
targets stringの配列 対象ワークロードが指定するビルド対象のステージ名の一覧 省略
origin string Dockerfileの場所を特定する情報の取得元 省略
compose_path string 場所の特定に使ったComposeファイルのリポジトリ内の相対パス 省略
files objectの配列 読み取ったソースファイルの一覧 省略
stage integer 書き換えるFROMの行が属するステージの0始まりの番号 未特定なら省略
platform string 書き換えるFROMの行に指定された固定の--platformの値 省略
stage_name string 書き換えるFROMの行が属するステージのAS名 省略
line integer 書き換えるFROMの行が始まる行番号(1始まり) 未特定なら省略

dockerfile_items[].source.originの値は次のとおりです。

値 意味
mapping 設定の対応付けから特定
compose_build Composeのbuildから特定
mapping_and_compose_build 設定の対応付けとComposeのbuildを参照

次のフィールドには補足があります。

  • targets
    • 重複を除いて並べ替えた一覧で、要素の""はビルド対象を指定せず最後のステージを使うことを表す
    • ビルド対象のステージと、そのベースイメージを参照するstageは異なることがある
  • stage
    • 最初のステージを表す0も出力する

ソースファイル

dockerfile_items[].source.files[]の1要素のフィールドは次のとおりです。

フィールド名 型 意味 値がないとき
path string ファイルがあるリポジトリのルートからの相対パス —
blob_sha string 読み取ったファイルのGit blob SHA —
repository string 項目のソースと異なる取得元のリポジトリ名 省略
base_branch string 項目のソースと異なる取得元の基準ブランチ 省略

repositoryとbase_branchが省略されたファイルは、dockerfile_items[].sourceのリポジトリと基準ブランチに属します。

次は、Dockerfileの最初のステージのFROMの行を書き換える場合のソース情報の例です。

{
  "repository": "ex/app",
  "base_branch": "main",
  "commit_sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "path": "docker/Dockerfile",
  "targets": [
    "runtime"
  ],
  "origin": "mapping",
  "files": [
    {
      "path": "docker/Dockerfile",
      "blob_sha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
    }
  ],
  "stage": 0,
  "stage_name": "runtime",
  "line": 3
}

修正対象と比較結果の件数

dockerfile_items[].countsは、dockerfile_items[].entities[]の対象と比較結果をまとめた件数です。 同じCVE ID・パッケージ名・エコシステム・パッケージ分類の組は、複数の稼働イメージにあっても1件に数えます。

dockerfile_items[].countsのフィールドは次のとおりです。

フィールド名 型 意味 値がないとき
targets integer 稼働イメージ全体で重複を除いた修正対象の件数 0
resolved integer その対象を持つすべての稼働イメージで解消した対象の件数 0
remaining integer その対象を持つ稼働イメージのいずれかで残った対象の件数 0
introduced integer 候補のベースイメージで新たに検出した所見の重複を除いた件数 0

次のフィールドには補足があります。

  • targets
    • パッケージの版や出現場所が複数あっても、同じCVE ID・パッケージ名・エコシステム・分類の組は1件
    • entities[].targetsの単純な合計ではない
  • resolved・remaining
    • その対象を持たない稼働イメージは、その対象の集計に影響しない
    • 未比較や判定不能の対象は解消と残存のどちらにも数えない場合があるため、合計がtargetsより少なくなることがある
  • introduced
    • 修正対象と同じCVE ID・パッケージ名・エコシステム・分類の組で重複を除く
    • 修正対象に含まれないパッケージの新規所見も数える

次は、対象の比較結果がない項目の件数の例です。

{
  "targets": 0,
  "resolved": 0,
  "remaining": 0,
  "introduced": 0
}

反映待ちのマージ済みPR

dockerfile_items[].awaiting_deployは、マージ済みで稼働イメージにまだ反映されていないベースイメージ更新のPRを表します。

出力する主な条件は次のとおりです。

  • KestreLynxが作ったベースイメージ更新のPRがマージ済みである
  • 項目の稼働イメージがすべて、そのPRを作ったときの稼働イメージのいずれかと同じである

マージ後のDockerfileでビルドしたイメージをデプロイすると、更新が反映されます。 この場合のdockerfile_items[].reasonはbase_update_not_deployedです。

dockerfile_items[].awaiting_deployのフィールドは次のとおりです。

フィールド名 型 意味 値がないとき
number integer マージ済みPRの番号 —
url string マージ済みPRのURL 省略
from string PR前にFROMが指していた、稼働イメージの作成元のベースイメージ名 —
to string PRがFROMに設定したタグ —

反映待ちの結果の読み方は再ビルドの案内を参照してください。

PR処理の結果

dockerfile_items[].pull_requestは、項目のベースイメージ更新に関するPR処理の結果を表します。

項目の更新に該当するPR処理がある場合に出力します。 PRを作成していない手動対応や保留などの処理結果も含みます。

dockerfile_items[].pull_requestのフィールドは次のとおりです。

フィールド名 型 意味 値がないとき
status string PR処理の状態値 —
reason string PR処理の結果に関する理由コード 省略
number integer 対応するPRの番号 省略
url string 対応するPRのURL 省略
state string 対応するPR記録の状態値 省略

次は、PRを作成した結果の例です。

{
  "status": "pr_created",
  "number": 7,
  "url": "https://github.com/ex/app/pull/7",
  "state": "open"
}

稼働イメージごとの結果

dockerfile_items[].entities[]の1要素は、項目の対象のワークロードで動いているイメージ1つ分の結果です。 同じFROMの行からビルドしたイメージでも、ワークロードによって動いているイメージが異なることがあるため、結果を分けます。

同じイメージかどうかは、running_image.refとrunning_image.contentの組で見分けます。 要素の分かれ方とまとまり方は次のとおりです。

  • 同じイメージを複数のワークロードが使う場合は1要素にまとめ、各ワークロードの情報をその要素のservices[]に並べる
  • running_image.contentがレジストリのdigestを使う場合は、イメージ名とdigestが同じでも、プラットフォームが違えば別の要素になる
    • running_image.contentは内容の識別値で、この場合はプラットフォームも含む
  • 内容を識別できない場合はrunning_image.contentがunconfirmedとなり、同じrunning_image.refの未確認のイメージを1要素にまとめる
    • この場合、同じrefでも内容が同じとは確認できない

dockerfile_items[].entities[]の1要素のフィールドは次のとおりです。

フィールド名 型 意味 値がないとき
services objectの配列 稼働イメージを使うサービスの情報 省略
running_image object 所見を検出した稼働中のイメージ情報 —
current_base object FROMのタグが現在指すベースのイメージ情報 省略
candidate_base object 更新候補のベースのイメージ情報 省略
layer_confirmation object 稼働イメージと現在のベースのレイヤーの照合結果 —
findings_by_layer object 稼働イメージのレイヤー別の所見件数 —
category string 稼働イメージごとの計画の分類値 —
reason string 分類の根拠となる理由コード 省略
detail string 分類や理由に関する補足の説明文 省略
targets integer ベースに属する修正対象の件数 0
kev_targets integer 修正対象のうちCISA KEVに掲載された対象の件数 0件なら省略
comparison object 現在のベースと候補のベースを修正対象について比べた比較結果 省略
rebuild_runtimes objectの配列 稼働イメージごとのランタイムの再ビルドの見込み 省略
rebuild_check object 稼働イメージごとの現在のベースとの突き合わせ 省略
scans objectの配列 現在のベースと候補のベースのスキャンの記録 省略
newer_series object 稼働イメージごとの新しい系列の確認結果 省略

次のフィールドには補足があります。

  • targets・kev_targets
    • CVE ID・パッケージ名・エコシステム・分類の組で重複を除いて数える
    • 修正対象の選定に到達していない場合もtargetsは0
  • comparison
    • verdicts[]は稼働イメージの修正対象に絞った判定
    • 再ビルド後の完成イメージを比較した結果ではない
  • scans
    • 現在のベースはrole: baseline、候補のベースはrole: candidate
    • 記録があるものだけを出力する

次は、稼働イメージごとの結果の抜粋です。

{
  "running_image": {
    "ref": "shop-app:1",
    "content": "config:sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "config_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "platform": "linux/amd64",
    "digest_kind_unverified": true
  },
  "layer_confirmation": {
    "status": "confirmed",
    "base_layers": 2,
    "image_layers": 3
  },
  "findings_by_layer": {
    "base": 3,
    "upper": 1,
    "unknown": 1
  },
  "category": "pr_candidate",
  "reason": "adopted",
  "targets": 3,
  "kev_targets": 1
}

レイヤーの照合結果

dockerfile_items[].entities[].layer_confirmationのフィールドは次のとおりです。

フィールド名 型 意味 値がないとき
status string レイヤーの照合状態 —
base_layers integer 稼働イメージの先頭と一致したベースのレイヤー数 一致を確認できなければ省略
image_layers integer 稼働イメージから取得したレイヤー数 0件なら省略
detail string 照合状態に関する補足の説明文 省略

dockerfile_items[].entities[].layer_confirmation.statusの値は次のとおりです。

値 意味
confirmed 現在のベースのレイヤー列が稼働イメージの先頭と一致
mismatch レイヤー情報を照合した結果、先頭と不一致
unusable レイヤー情報が不足または利用不能で照合できない
not_checked レイヤーの照合に到達していない

照合の範囲と判定条件はベースレイヤーの照合を参照してください。

レイヤー別の所見件数

dockerfile_items[].entities[].findings_by_layerのフィールドは次のとおりです。

フィールド名 型 意味 値がないとき
base integer 現在のベースに属すると分類した所見の件数 0
upper integer ベースより後のレイヤーに属すると分類した所見の件数 0
unknown integer ベースと後のレイヤーのどちらにも分類できなかった所見の件数 0

所見の出現ごとに数えるため、CVE IDの重複を除いた件数ではありません。 修正対象に選ばれなかった所見も含みます。

分類に到達していない場合は3つとも0になるため、すべて0でも所見がないとは限りません。 結果を読むときはdockerfile_items[].entities[].category・reason・layer_confirmation.statusも確認してください。

ランタイムの再ビルドの見込み

rebuild_runtimes[]は、現在のベースのランタイムの版を引き継いだ場合に、稼働イメージで検出中のCVEがどう変わるかを表します。 稼働イメージごとの結果と、項目全体の集計の2か所にあります。

付く条件は次のとおりです。

  • dockerfile_items[].entities[].rebuild_runtimes
    • 対応するdockerfile_items[].entities[].reasonがfloating_base_unconfirmedで、稼働イメージのランタイムの所見を現在のベースの版で確認できた場合に付く
    • 確認できたランタイムがなければ省略する
  • dockerfile_items[].rebuild_runtimes
    • dockerfile_items[].entities[]が1要素以上あり、すべてのdockerfile_items[].entities[].reasonがfloating_base_unconfirmedの場合に個別の結果をまとめる
    • 集計結果が空なら省略する
    • 別の理由の稼働イメージが混在する場合は項目全体を省略し、条件に該当する稼働イメージの個別の記録は残す

dockerfile_items[].rebuild_runtimes[]の1要素のフィールドは次のとおりで、dockerfile_items[].entities[].rebuild_runtimes[]の各要素も同じフィールドを持ちます。

フィールド名 型 意味 値がないとき
package string ランタイム名 —
installed string 稼働イメージのランタイムの版 —
base_version string 現在のベースのランタイムの版 —
disappearing stringの配列 現在のベースの版を引き継げば出なくなる見込みのCVE ID 省略
remaining stringの配列 現在のベースの版でも残るCVE ID 省略

dockerfile_items[].rebuild_runtimes[].packageの値は次のとおりです。

値 意味
Node.js Node.js本体
Python runtime Python本体

次のフィールドには補足があります。

  • disappearing・remaining
    • 稼働イメージで検出中のCVEだけを対象とし、現在のベースの版で新たに増えるCVEは含めない
    • CVE IDの重複を除いて並べ替える
    • 項目全体ではpackage・installed・base_versionが同じ記録をまとめる
    • まとめた記録のいずれかでremainingにあるIDは、項目全体のdisappearingに含めない

この結果はランタイムの版から求めた見込みで、完成イメージの検証ではありません。 条件と制約はベースレイヤーの照合と再ビルドの案内を参照してください。

現在のベースとの突き合わせ

rebuild_checkは、稼働イメージと現在のベースをパッケージの場所・CVEで突き合わせた結果です。 完成イメージはビルドせず、dockerfile_items[].final_image_verifiedはfalseのままです。

突き合わせに使う所見は次のとおりです。

イメージ 突き合わせに使う所見
稼働イメージ 比較する深刻度の範囲内で、修正状態がfixedかつ修正版の情報がある所見
現在のベース 修正版のない所見も含め、比較する深刻度の範囲内のすべての所見(CVEが残っているかを確かめるため)

場所の照合と未判定になる条件はベースレイヤーの照合を参照してください。

付く条件は次のとおりです。

  • dockerfile_items[].entities[].rebuild_check
    • 対応するdockerfile_items[].entities[].reasonがfloating_base_unconfirmedで、突き合わせの処理結果がある場合に付く
    • 比較できなかった場合もstatus: not_checkedとして記録する
  • dockerfile_items[].rebuild_check
    • dockerfile_items[].entities[]が1要素以上あり、すべてのdockerfile_items[].entities[].reasonがfloating_base_unconfirmedの場合に個別の結果をまとめる
    • 別の理由の稼働イメージが混在する場合は項目全体を省略し、個別の記録は残す

statusがcheckedで消える見込みの所見がなく、Slackとメールに何も表示しない場合も、Webhookには結果を出力します。

dockerfile_items[].rebuild_checkのフィールドは次のとおりで、dockerfile_items[].entities[].rebuild_checkも同じフィールドを持ちます。

フィールド名 型 意味 値がないとき
status string 突き合わせの確認状態 —
reason string 比較できなかった理由を表す理由コード 省略
detail string 比較できなかった理由に関する補足の説明文 省略
gone objectの配列 ベースの同じ場所に別の版があり、対象のCVEがないパッケージの記録 省略
remaining objectの配列 ベースの同じ場所にも対象のCVEがあるパッケージの記録 省略
not_in_base objectの配列 ベースの同じ場所にないOSパッケージまたはグローバルなnode_modulesのパッケージの記録 省略
other_not_in_base integer アプリの依存など、not_in_baseの対象以外でベースの同じ場所にないパッケージの件数 0件なら省略
only_in_base objectの配列 現在のベースにだけ対応する修正可能な所見があるパッケージの記録 省略
undetermined integer 判定できなかった所見の件数 0件なら省略
running_scan object 稼働イメージのスキャンの記録 省略
base_scan object 現在のベースのスキャンの記録 省略

dockerfile_items[].rebuild_check.statusの値は次のとおりです。

値 意味
checked 対象の所見をすべて判定した
partial 突き合わせを行ったが、未判定の所見がある
not_checked 比較していない

次のフィールドには補足があります。

  • not_in_base
    • ベースから消えたパッケージとDockerfileの手順で足したパッケージを区別できない
  • other_not_in_base
    • 稼働イメージごとの件数は、パッケージの分類・名前・版・パスの組で重複を除いて数える
  • only_in_base
    • ベース側にある修正状態がfixedかつ修正版の情報がある所見のうち、稼働イメージの同じ場所に対応する所見がないものを含む
    • Dockerfileの手順で消す所見も含む
  • undetermined
    • 言語ランタイム本体の所見はrebuild_runtimesで扱い、その記録で確認できない対象はundeterminedに数える
  • running_scan・base_scan
    • 稼働イメージごとの結果に記録し、項目全体の集計には付けない
    • どちらの記録もroleはbaselineなので、フィールド名で対象を区別する

パッケージの記録

gone[]・remaining[]・not_in_base[]・only_in_base[]の1要素は、1つの場所にあるパッケージの版と、その結果に該当するCVEをまとめた記録です。 CVEごとに結果が異なる場合は、同じパッケージが複数の配列に入ります。

dockerfile_items[].rebuild_check.gone[]の1要素のフィールドは次のとおりで、remaining[]・not_in_base[]・only_in_base[]と、稼働イメージごとのrebuild_check内の各配列の要素も同じフィールドを持ちます。

フィールド名 型 意味 値がないとき
name string パッケージ名 —
version string 記録の対象となるパッケージの版 ""
class string パッケージの分類 —
path string スキャン結果にあるパッケージの場所を示す文字列 省略
owner string グローバルなnode_modulesで、このパッケージを配下に持つパッケージ名 省略
base_version string goneの記録に対応する現在のベースの同じ場所にある版 省略
vuln_ids stringの配列 この記録の結果に該当するCVE IDの一覧 —

dockerfile_items[].rebuild_check.gone[].classの値は次のとおりです。

値 意味
os OSパッケージ
lang 言語パッケージ

次のフィールドには補足があります。

  • version
    • gone[]・remaining[]・not_in_base[]では稼働イメージの版
    • only_in_base[]では現在のベースの版
  • path
    • パッケージ自身のパスがあればその値を使い、得られなければ検出元のスキャン対象を示す文字列を使う
    • OSパッケージでは省略する
    • 出力する文字列は検出時の値で、場所の照合用に版を除いたパスではない
  • owner
    • 例えばusr/local/lib/node_modules/npm/node_modules/undici/package.jsonにある依存ではnpm
  • base_version
    • gone[]にだけ設定する
  • vuln_ids
    • 重複を除いて並べ替えた1件以上のIDを含む

項目全体へのまとめ方

稼働イメージごとのrebuild_checkをdockerfile_items[].rebuild_checkへまとめる決まりを説明します。

項目全体のstatusは、次の条件で決まります。

項目全体のstatus 条件
not_checked 比較していない稼働イメージ(not_checkedまたは結果のないもの)が1つでもある
partial 比較していない稼働イメージがなく、partialが1つでもある
checked すべての稼働イメージがchecked

フィールドごとのまとめ方は次のとおりです。

フィールド まとめ方
gone その所見を持つすべての稼働イメージで消えるものだけを含める
gone・remaining・not_in_base・only_in_base パッケージの分類・名前・版・パス・base_versionが同じ記録を1つにまとめ、CVE IDの重複を除く
undetermined 稼働イメージごとの件数の合計
other_not_in_base 稼働イメージごとの件数の最大値

項目全体へのまとめ方には、次の補足があります。

  • 項目全体がnot_checkedの場合は、確認できた稼働イメージのパッケージ一覧も項目全体には載せず、個別の結果に残す
  • プラットフォームによって現在のベースの版が違う場合は、base_versionごとに別の記録にする

Dockerfileの手順の効果など、見込みの制約は再ビルドの案内を参照してください。