패키지 소스 매핑

패키지 원본 매핑은 특히 퍼블릭 및 프라이빗 패키지 원본을 혼합하여 사용하는 경우 공급망 보안을 개선하는 데 사용할 수 있는 도구입니다.

기본적으로 NuGet은 패키지를 다운로드해야 하는 경우 구성된 모든 패키지 원본을 검색합니다. 패키지가 여러 원본에 있는 경우 패키지를 다운로드할 원본을 결정하지 못할 수 있습니다. 패키지 원본 매핑을 사용하면 패키지별로 NuGet에서 검색할 원본을 필터링할 수 있습니다.

또한 공격 방지를 위해 공급망을 강화하는 데 도움이 되는 다른 모범 사례에 대한 제안도 있습니다.

패키지 원본 매핑이 NuGet 6.0에 추가되었습니다. Visual Studio 17.5부터 Visual Studio 옵션 대화 상자를 사용하여 패키지 원본 매핑을 추가하고 제거할 수 있습니다.

Visual Studio 지원

Visual Studio	패키지 소스 매핑	도구 지원 -> 옵션	패키지 관리자 UI 지원
17.0 - 17.4	✅ 사용 가능	❌ 사용 불가	❌ 사용 불가
17.5	✅ 사용 가능	✅ 사용 가능	❌ 사용 불가
17.7 미리 보기 3	✅ 사용 가능	✅ 사용 가능	✅ 상태가 표시됩니다.

이 기능은 모든 NuGet 통합 도구에서 사용할 수 있습니다.

• Visual Studio 2022 이상
• .NET SDK 6.0.100 이상
• nuget.exe 6.0.0 이상

이전 도구는 패키지 소스 매핑 구성을 무시합니다. 이 기능을 사용하려면 모든 빌드 환경에서 호환되는 도구 버전을 사용해야 합니다.

패키지 소스 매핑은 호환되는 도구가 사용되는 한 .NET Framework 포함한 모든 프로젝트 형식에 적용됩니다.

연습 동영상

패키지 소스 매핑 기능에 대한 비디오 개요를 보려면 YouTube에서 Secure your NuGet packages with Package Source Mapping(패키지 소스 매핑을 사용하여 NuGet 패키지 보안) 비디오를 시청하세요.

패키지 소스 매핑 사용

이 기능을 옵트인하려면 nuget.config 파일이 있어야 합니다. 리포지토리의 루트에 단일 nuget.config를 두는 것이 모범 사례로 간주됩니다. 자세한 내용은 nuget.config 설명서를 참조하세요.

Visual Studio 옵션 대화 상자를 사용하여 사용

1. Visual Studio에서 솔루션을 엽니다.
2. 옵션 대화 상자로 Package Source Mappings 이동합니다.

패키지 관리자 UI에서

• 목록에서 패키지를 선택하여 세부 정보 창에 표시합니다.
• Configure 단추를 눌러 패키지 원본 매핑 옵션 페이지를 엽니다.

Visual Studio 옵션 대화 상자에서

• Tools 기본 Visual Studio 도구 모음의 메뉴로 이동하여 ->Package Manager Settings를 선택합니다 NuGet Package Manager .
• Package Source Mappings 페이지로 이동합니다.

3. Add 페이지의 단추를 Package Source Mappings 눌러 대화 상자를 Add Package Source Mappings 엽니다.

4. 패키지 ID 또는 패키지 패턴을 입력하고 원하는 원본에 대한 확인란을 전환하여 하나 이상의 패키지 원본을 선택합니다.

5. Package Source Mapping 옵션 페이지에 새로 만든 원본 매핑이 표시됩니다.

6. 옵션 대화 상자를 눌러 OK 적용 가능한 변경 내용을 저장합니다 nuget.config.
7. NuGet 패키지 관리자 창이 새로 고쳐지고 선택한 패키지 원본 매핑의 새 상태가 반영됩니다.

수동으로 편집하여 사용 nuget.config

• nuget.config 파일에서 원하는 패키지 소스를 선언합니다.
• 소스 선언 후 각 소스에 대해 원하는 매핑을 지정하는 <packageSourceMapping> 요소를 추가합니다.
• 사용 중인 소스 각각에 대해 정확히 하나의 packageSource 요소를 선언합니다.
  • 필요한 만큼 패턴을 추가합니다.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <!-- Define the package sources, nuget.org and contoso.com. -->
  <!-- `clear` ensures no additional sources are inherited from another config file. -->
  <packageSources>
    <clear />
    <!-- `key` can be any identifier for your source. -->
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="contoso.com" value="https://contoso.com/packages/" />
  </packageSources>
  
  <!-- Define mappings by adding package patterns beneath the target source. -->
  <!-- Contoso.* packages and NuGet.Common will be restored from contoso.com,
       everything else from nuget.org. -->
  <packageSourceMapping>
    <!-- key value for <packageSource> should match key values from <packageSources> element -->
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="contoso.com">
      <package pattern="Contoso.*" />
      <package pattern="NuGet.Common" />
    </packageSource>
  </packageSourceMapping>
</configuration>

패키지 소스 매핑 설정은 다양한 수준의 여러 nuget.config 파일(컴퓨터 수준, 사용자 수준, 리포지션 수준)이 있을 때 nuget.config 우선 순위 규칙에 따라 적용됩니다.

패키지 소스 매핑 규칙

최대한의 유연성과 제어를 위해 NuGet에서는 모든 패키지가 잘 정의된 우선 순위를 통해 패키지 패턴과 일치해야 합니다.

패키지 패턴 요구 사항

요청된 모든 패키지는 정의된 패키지 패턴을 일치시켜 하나 이상의 소스에 매핑되어야 합니다. 즉, packageSourceMapping 요소를 정의한 후에는 전이적 패키지를 포함해 모든 패키지가 복원될 소스를 명시적으로 정의해야 합니다.

• 최상위 패키지와 전이적 패키지는 모두 정의된 패턴과 일치해야 합니다. 최상위 패키지와 그 종속성이 동일한 소스에서 오는 요구 사항은 없습니다.
• 여러 소스에서 동일한 ID 패턴을 정의할 수 있어, 패턴을 정의하는 피드에서 일치하는 패키지 ID를 복원할 수 있습니다. 그러나 이는 복원 예측 가능성에 미치는 영향 때문에 권장되지는 않습니다(해당 패키지가 여러 소스에서 올 수 있어). 이 구성은 모든 해당 소스를 신뢰하는 경우 유효할 수 있습니다.

패키지 패턴 구문

패턴	예제 구문	설명
패키지 접두사 패턴	*, NuGet.*	*로 끝나야 합니다. 여기서 *는 0자 이상과 일치합니다. *는 허용되는 가장 짧은 접두사 패턴이며 모든 패키지 ID와 일치합니다.
패키지 ID 패턴	NuGet.Common, Contoso.Contracts	정확한 패키지 ID입니다.

패키지 패턴 우선 순위

여러 고유 패턴이 패키지 ID와 일치할 때는 가장 구체적인 패턴이 선호됩니다. 패키지 ID 패턴은 항상 우선 순위가 가장 높지만 제네릭 * 우선 순위는 항상 가장 낮습니다. 패키지 접두사 패턴은 가장 긴 패턴이 우선합니다.

기본 원본 설정

* 패턴을 사용하여 사실상 기본 소스를 선언할 수 있습니다. 즉, 지정된 다른 패턴과 일치하지 않는 패키지는 오류를 throw하지 않고 해당 원본에서 복원됩니다. 이 구성은 주로 nuget.org의 패키지를 사용하고 몇 개의 내부 패키지만 있거나 Contoso.*과 같은 모든 내부 패키지에 표준 접두사를 사용하는 경우에 유리합니다.

팀에서 설치하기 전에 내부 패키지 ID에 표준 접두사를 사용하지 않거나 nuget.org 패키지를 검사하는 경우 프라이빗 원본을 기본값으로 설정하면 요구 사항에 더 적합합니다.

참고 항목

요청된 패키지가 전역 패키지 폴더에 이미 있는 경우 원본 조회가 발생하지 않으며 매핑이 무시됩니다. 이 기능의 전체 보안 이점을 얻으려면 리포지토리에 대한 전역 패키지 폴더를 선언하는 것이 좋습니다. 다음 반복을 위해 기본 전역 패키지 폴더를 사용하여 환경을 개선하기 위한 작업이 계획되어 있습니다. 패키지 설치의 작동 방식에 관한 자세한 내용은 개념 문서를 참조하세요.

시작하기

리포지토리를 완전히 온보딩할 수 있는 두 가지 방법이 있습니다. 수동으로 하거나 또는 NuGet.PackageSourceMapper 도구를 사용합니다.

수동 온보딩

수동 온보딩의 경우 다음 단계를 수행할 수 있습니다.

1. 리포지토리에 대한 새 전역 패키지 폴더를 선언합니다.
2. dotnet restore를 실행하여 종속성을 복원합니다.
3. dotnet list package --include-transitive를 실행하여 솔루션의 모든 최상위 및 전이적 패키지를 봅니다.
   • packages.config를 사용하는 .NET Framework 프로젝트의 경우 packages.config 파일에 모든 직접 및 전이적 패키지의 플랫 목록이 포함됩니다.
4. 전이적 패키지를 포함해 솔루션의 모든 패키지 ID가 대상 원본의 패턴과 일치하도록 매핑을 정의합니다.
5. dotnet nuget locals global-packages -c를 실행하여 global-packages 디렉터리를 지웁니다.
6. 복원을 실행하여 매핑이 올바르게 구성되었는지 확인합니다. 매핑이 솔루션의 모든 패키지 ID를 완전히 다루지 않는 경우에 오류 메시지로 문제를 쉽게 식별할 수 있습니다.
7. 복원이 성공하면 완료됩니다. 필요에 따라 다음을 고려합니다.
   • 광범위한 패키지 ID 접두사 또는 가능한 경우 기본 원본을 설정하여 더 적은 수의 선언으로 구성을 간소화합니다.
   • 전역 패키지 폴더의 메타데이터 파일을 확인하거나 복원 로그를 검토하여 각 패키지가 복원된 원본을 확인합니다.

도구를 사용한 자동화된 온보딩

많은 리포지토리에 많은 수의 패키지가 있으며 수동으로 작업을 수행하려면 시간이 오래 걸릴 수 있습니다. NuGet.PackageSourceMapper 도구는 프로젝트의 알려진 패키지 및 원본에 따라 자동으로 NuGet.config를 생성할 수 있습니다.

패키지 소스 매퍼 도구를 사용하려면 빌드의 일부로 생성된 각 .nupkg.metadata 파일을 읽을 성공적인 패키지 복원을 완료하여 각 패키지와 소스를 매핑할 방법을 가장 잘 이해해야 합니다. 도구는 상위 종속성을 포괄할 뿐만 아니라 매핑을 생성할 때 모든 전이적 종속성을 고려합니다.

도구에는 필요에 따라 매핑 패턴을 생성하는 몇 가지 옵션이 있습니다. 자세한 내용은 블로그 게시물 및 도구의 추가 정보 지침을 확인하세요.

원본 매핑의 모양은 샘플 리포지토리를 참조하세요.

참고 항목

• 패키지 소스 매핑 구성을 관리하기 위한 nuget.exe 또는 dotnet.exe 명령은 없습니다. NuGet/Home#10735를 참조하세요.
• 패키지 설치 시 패키지를 매핑할 수 있는 방법이 없습니다. NuGet/Home#10730을 참조하세요.
• DotNetCoreCLI@2 Azure Pipelines 작업을 사용할 때 제한 사항이 적용되는지, 이는 소스 매핑 구성에서 feed- 접두사를 사용하여 해결할 수 있습니다. 그러나 인증이 필요한 경우 NuGetAuthenticate를 사용하고 스크립트 작업에서 곧바로 dotnet CLI를 호출하는 것이 권장됩니다. microsoft/azure-pipelines-tasks#15542를 참조하세요.