RATATOSKRATATOSK
로그인

데이터 이해하기

이 페이지는 라타토스크의 데이터 모델을 설명합니다 — change, 그것을 분류하는 세 개의 축, 심각도, 그리고 무엇이 "조치 필요"인지. API·MCP·피드 문서에서 쓰는 용어는 전부 여기서 정의합니다.

모델은 하나, 표면은 여럿. 웹 화면·REST API·MCP 도구·알림·피드가 전부 같은 기록을 같은 규칙으로 씁니다. 두 표면에 "여기서 내가 할 일이 몇 건인가"를 물으면 같은 수가 나옵니다.

change

change는 릴리스가 한 일 하나이고, 공식 릴리스 노트에서 축자적으로 뽑습니다. 기록된 줄은 전부 change가 됩니다 — 버리는 것은 없습니다 — 그리고 각각 세 개의 축을 답니다.

family — 어떤 종류인가

값 뜻
security 보안 수정, 또는 보안을 이유로 한 의존성 갱신
breaking 기존 설정을 깨뜨릴 수 있는 것: 제거, 기본값 변경, 검증 강화, 개명, API 버전 변경
deprecated 앞으로 제거하겠다는 예고와 그 시점

사람이 구독할 때 고르는 축입니다. "보안과 호환성은 알려 주고, 폐기 예고는 빼 줘."

bucket — 지금 어떻게 행동할 것인가

값 뜻
action 그 버전을 쓰는 모든 설치에 해당. 하세요
check applies_if가 내 설정과 맞을 때만 해당. 조건부터 확인하세요
plan 앞으로 예고된 것. 오늘 할 일은 없음
other 전수 기록: 일상적인 줄과 봇 의존성 범프

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 — 그 밑에 깔린 사안의 정체성. 릴리스와 갈래를 가로질러 유지됩니다. 같은 보안 롤업이 다섯 갈래에 착지해도 키는 하나입니다. /v1/matters/{key}가 등장한 모든 릴리스를 돌려줍니다.

  • subjects — 이 change가 건드린 식별자들. 내 매니페스트·설정과 이름으로 대조하기 위한 것입니다. kind 값은 다음과 같습니다.

    kind 뜻
    api API 그룹/버전 (예: v1beta1 → v1 승격의 대상)
    crd 커스텀 리소스 정의(CRD) 이름
    feature_gate 피처 게이트 이름
    flag 커맨드라인 플래그 (예: --listen-client-http-urls)
    metric 메트릭 이름 또는 접두사
    config_field 설정 파일이나 차트 values의 필드 이름
    extension 플러그인·확장점 이름
    dependency 의존 라이브러리·구성요소 이름
    cve CVE 식별자
    advisory 보안 권고 ID (GHSA-… 및 프로젝트/GitHub 공식 공지)
    subsystem 식별자 하나로 특정되지 않을 때의 서브시스템 이름

  • advisories — 이 change가 인용한 CVE·권고 식별자. 각각 대장의 현재 심각도를 답니다(아래 참조).

  • 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: []는 "등급 없음"이 아니라 릴리스 노트가 권고 식별자를 대지 않았다는 뜻입니다.

릴리스 요약은 그 릴리스 권고들의 최고 심각도를 max_severity로 내보냅니다.

같은 CVE가 프로젝트마다 다른 심각도를 다는 것은 정상입니다 — 출처마다 자기 맥락 기준으로 매기기 때문입니다.

릴리스 상세 페이지

릴리스 상세 페이지는 공식 릴리스 노트의 모든 항목을 기록하고, 그중 당신에게 무언가를 요구하는 것을 위의 세 층으로 묶습니다. 나머지는 마지막 층에 접힙니다.

  • 조치 필요 — bucket: action.
  • 영향 확인 — bucket: check. 항목마다 "다음의 경우 해당" 조건을 답니다.
  • 미리 준비 — bucket: plan. 각각 시점과 함께 (예: v1.9.0부터 · v2.0에서 제거 예정).
  • 그 밖의 변경 — 나머지 기록을 접어 둔 것: 원문 인용을 종류별로 묶습니다. 보안이 동기인 항목은 언제나 별도 그룹으로 드러내고 묻지 않습니다.

릴리스 노트가 같은 것을 두 번 말하면 화면은 한 번으로 셉니다 — 기록은 둘 다 남기고, 접는 것은 화면입니다.

"조치 필요"의 뜻

웹 홈·이메일 알림·개인 RSS 필터가 전부 같은 기준을 씁니다. action 층을 family로 가른 것입니다.

  • security — 보안 수정. 심각도와 무관하게 전부.
  • breaking — 호환성을 깨뜨리는 변경.
  • deprecated — 예고된 제거.

웹 홈의 "조치 필요" 창은 최근 7일(롤링)입니다. 이메일 알림과 개인 RSS의 type=security·type=breaking·type=deprecated 필터도 같은 세 가족으로 거릅니다 — 알림과 피드 참조.

감사 가능한 침묵

change가 0건인 릴리스는 빈칸이 아니라 답입니다. 노트를 읽었고 그 안에 당신이 할 일이 없다는 뜻입니다. 릴리스 요약은 기록한 줄 수를 notes_total로 계속 보고하므로, "읽었고 일상적이었다"와 "안 읽었다"를 구별할 수 있습니다.

시각과 시간대

라타토스크는 모든 시각을 UTC로 저장·표시·집계합니다. 릴리스 날짜는 GitHub이 보고하는 발행 시각(published_at)입니다.

어떤 프로젝트를 다루나

라타토스크는 CNCF 랜드스케이프의 프로젝트를 추적합니다. 현재 목록과 프로젝트별 분석 이력은 /projects에 있습니다.

다음 단계

  • 이 데이터를 프로그램으로 조회하려면: REST API
  • 에이전트가 도구로 쓰게 하려면: MCP 서버