VEX 저장소 사양 v0.1

VEX 저장소 사양 v0.1

이 문서의 키워드 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", "OPTIONAL"은 RFC 2119에 설명된 대로 해석되어야 한다.

1. 버전 관리

VEX(Vulnerability Exploitability eXchange) 저장소 사양은 vX.Y 버전 관리를 사용해야 한다(MUST).
v1.0 이상의 경우:
- X(주 버전)는 호환성을 깨는 변경 사항이 있을 때 업데이트되어야 한다(MUST).
- Y(부 버전)는 하위 호환 변경 사항이 있을 때 업데이트되어야 한다(MUST).
v0.Y 버전의 경우, 부 버전 업데이트를 통해 호환성을 깨는 변경 사항이 발생할 수 있다(MAY).

버전 비교 시:

버전은 사전식이 아닌 숫자로 비교해야 한다(MUST).
주 버전을 먼저 비교해야 한다(MUST):
- 주 버전이 다르면 주 버전이 더 높은 버전이 더 새로운 것으로 간주한다.
- 주 버전이 같으면 부 버전 비교를 진행한다.
부 버전은 주 버전이 같을 때만 비교해야 한다(MUST):
- 부 버전이 더 높은 버전이 더 새로운 것으로 간주한다.

비교 예시:

1.0 < 2.0
1.1 < 1.2
1.10 > 1.2

2. 저장소 매니페스트

2.1 개요

매니페스트 파일은 VEX 데이터 저장소에 대한 메타데이터를 제공한다. 이 파일에는 VEX 데이터를 검색하고 업데이트하는 데 필요한 정보가 포함되어야 한다(MUST).

2.2 파일 위치

HTTPS의 경우: 매니페스트 파일은 https://<domain>/.well-known/vex-repository.json에 위치해야 한다(MUST).
GitHub 저장소의 경우: vex-repository.json은 메인 브랜치의 루트 디렉터리에 배치되어야 한다(MUST).

2.3 스키마

매니페스트 파일의 JSON 스키마는 여기에 정의되어 있다.

2.4 예시

{
  "name": "Example Org VEX Repository",
  "description": "VEX repository for Example Organization",
  "versions": [
    {
      "spec_version": "0.1",
      "locations": [
        {
          "url": "https://example.com/vex-hub/v0/vex-data-v0.tar.gz"
        }
      ],
      "update_interval": "24h",
      "repository_specific": {
        "location": {
          "repository_type": "db",
          "db_type": "bbolt",
          "url": "oci://ghcr.io/example.com/vex-db:0"
        }
      }
    },
    {
      "spec_version": "1.0",
      "locations": [
        {
          "url": "https://example.com/vex-hub/v1/vex-data-v1.tar.gz//subdirectory"
        },
        {
          "url": "https://example.com/vex-api/v1"
        }
      ],
      "update_interval": "1h"
    }
  ]
}

2.5 필드 설명 및 참고 사항

주요 필드

필드	필수	설명 및 참고 사항
name	✓	저장소의 이름.
description	✓	저장소에 대한 간략한 설명.
versions	✓	사용 가능한 버전의 세부 정보를 포함하는 배열. 배열의 각 객체는 VEX 저장소 사양 버전을 구현하는 버전을 나타낸다. 버전은 오래된 순서에서 최신 순서로 오름차순 정렬되어야 한다(MUST). 하위 필드는 별도 표를 참조하라.

버전 하위 필드

필드	필수	설명 및 참고 사항
spec_version	✓	구현된 VEX 저장소 사양의 버전(예: "0.1"). 형식은 섹션 1에 정의된 대로 "X.Y"여야 한다(MUST).
locations	✓	VEX 데이터 위치를 설명하는 객체 배열. 하나 이상의 위치 객체를 포함해야 한다(MUST). 하위 필드는 별도 표를 참조하라.
update_interval	✓	이 버전의 VEX 데이터에 대한 권장 업데이트 확인 간격. Go duration 형식을 사용한다(예: "1h", "30m", "24h").
repository_specific	-	추가적인 저장소별 정보.

위치 하위 필드

필드	필수	설명 및 참고 사항
url	✓	VEX 데이터 위치의 URL로, "https://"로 시작한다. 콘텐츠는 섹션 3 및 4의 저장소 구조 사양을 따른다. URL에는 '//' 다음에 하위 디렉터리 경로를 추가하여 하위 디렉터리 지정을 포함할 수 있다.

3. 저장소 구조

3.1 파일 구조

저장소는 다음 구조를 가져야 한다(MUST):

vex-repository.<archive_extension>
[optional_subdirectory/]
├── index.json
└── pkg/
    ├── <type>/
    │   ├── <namespace>/
    │   │   ├── <name>/
    │   │   │   └── vex.json
    │   │   └── ...
    │   └── ...
    └── ...

여기서 <archive_extension>은(는) 지원되는 아카이브 형식 중 하나이다.

[optional_subdirectory/]은(는) locations 필드의 URL이 // 다음에 하위 디렉터리 경로로 끝날 때 포함된다. 이는 특히 GitHub 저장소와 같은 기존 저장소 레이아웃을 사용할 때 저장소 구조에 유연성을 제공한다.

예를 들어, URL이 https://github.com/org/repo/archive/refs/heads/main.tar.gz//repo-main이면 파일 구조는 다음과 같다:

main.tar.gz
└──repo-main/
   ├── index.json
   └── pkg/
       └── ...

이 경우 repo-main/은(는) tar.gz 파일 내에서 VEX 저장소의 루트 디렉터리이다.

3.2 index.json

index.json 파일은 아카이브 파일의 내용에 대한 매니페스트 역할을 한다. 아카이브의 루트 디렉터리 또는 URL에 정의된 경우 지정된 하위 디렉터리에 배치되어야 한다(MUST). 이 파일은 다음 구조를 가져야 한다(MUST):

{
  "updated_at": "2023-07-04T12:00:00Z",
  "packages": [
    {
      "id": "pkg:deb/debian/curl",
      "location": "pkg/deb/debian/curl/vex.json"
    },
    {
      "id": "pkg:npm/lodash",
      "location": "pkg/npm/lodash/vex.json",
      "format": "csaf"
    }
  ]
}

필드 설명:

vex-repo-spec

인기