Internal packages

Prevent internal packages from being fetched from external upstreams

To prevent internal packages from being fetched from external upstreams, packages can be flagged internal in Bytesafe.

Internal packages and registries

  • Registries are by default flagged as internal
  • Package versions published, pushed or uploaded to an internal registry will automatically be flagged as internal

internal-package

When fetching versions for an internal package from upstreams, only upstreams containing internal flagged versions of the package will be considered. This prevents accidental fetches of internal packages from external upstreams - without any additional user interaction or configuration.

Example: Fetching internal packages for a registry using registry.npmjs.org as upstream

flowchart TD
  A(fab:fa-npm registry.npmjs.org) ---x | public registry will not be considered as upstream for internal package | B{Internal registry};
  E[fa:fa-user User A] --> | publish - internal package | B
  B --> | install - internal package | C[fa:fa-user Team B];
  B --> | install - internal package | D[fa:fa-server System C];

Using a Bytesafe private registry together with registry.npmjs.org as an upstream for public packages:

  • Package published to the private registry will be flagged internal
  • Install of internal package by other users / systems will never fetch versions from registry.npmjs.org as it does not contain internal versions
  • Installing any public package will work as normal, with registry.npmjs.org as a valid upstream

Dependency confusion

A Dependency Confusion attack, or Supply Chain Substitution attack, occurs when a user is tricked into pulling a version of a package from a public registry instead of the intended package of the same name from an internal registry.

This security risk is prevented with the use of internal packages. Internal packages in Bytesafe are designed to be a safe solution, that protects a users code supply chain out of the box and does not require any additional configuration to be secure.

Internal package versions can safely be pushed to other Bytesafe registries in the same workspace. The internal flag will be pushed together with the package, making sure internal packages are secure from dependency confusion across a users entire workspace.

Upstream issues are opened in scenarios where packages are found in multiple external upstreams, with non-matching contents. Warning you of potential dependency confusion attacks.

upstream-issue

Optional configuration

For most use cases there is no need to make any changes to how internal packages are handled in Bytesafe. But to cover other specific use cases, Bytesafe offers additional configuration related to internal packages.

Internal flag for registries

Registries are by default flagged as internal when created. Package versions published, pushed or uploaded to an internal registry will automatically be flagged as internal.

To disable this feature, toggle Internal registry to disabled in the registry settings.

internal-registry

Internal flag for package versions

Package versions published, pushed or uploaded to an internal registry will automatically be flagged as internal.

To toggle this flag for a specific package version, click the Internal checkbox on the page for a package version.

internal-package-toggle

Internal flag for upstreams

Upstreams outside the Bytesafe workspace can also be flagged as internal. This option only applies to External URL upstreams.

Any package version available from an internal upstream will be considered internal. This allows trusted registries outside the workspace to be used as source for internal packages.

Setting internal upstream flag for an upstream will make all package versions from that upstream considered internal. Make sure that upstream is not connected to other untrusted sources containing public packages (public registries or similar)

To enable/disable this feature for an external URL upstream, toggle Internal upstream when adding/editing an upstream.

internal-package-toggle

Special use-cases

Team using an external registry that contains internal (trusted) packages

A team might need to access internal packages from a source outside the workspace, like a private registry with packages published by a partner, or another team.

Another common use case is a Git repository containing unpublished internal versions of a package. By adding a Git repository as an upstream, and marking that upstream as internal, teams can access their unpublished versions from Git together with internal (but published) versions in Bytesafe registries.

flowchart TD
  A(fab:fa-npm registry.npmjs.org) ---x |  public registry will not be considered as upstream for internal package | B{internal registry};
  Git1(fab:fa-git Internal Git repository) --> |  pull - internal version | B;
  B --> | install  | D[fa:fa-user Developer];
  B --> | install  | E[fa:fa-user Developer];
  B --> | install  | F[fa:fa-user Developer];
  F ---> | push | Git1;

Registry containing packages that are also published externally

Most users that develop proprietary software never intend to publish their internal packages to a public registry. For those users there is no need to ever disable the internal flag for a registry.

Users that do publish to external registries from Bytesafe may want to disable this feature to allow public and internal versions to co-exist.