Skip to content

upstream-behavior.md

Latest commit

 

History

History
189 lines (115 loc) · 9.19 KB

upstream-behavior.md

File metadata and controls

189 lines (115 loc) · 9.19 KB
title Safeguard against malicious public packages
description Learn how to control access to public registries and protect your environment from malicious public packages.
ms.service azure-devops-artifacts
ms.topic conceptual
ms.date 08/22/2023
ms.author rabououn
author ramiMSFT
monikerRange azure-devops

Safeguard against malicious public packages

[!INCLUDE version-lt-eq-azure-devops]

With Azure Artifacts upstream sources, developers gain the convenience of using a unified feed to both publish and consume packages from Artifact feeds and popular public registries like NuGet.org or npmjs.com. Previously, Artifact feeds combined a list of available package versions from both the feed itself and all the configured upstream sources.

:::image type="content" source="media/previous-behavior.svg" alt-text="An illustration showing the content of a feed.":::

The Allow externally-sourced versions is a feature that enables developers to choose if they want to consume externally sourced package versions. It governs which packages are accessible from the public registries for specific packages.

When you disable the Allow External Versions toggle, versions from the public registry are blocked and become unavailable for download. This adds an extra layer of security by preventing exposure to potentially malicious packages from public registries.

However, if users prefer, they can enable the Allow External Versions toggle to allow access to and consume packages from public registries.

Note

This setting will not make changes to any package versions that are already saved to the feed. Access to these package versions will not change as a result of changing this setting.

Applicable scenarios

The following section illustrates various common scenarios where the external version setting blocks externally sourced package versions, and other scenarios where there's no need to block access to public packages.

Public versions are blocked

Private package version made public

In this scenario, a team has a private package that was made public. The external versions setting in this case will cause the feed to block consumption of any new versions with that package name from a public source.

:::image type="content" source="media\internal-to-public.svg" alt-text="An illustration showing an internal package version made public.":::

Having both private and public packages

In this scenario, if a team uses a combination of private and public packages, disallowing externally sourced packages blocks any new package versions from the public registry.

:::image type="content" source="media\private-and-public-packages.svg" alt-text="An illustration showing available private and public packages.":::

Public versions won't be blocked

All packages are private*

If all existing packages are private, and the team has no plans to use any public packages, the external versions setting has no effect on the team's workflow in this scenario.

:::image type="content" source="media\only-private-packages.svg" alt-text="An illustration showing feed with only private packages.":::

All packages are public

In this scenario, if the team exclusively consumes public packages, whether from the public registry or other open-source repositories, the setting doesn't affect their workflow in any way.

:::image type="content" source="media\public-packages-only.svg" alt-text="An illustration showing feed with only public packages.":::

Public package made private

In this situation, when a public package is converted to a private package, the external versions setting doesn't affect the team's workflow in any way.

:::image type="content" source="media\public-to-internal.svg" alt-text="An illustration showing a package converted from public to private.":::

Allow external versions

Note

You must be a Feed Owner to allow externally sourced versions. For more information, see Feed permissions.

  1. Sign in to your Azure DevOps organization, and then navigate to your project.

  2. Select Artifacts, and then select your feed from the dropdown menu.

  3. Select your package, and then select the ellipsis button for more options. Select Allow externally-sourced versions.

    :::image type="content" source="media\allow-external-versions.png" alt-text="A screenshot showing how to allow externally sourced versions.":::

  4. Select the toggle button to allow external versions. Select Close when you're done.

    :::image type="content" source="media\enable-external-versions.png" alt-text="A screenshot showing how to enable external versions.":::

Allow external versions using the REST API

NuGet

npm

Python

Maven

Allow external versions using PowerShell

  1. Create a personal access token with Packaging > Read, write, & manage permissions.

    :::image type="content" source="media\packaging-permissions.png" alt-text="Screenshot showing how to select packaging permissions.":::

  2. Create an environment variable for your personal access token.

    $env:PATVAR = "YOUR_PERSONAL_ACCESS_TOKEN"

  3. Convert your personal access token to baser64 encoded string and construct the HTTP request header.

    $token = [Convert]::ToBase64String(([Text.Encoding]::ASCII.GetBytes("username:$env:PatVar")))
$headers = @{
    Authorization = "Basic $token"
}

  4. Construct your endpoint url. Example: //pkgs.dev.azure.com/MyOrg/MyProject/_apis/packaging/feeds/MyFeed/nuget/packages/pkg1.0.0.nupkg/upstreaming?api-version=6.1-preview.1

    • Project-scoped feed:

      $url = "https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_apis/packaging/feeds/<FEED_NAME>/<PROTOCOL>/packages/<PACKAGE_NAME>/upstreaming?api-version=6.1-preview.1"

    • Organization-scoped feed:

      $url = "https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/_apis/packaging/feeds/<FEED_NAME>/<PROTOCOL>/packages/<PACKAGE_NAME>/upstreaming?api-version=6.1-preview.1"

Get upstreaming behavior

Run the following command to retrieve the upstream behavior state of your package. $url and $headers are the same variables we used in the previous section.

Invoke-RestMethod -Uri $url -Headers $headers

Set upstreaming behavior

Run the following commands to allow externally sourced versions for your package. This sets versionsFromExternalUpstreams to AllowExternalVersions, and uses the $url and $headers variables to query the REST API.

$body = '{"versionsFromExternalUpstreams": "AllowExternalVersions"}'

Invoke-RestMethod -Uri $url -Headers $headers -Body $body -Method Patch -ContentType "application/json"

Note

In some cases, setting up the upstream behavior can take time to propagate across the service. If your package is not available after updating the settings, please allow up to 3 hours for the new settings to take effect.

Clear upstreaming behavior

To clear the upstream behavior for your package, run the following commands to set versionsFromExternalUpstreams to Auto and query the REST API.

$body = '{"versionsFromExternalUpstreams": "Auto"}'

Invoke-RestMethod -Uri $url -Headers $headers -Body $body -Method Patch -ContentType "application/json"

Related articles