리포지토리 보안 권고 작성 모범 사례

보안 권고를 만들거나 편집할 때 표준 형식을 사용하여 에코시스템, 패키지 이름, 영향을 받는 버전을 지정하면 다른 사용자가 제공된 정보를 더 쉽게 이해할 수 있습니다.

누가 이 기능을 사용할 수 있나요?

리포지토리 소유자, 조직 소유자, 보안 관리자 및 관리자 역할이 있는 사용자

이 문서의 내용

참고 항목

보안 연구원인 경우 관리자에게 직접 연락하여 관리하지 않는 리포지토리에서 보안 권고를 만들거나 CVE를 대신 발급하도록 요청해야 합니다. 그러나 리포지토리에 대해 프라이빗 취약성 보고를 사용하도록 설정한 경우 취약성을 비공개로 직접 보고할 수 있습니다. 자세한 내용은 보안 취약성 비공개 보고을(를) 참조하세요.

리포지토리 보안 권고 정보

리포지토리 보안 권고를 통해 퍼블릭 리포지토리 유지 관리자가 프로젝트의 보안 취약성을 비공개로 논의하고 수정할 수 있습니다. 수정 사항을 공동으로 수행한 후 리포지토리 관리자는 보안 공지를 게시하여 보안 취약성을 프로젝트 커뮤니티에 공개적으로 공개할 수 있습니다. 리포지토리 관리자는 보안 공지를 게시하여 커뮤니티가 더 쉽게 패키지 종속성을 업데이트하고 보안 취약성의 영향을 조사할 수 있습니다. 자세한 내용은 리포지토리 보안 공지 정보을(를) 참조하세요.

리포지토리 보안 권고를 작성하거나 전역 보안 권고에 대한 커뮤니티 기여를 할 때 GitHub Advisory Database에서 사용하는 구문, 특히 버전 서식을 사용하는 것을 권장합니다.

GitHub Advisory Database의 구문, 특히 영향을 받는 버전을 정의할 때의 구문을 따르면 다음과 같은 이점이 있습니다:

  • 리포지토리 권고를 게시하면, 추가 정보를 요청하지 않아도 권고를 "GitHub-검토 완료" 권고로 GitHub Advisory Database에 추가할 수 있습니다.
  • Dependabot이(가) 영향을 받는 리포지토리를 정확히 식별하고, 알림을 위해 해당 리포지토리에 Dependabot alerts을(를) 보낼 수 있는 정보를 갖게 됩니다.
  • 커뮤니티 구성원이 누락되었거나 잘못된 정보를 수정하기 위해 권고에 대한 편집을 제안할 가능성이 줄어듭니다.

보안 권고 초안 양식을 사용하여 리포지토리 권고를 추가하거나 편집합니다. 자세한 내용은 리포지토리 보안 공지 만들기을(를) 참조하세요.

보안 권고 개선 양식을 사용하여 기존 전역 권고에 대한 개선을 제안합니다. 자세한 내용은 GitHub Advisory Database에서 보안 권고 편집을(를) 참조하세요.

에코시스템

에코시스템 필드를 사용하여 지원되는 에코시스템 중 하나에 권고를 할당해야 합니다. 지원되는 에코시스템에 대한 자세한 내용은 GitHub Advisory Database에서 보안 권고 탐색을(를) 참조하세요.

보안 권고 양식의 "영향을 받는 제품" 영역 스크린샷. "에코시스템" 필드가 짙은 주황색 윤곽선으로 강조 표시됩니다.

패키지 이름

GitHub Advisory Database에서 "GitHub-검토 완료" 권고를 작성하려면 패키지 정보가 필요하므로, 영향을 받는 패키지를 지정할 때 패키지 이름 필드를 사용하는 것을 권장합니다. 패키지 정보는 리포지토리 수준 보안 권고에서는 선택 사항이지만, 이 정보를 미리 포함하면 보안 권고를 게시할 때 검토 프로세스가 간소화됩니다.

영향을 받는 버전

GitHub Advisory Database에서 "GitHub-검토 완료" 권고를 작성하려면 버전 정보가 필요하므로, 영향을 받는 버전을 지정할 때 영향을 받는 버전 필드를 사용하는 것을 권장합니다. 버전 정보는 리포지토리 수준 보안 권고에서는 선택 사항이지만, 이 정보를 미리 포함하면 보안 권고를 게시할 때 검토 프로세스가 간소화됩니다.

GitHub Advisory Database에 대한 자세한 내용은 https://github.com/github/advisory-database을(를) 참조하세요.

Glossary

  •           **취약한 버전 범위(VVR):** 특정 소프트웨어 버그에 취약한 버전 범위입니다.

  •           **연산자**: 취약한 버전 범위의 경계를 나타내는 모든 기호입니다.

  •           **오픈 소스 취약점 형식(OSV):** GitHub Advisory Database 데이터가 호환되도록 목표로 하는 형식입니다.

버전 구문

  • 작은 숫자는 큰 숫자보다 더 이전 버전입니다. 예를 들어 1.0.0은(는) 2.0.0보다 낮은 버전입니다.
  • 알파벳에서 앞선 글자는 뒤의 글자보다 더 이전 버전입니다. 예를 들어 2.0.0-a은(는) 2.0.0-b보다 이전 버전입니다.
  • 숫자 뒤에 오는 모든 문자는 시험판의 일부로 간주되므로, 숫자 뒤에 문자가 있는 버전은 버전 번호에 문자가 없는 숫자보다 더 이전 버전입니다. 예를 들어 2.0.0-alpha, 2.0.0-beta, 2.0.0-rc은(는) 2.0.0보다 이전 버전입니다.
  • 수정된 버전은 VVR에서 가장 큰 숫자보다 작을 수 없습니다. 예를 들어 취약한 버전이 릴리스되었고 유지 관리자가 다운그레이드를 권장한다고 가정합니다. 그 낮은 버전은 취약한 버전보다 작기 때문에, 유지 관리자는 Fixed 필드에서 해당 낮은 버전을 수정된 버전 또는 패치된 버전으로 라벨링할 수 없습니다.

지원되는 연산자

  •           `>=`은(는) “이 버전 이상(>=)”을 의미합니다.

  •           `>`은(는) “이 버전 초과(>)”를 의미합니다.

    경고

    GitHub에서 > 연산자 사용을 지원하긴 하지만, OSV 형식에서 지원되지 않으므로 이 연산자를 사용하는 것은 권장되지 않습니다.

  •           `=`은(는) “이 버전과 같음(=)”을 의미합니다.

  •           `<=`은(는) “이 버전 이하(<=)”를 의미합니다.

  •           `<`은(는) “이 버전 미만(<)”을 의미합니다.

GitHub에서 영향을 받는 버전 지정

권고의 영향을 받는 버전을 명확히 정의하는 것이 중요합니다. GitHub에서는 영향을 받는 버전 필드에서 취약한 버전 범위를 지정할 수 있도록 여러 옵션을 제공합니다.

일부 기존 권고에서 영향을 받는 버전이 어떻게 정의되어 있는지에 대한 예시는 예시를 참조하세요.

  • 유효한 영향을 받는 버전 문자열은 다음 중 하나로 구성됩니다:

    • 하한 연산자 시퀀스.

    • 상한 연산자 시퀀스.

    • 상한과 하한 연산자 시퀀스 모두. 하한이 먼저 와야 하며, 그 다음 쉼표와 공백 1개, 그리고 상한이 와야 합니다.

    • 같음(=) 연산자를 사용하는 특정 버전 시퀀스.

    • 각 연산자 시퀀스는 연산자, 공백 1개, 그리고 버전 순서로 지정해야 합니다. 유효한 연산자에 대한 자세한 내용은 위의 지원되는 연산자를 참조하세요.

    • 버전은 숫자로 시작해야 하며, 그 뒤에는 숫자, 문자, 점, 대시, 밑줄(공백이나 쉼표를 제외한 모든 문자)이 얼마든지 올 수 있습니다. 버전 서식에 대한 자세한 내용은 위의 버전 구문을 참조하세요.

    참고 항목

    영향을 받는 버전 문자열에는 선행 또는 후행 공백을 포함할 수 없습니다.

  • 상한 연산자는 포함 또는 제외일 수 있습니다. 즉 각각 <= 또는 <입니다.

  • 하한 연산자는 포함 또는 제외일 수 있습니다. 즉 각각 >= 또는 >입니다. 하지만 리포지토리 권고를 게시하고 리포지토리 권고를 전역 권고로 승격하는 경우에는 다른 규칙이 적용됩니다. 하한 문자열은 포함만 허용됩니다. 즉 >=만 허용됩니다. 제외 하한 연산자(>)는 버전이 0인 경우에만 허용됩니다. 예: > 0.

  • 공백을 올바르게 사용하는 방법

    • 연산자와 버전 번호 사이에는 공백을 넣으세요.

    • >= 또는 <=에는 공백을 넣지 마세요.

    • >= lower bound, <= upper bound에서 숫자와 쉼표 사이에는 공백을 넣지 마세요.

    • 쉼표와 상한 연산자 사이에는 공백을 넣으세요.

    참고 항목

    하한 제한:

    • 이는 OSV 스키마와의 비호환성 때문입니다.
    • GitHub Advisory Database에서 기존 권고에 대해 제안을 할 때만 적용됩니다.

  • > 2.0, < 2.3, > 3.0, < 3.2처럼 동일한 필드에서 여러 영향을 받는 버전 범위를 지정할 수는 없습니다. 둘 이상의 범위를 지정하려면 + 다른 영향을 받는 제품 추가 버튼을 클릭하여, 각 범위마다 새 영향을 받는 제품 섹션을 만들어야 합니다.

    보안 권고 양식의 "영향을 받는 제품" 영역 스크린샷. "다른 영향을 받는 제품 추가" 링크가 짙은 주황색 윤곽선으로 표시됩니다.

  • 영향을 받는 버전 범위에 상한 또는 하한 하나만 포함되는 경우:

    • 하한을 명시적으로 지정하지 않으면 암묵적 값은 항상 > 0입니다.
    • 상한을 명시적으로 지정하지 않으면 암묵적 값은 항상 무한대입니다.

VVR에서 상한만 설정하기

  • 상한만 설정하는 경우 <= 또는 <을(를) 사용하세요.
  • GitHub Advisory Database은(는) 데이터 소스 중 하나로 PyPA 데이터베이스를 사용합니다. 하지만 GitHub은(는) PyPA VVR 형식과 정확히 일치하지 않습니다(PyPa 보안 권고는 상한만 있는 버전 범위를 가리키기 위해 >= 0, <= n 또는 >= 0, < n을(를) 자주 사용합니다).
  • 상한만 있는 범위에는 >= 0을(를) 포함할 필요가 없습니다.

VVR에서 하한만 설정하기

  • 권고 큐레이션 팀은 맬웨어를 제외한 어떤 권고에서도 하한만 설정하는 것을 권장하지 않습니다. 이는 수정된 버전이 나중에 릴리스되면, 권고를 수동으로 업데이트할 때까지 수정된 버전을 사용하는 사용자도 불필요한 Dependabot alerts을(를) 계속 받게 되기 때문입니다.
  • 모든 버전에 >= 0 사용
  •           `> 0`은(는) 일반적으로 사용되지 않습니다.

영향을 받는 버전 하나만 지정하기

  •           `= n`은(는) 영향을 받는 단일 버전에 사용
  • =은(는) 공개 프리뷰나 비공개 프리뷰를 자동으로 포함하지 않으며, 오직 지정된 버전만 포함한다는 점에 유의하세요.

일반 오류

  • < n 취약한 버전 범위를 사용한 다음 n+1이(가) 패치되었다고 말하는 방식은 피하세요.

    •           `< n`은(는) `n`이(가) 취약하지 않을 때만 사용해야 합니다.
    • 이 경우 VVR은 <= n 또는 < n+1(이)여야 합니다.

  • 공식 버전 번호에 문자가 포함된 수정된 버전을 설명할 때 숫자만 사용하는 것은 피하세요. 소프트웨어에 linux 및 windows 두 개의 분기가 있다고 가정합시다. 2.0.0-linux 및 2.0.0-windows을(를) 릴리스할 때, 취약한 버전으로 < 2.0.0을(를) 사용하면 버전 로직이 -linux 및 -windows을(를) 시험판으로 해석하기 때문에 2.0.0-linux 및 2.0.0-windows이(가) 취약한 것으로 표시됩니다. 2.0.0-linux 및 2.0.0-windows이(가) 취약한 것으로 간주되는 것을 방지하려면, 알파벳에서 가장 앞선 분기인 2.0.0-linux을(를) 첫 번째 패치된 버전으로 표시해야 합니다.

예시

여러 VVR과 여러 연산자를 포함하는 권고

          [etcd Gateway TLS 인증은 DNS SRV 레코드에서 검색된 엔드포인트에만 적용(GHSA-wr2v-9rpq-c35q)](https://github.com/advisories/GHSA-wr2v-9rpq-c35q)에는 두 개의 취약한 버전 범위가 있습니다.

  •           `< 3.3.23`은(는) 하한 없이 상한만 있으며, `<` 연산자를 사용합니다.

  •           `>= 3.4.0-rc.0, <= 3.4.9`은(는) 상한과 하한이 모두 있으며, `>=` 및 `<=` 연산자를 사용합니다.

시험판과 정식 릴리스 간의 관계를 보여주는 권고

          [XWiki 플랫폼은 문자열 속성에서 XClass 이름을 통해 XSS를 허용(GHSA-wcg9-pgqv-xm5v)](https://github.com/advisories/GHSA-wcg9-pgqv-xm5v)에는 네 개의 취약한 버전 범위가 있습니다.
  • >= 1.1.2, < 14.10.21
  • >= 15.0-rc-1, < 15.5.5
  • >= 15.6-rc-1, < 15.10.6
  • = 16.0.0-rc-1

이 VVR 중 세 개에는 취약한 버전 범위에 시험판이 포함됩니다. 마지막 VVR인 = 16.0.0-rc-1은(는) 16.0.0-rc-1만 취약하고, 그 다음에 나온 정식 릴리스 16.0.0은(는) 취약하지 않음을 보여줍니다. 이 로직은 16.0.0-rc-1과(와) 16.0.0을(를) 별도의 버전으로 간주하며, 16.0.0-rc-1이(가) 16.0.0보다 더 이전 릴리스로 간주됩니다.

이 취약성에 대한 패치는 2024년 1월 24일에 16.0.0 버전용으로 게시되었습니다. 자세한 내용은 xwiki/xwiki-platform 리포지토리의 커밋 27eca84를 참조하세요. MVN Repository 사이트의 XWiki Platform Old Core 페이지에 따르면 16.0.0-rc-1은(는) 수정 사항이 XWiki에 추가되기 전인 2024년 1월 22일에 게시되었고, 16.0.0은(는) 수정 사항이 커밋된 후인 2024년 1월 29일에 게시되었습니다.

버전 번호에 분기 이름이 포함된 권고

          [Google Guava](https://mvnrepository.com/artifact/com.google.guava/guava)는 버전 릴리스에 `android` 및 `jre` 두 개의 분기를 포함합니다.               [Guava가 임시 디렉터리의 안전하지 않은 사용에 취약점이 있음(GHSA-7g45-4rm6-3mm3)](https://github.com/advisories/GHSA-7g45-4rm6-3mm3) 및 [Guava의 정보 공개(GHSA-5mg8-w23w-74h3)](https://github.com/advisories/GHSA-5mg8-w23w-74h3)는 Guava에 영향을 주는 취약성에 대한 권고입니다. 두 권고 모두 패치된 버전으로 `32.0.0-android`을(를) 설정합니다.
  • 버전 범위 로직은 32.0.0 뒤의 문자를 시험판으로 해석하므로, 패치된 버전을 32.0.0(으)로 설정하면 32.0.0-android 및 32.0.0-jre 모두가 취약한 것으로 잘못 표시됩니다.
  • 버전 범위 로직은 알파벳에서 뒤의 문자가 앞의 문자보다 더 이후 버전이라고 해석하므로, 패치된 버전을 32.0.0-jre(으)로 설정하면 32.0.0-android이(가) 취약한 것으로 잘못 표시됩니다.

32.0.0-android과(와) 32.0.0-jre이(가) 모두 패치되었음을 나타내는 가장 좋은 방법은 패치된 버전으로 32.0.0-android을(를) 사용하는 것이며, 로직은 알파벳에서 32.0.0-android 이후의 모든 항목을 패치된 것으로 해석합니다.