버전 비교 시:

• 버전은 사전식이 아닌 숫자로 비교해야 한다(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 예시

2.5 필드 설명 및 참고 사항

주요 필드

버전 하위 필드

위치 하위 필드

3. 저장소 구조

3.1 파일 구조

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

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

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

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

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

3.2 index.json

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

필드 설명:

인덱스 파일의 스키마는 여기에 정의되어 있다.

3.3 VEX 문서

각 패키지의 VEX 정보는 index.json 파일에 정의된 경로 구조에 따라 별도의 JSON 파일로 저장되어야 한다(MUST). 이러한 파일의 내용은 format 필드에 지정된 VEX 형식 사양(OpenVEX 또는 CSAF VEX)을 준수해야 한다(MUST). 단일 VEX 문서에는 동일한 패키지의 서로 다른 버전, 한정자 및 하위 경로에 대한 정보가 포함될 수 있다(MAY).

OpenVEX 문서 예시는 OpenVEX 사양을 참조하라.

3.4 사용 참고 사항

디렉터리 구조

• 버전, 한정자 및 하위 경로를 제외한 PURL을 기준으로 패키지의 디렉터리 구조를 만드는 것이 권장된다(RECOMMENDED). 예를 들어, PURL이 "pkg:deb/debian/curl"인 패키지는 "pkg/deb/debian/curl/vex.json"에 저장될 수 있다.
• OCI 패키지의 경우 PURL의 repository_url 한정자를 사용하여 디렉터리 구조를 만들 수 있다(MAY). 예를 들어, PURL이 "pkg:oci/debian@sha256:3e45770a143ee5afd1ebde5a6aea6e32a71d2bt5602f5dac8025db0d9cc19f10?repository_url=docker.io/library/debian"인 패키지는 "pkg/oci/docker.io/library/debian/vex.json"에 저장될 수 있다.
• VEX 파일의 실제 위치는 권장 구조와 관계없이 index.json 파일의 location 필드에서 자유롭게 정의할 수 있다(MAY).
• 아카이브 내의 모든 파일 경로는 운영 체제와 관계없이 구분자로 슬래시(/)를 사용해야 한다(MUST).
• 디렉터리 구조의 패키지 이름은 특수 문자를 포함하는 경우 URL 인코딩되어야 한다(MUST).

VEX 문서 내용

• 단일 VEX 문서에는 동일한 패키지의 서로 다른 버전, 한정자 및 하위 경로에 대한 정보가 포함될 수 있다(MAY).
• 특정 버전, 한정자 또는 하위 경로를 조회할 때 클라이언트는 관련 정보를 찾기 위해 전체 VEX 문서를 구문 분석해야 한다(MUST).

3.5 저장소 업데이트

VEX 저장소를 업데이트할 때:

1. 영향을 받는 패키지에 대한 새롭거나 업데이트된 vex.json 파일을 생성한다.
2. updated_at 타임스탬프 업데이트를 포함하여 변경 사항을 반영하도록 index.json 파일을 업데이트한다.
3. 업데이트된 내용으로 새 아카이브를 생성한다.
4. 새 아카이브를 매니페스트 파일(vex-repository.json)에 지정된 위치에 업로드한다.
5. 필요한 경우 매니페스트 파일(vex-repository.json)의 관련 locations URL을 업데이트한다.

4. 저장소 배포

4.1 개요

VEX 저장소는 VEX 데이터 및 관련 메타데이터를 포함하는 아카이브 파일로 배포되어야 한다(MUST). 이 아카이브는 vex-repository.json 파일의 locations 필드에서 참조되어야 하며(MUST), VEX 정보를 배포하는 주요 수단이다.

4.2 아카이브 형식

아카이브 파일은 다음 형식 중 하나여야 한다(MUST):

• tar.gz and tgz
• tar.bz2 and tbz2
• tar.xz and txz
• zip
• gz
• bz2
• xz

5. 클라이언트 구현 지침

5.1 버전 선택

versions 배열에서 버전을 선택할 때:

• 클라이언트는 spec_version 필드를 기준으로 지원하는 버전을 선택해야 한다(MUST).
• 클라이언트는 섹션 1에 정의된 규칙에 따라 버전을 비교해야 한다(MUST).
• versions 배열은 오래된 순서에서 최신 순서로 정렬되어 있음이 보장된다. 클라이언트는 이 순서를 사용하여 적절한 버전을 효율적으로 선택할 수 있다.
• v1.0 이상 버전의 경우:
  • 주 버전 내에서 하위 호환성이 유지되므로 클라이언트는 동일한 주 버전 내에서 지원하는 최신 버전을 선택할 수 있다(MAY).
• v0.Y 버전(Y는 임의의 부 버전)의 경우:
  • 클라이언트는 정확히 일치하는 버전을 선택해야 한다(SHOULD).
  • v0.Y 버전은 부 버전 간에 호환성을 깨는 변경 사항이 포함될 수 있기 때문이다(MAY).
• 지원되는 버전이 없으면 클라이언트는 저장소를 사용해서는 안 되며(MUST NOT), 사용자에게 알려야 한다(SHOULD).

5.2 위치 선택

locations 배열에 여러 위치가 있을 때:

1. 우선순위 순서: 클라이언트는 배열의 순서에 따라 위치의 우선순위를 정해야 한다(MUST). 먼저 나열된 위치를 먼저 시도한 후 후속 위치로 이동해야 한다.
2. 스키마 지원:
   • 현재 사양에서는 "https" 스키마만 지원된다.
   • 이 사양의 향후 버전에서는 추가 스키마가 도입될 수 있다.
   • 클라이언트는 각 위치의 URL 스키마를 확인하고 지원되는 스키마가 있는 위치만 사용해야 한다(SHOULD).
3. 폴백 메커니즘: 클라이언트가 한 위치에서 오류가 발생하면 배열의 다음 사용 가능한 위치를 시도해야 한다(SHOULD).

5.3 다중 저장소 지원

클라이언트는 여러 VEX 저장소를 지원하도록 설계되어야 한다(SHOULD).

저장소 우선순위

• 클라이언트는 저장소에 대한 우선순위 메커니즘을 구현해야 한다(SHOULD).
• 여러 저장소가 동일한 PURL에 대한 VEX 데이터를 제공하는 경우, 클라이언트는 저장소 우선순위에 따라 데이터를 선택해야 한다(SHOULD).
• 우선순위 방법은 사용자가 특정 요구 사항과 다양한 데이터 소스에 대한 신뢰도를 기준으로 조정할 수 있도록 구성 가능해야 한다(SHOULD).

5.4 업데이트 확인

클라이언트는 업데이트를 확인하기 위해 다음 프로세스를 사용해야 한다(SHOULD):

1. 마지막으로 성공한 업데이트 또는 업데이트 확인의 타임스탬프를 로컬에 저장한다.
2. 업데이트를 고려할 때 vex-repository.json 파일에서 update_interval을 검색한다.
3. 로컬에 저장된 타임스탬프에 update_interval을 더하여 다음 업데이트 시간을 계산한다.
4. 계산된 시간을 현재 시간과 비교한다:
   • 현재 시간이 계산된 시간보다 늦으면 업데이트 확인을 진행한다:
     • 최신 저장소 콘텐츠를 다운로드하기 위한 요청을 보낸다.
     • 새 콘텐츠가 있으면 업데이트된 저장소를 다운로드하고 처리한다.
     • 로컬에 저장된 타임스탬프를 현재 시간으로 업데이트한다.
   • 현재 시간이 계산된 시간보다 이르면 캐시된 저장소 콘텐츠를 계속 사용한다.

5.5 효율성 전략

효율적인 운영을 위해 클라이언트는 다음 전략을 구현할 수 있다(MAY):

1. 업데이트 확인 요청 시 HTTP ETag 또는 Last-Modified 헤더를 사용한다. 이는 콘텐츠가 변경되지 않은 경우 불필요한 다운로드를 최소화하는 데 도움이 될 수 있다.
2. 특히 update_interval이 매우 짧은 경우 과도한 네트워크 요청을 피하기 위해 업데이트 확인 사이의 최소 간격(예: 1시간)을 구현한다.
3. 계산된 다음 업데이트 시간과 관계없이 사용자가 즉시 확인을 강제할 수 있도록 업데이트 확인의 수동 재정의를 허용한다.