データを理解する
このページでは Ratatosk のデータモデルを説明します — change、それを分類する 3 つの 軸、深刻度、そして何が「要対応」なのか。API・MCP・フィードのドキュメントで使う用語は すべてここで定義します。
モデルは 1 つ、表面は複数。 ウェブ画面・REST API・MCP ツール・アラート・フィードは すべて同じ記録を同じ規則で使います。2 つの表面に「ここで自分がやるべきことは何件か」を 尋ねれば、同じ数が返ります。
change
change はリリースが行ったこと 1 つで、公式リリースノートから逐語的に取り出します。 記録された行はすべて change になります — 捨てるものはありません — そしてそれぞれが 3 つの軸を持ちます。
family — どの種類か
| 値 | 意味 |
|---|---|
security |
セキュリティ修正、またはセキュリティを理由とする依存関係の更新 |
breaking |
既存の構成を壊しうるもの: 削除、既定値の変更、検証の厳格化、改名、API バージョン変更 |
deprecated |
将来の削除の予告と、その時期 |
人が購読するときに選ぶ軸です。「セキュリティと互換性は知らせて、廃止予告は要らない。」
bucket — いまどう動くか
| 値 | 意味 |
|---|---|
action |
そのバージョンの全インストールに該当。実施してください |
check |
applies_if が自分の構成と一致する場合だけ該当。まず条件を確かめてください |
plan |
将来に向けた予告。今日やることはありません |
other |
全件記録: 定型行と bot の依存関係更新 |
bucket はモデルが選ぶのではなく、保存されたフィールドからコードが計算し、
ウェブ画面・API・週次メールの裏で同じ規則が動きます。other はすべての表面で既定では
除外されます — 記録の大半を占めるからです。
applies_if — 自分に該当するか
文章ではなく真偽式です:
"applies_if": {
"evaluable": true,
"mode": "any_of",
"clauses": [
{ "kind": "api", "name": "ScheduleJobAlpha1", "verb": "uses", "polarity": "present" }
],
"raw": null
}
mode は all_of・any_of・universal（全員該当）です。evaluable が true なら、
文章を解釈する代わりに節を自分のマニフェストと突き合わせれば済みます。false の場合は
raw に元の文が入ります — 持っていない構造を作り出す代わりに、無いと明示します。
change_kind
どの種類の変更だったか:
| 値 | 意味 |
|---|---|
added |
無かったものが増えた |
removed |
あった機能・オプション・フラグが消えた |
deprecated |
まだ動くが削除を予告した |
renamed |
識別子の名前が変わった |
value_changed |
バージョン・既定値・上限が動いた |
behavior_changed |
同じ構成なのに結果が変わった |
constraint_changed |
検証や上限が厳しく（あるいは緩く）なった |
defect_corrected |
欠陥を修正した |
主なフィールド
matter_key— 根にある事案の同一性。リリースやブランチをまたいでも変わりません。 同じセキュリティロールアップが 5 つのブランチに着地してもキーは 1 つです。/v1/matters/{key}が登場したすべてのリリースを返します。subjects— この change が触れた識別子。自分のマニフェストや設定と名前で 突き合わせるためのものです。kindの値は次のとおりです。kind 意味 apiAPI グループ/バージョン（例: v1beta1 → v1 昇格の対象） crdカスタムリソース定義（CRD）名 feature_gateフィーチャーゲート名 flagコマンドラインフラグ（例: --listen-client-http-urls）metricメトリクス名または接頭辞 config_field設定ファイルや chart values のフィールド名 extensionプラグイン・拡張点の名前 dependency依存ライブラリ・コンポーネント名 cveCVE 識別子 advisoryセキュリティアドバイザリ ID（GHSA-… やプロジェクト/GitHub の公式告知） subsystem単一の識別子で特定できない場合のサブシステム名 advisories— この change が引用した CVE・アドバイザリ ID。それぞれ台帳の 現在の深刻度を持ちます（下記参照）。quote— 出典の文。一字一句そのまま写し、翻訳しません。だからすべての change は 原文にたどれます。window— ノートが示した時期:introduced_in・deprecated_in・removed_in。version_rank— 表記に依存しない並び替え用の配列（v0.42.0→[0, 42, 0]）。 プロジェクトのタグを数値として並べられない場合はnullです（モノレポのタグflagd/v0.16.1、チャネルのタグlts-4081.3.8など）。推測せず、区間比較から 除外します。
実際の例
API が返す実際の change です（ここで扱わないフィールドは省略）:
{
"change_id": "buildpacks:v0.40.9:83576398",
"matter_key": "buildpacks/advisory:cve-2026-41178",
"project": "buildpacks",
"version": "v0.40.9",
"version_rank": [0, 40, 9],
"family": "security",
"actionability": "act",
"bucket": "action",
"kind": "value_changed",
"applies_if": { "evaluable": false, "mode": "universal", "clauses": [], "raw": null },
"advisories": [
{ "id": "CVE-2026-41178", "severity": "medium" },
{ "id": "GO-2026-5158", "severity": "medium" }
],
"subjects": [
{ "kind": "dependency", "name": "go.opentelemetry.io/otel", "name_full": "go.opentelemetry.io/otel", "role": "changed" },
{ "kind": "cve", "name": "cve-2026-41178", "name_full": "CVE-2026-41178", "role": "changed" }
],
"window": { "introduced_in": "v0.40.9" },
"quote": "`go.opentelemetry.io/otel` | v1.43.0 → v1.44.0 | GO-2026-5158 / CVE-2026-41178 — baggage header not length-capped | Medium",
"source_url": "https://github.com/buildpacks/pack/releases/tag/v0.40.9",
"seq": 1487
}
REST API と MCP ツールはこの JSON をそのまま返します。
深刻度
深刻度は change ではなくアドバイザリに付きます。advisories の各項目は公式の
出典（cve.org・GitHub アドバイザリ DB・OSV）から読んだ値を持ち、後から深刻度が
付与・改訂されれば読み直します。画面と API は再分析なしにそれに追随します。
advisories: [] は「評価なし」ではなく、リリースノートがアドバイザリ ID を
挙げなかったという意味です。
リリース要約は、そのリリースのアドバイザリの最大の深刻度を max_severity として
出します。
同じ CVE がプロジェクトごとに異なる深刻度を持つのは正常です — 出典ごとに自分の 文脈で評価するからです。
リリース詳細ページ
リリース詳細ページは公式リリースノートのすべての項目を記録し、そのうちあなたに 何かを求めるものを上の 3 つの層にまとめます。残りは最後の層に畳まれます。
- 要対応 —
bucket: action。 - 影響確認 —
bucket: check。項目ごとに「次の場合に該当」の条件を示します。 - 事前準備 —
bucket: plan。それぞれ時期とともに （例:v1.9.0 から · v2.0 で削除予定）。 - その他の変更 — 残りの記録を畳んだもの: 原文の引用を種類別にまとめます。 セキュリティが動機の項目は必ず独立したグループとして示し、埋もれさせません。
リリースノートが同じことを 2 回述べていれば、画面は 1 件として数えます — 記録は 両方残し、畳むのは画面です。
「要対応」の意味
ウェブのホーム・メールアラート・個人 RSS フィルタはすべて同じ基準を使います。
action の層を family で分けたものです。
- security — セキュリティ修正。深刻度に関わらずすべて。
- breaking — 互換性を壊す変更。
- deprecated — 予告された削除。
ウェブホームの「要対応」ウィンドウは直近 7 日間（ローリング）です。メールアラートと
個人 RSS の type=security・type=breaking・type=deprecated フィルタも同じ 3 つの
family で絞ります — アラートとフィード を参照。
監査可能な沈黙
change が 0 件のリリースは欠落ではなく答えです。ノートは読まれ、その中にあなたの
対応を要するものが無かった、という意味です。リリース要約は記録した行数を
notes_total として報告し続けるので、「読んで定型だった」と「読んでいない」を
区別できます。
時刻とタイムゾーン
Ratatosk はすべての時刻を UTC で保存・表示・集計します。リリース日は GitHub が
報告する公開時刻（published_at）です。
対象プロジェクト
Ratatosk は CNCF ランドスケープのプロジェクトを追跡します。現在の一覧と プロジェクトごとの分析履歴は /projects にあります。