Set up custom package repositories

Learn how to configure custom package repositories for dependency resolution.

Suppose your software components are private and are hosted in an internal package repository. In that case, you must provide authentication credentials to the registry, to create a complete bill of materials or perform static analysis.

You must set up custom package repositories if:

  • Your software package isn’t scanned as part of a post-build or install step
  • You are using the Endor Labs GitHub App
  • you are implementing scans across your environment for quick visibility
  • Authentication information to your private package repository is hosted outside of the repository

If your software components are private and hosted in AWS CodeArtifact, set up an OpenID Connect provider in AWS and create roles with trust policies to allow Endor Labs access to your CodeArtifact repositories. See Configure package manager integrations with AWS.

You can authenticate to private package artifact repositories using mutual TLS. See mTLS authentication to learn how to set up and authenticate.

Configure package manager integration

Endor Labs integrates with your self-hosted package repositories and source control systems to give you visibility into your environment. Package manager integrations allow users to simplify scanning using custom repositories.

Endor Labs generally respects package authentication and configuration settings and a package manager integration is usually not required to scan private packages successfully.

  • Use package manager integrations to simplify scanning when authentication to private repositories is not part of standard manifest or settings files.

  • Package manager integrations allow you to set custom repositories for each package ecosystem and the priority of each repository for scanning.

To set up a package manager integration:

  1. Sign in to Endor Labs.
  2. Select Manage > Integrations from the left sidebar.
  3. Click Manage in the package manager configuration you want to customize.
  4. Select Add Package Manager.
  5. Enter the name of the package manager.
  6. Select either Basic or AWS Code Artifactory as Authentication Type. See AWS authentication and basic authentication to learn more.
  7. To set up authentication for Maven, PyPI, Nuget, RubyGems, Packagist, and npm, see connect to private repositories.
  8. Click Advanced and select Propagate this policy to all child namespaces to apply the package manager integration to all child namespaces.
  9. Select Add Package Manager.

If you want to delete a package manager integration, click the trash can icon at the far right of the integration.

Basic authentication to private package repositories

Use basic authentication to connect with private package repositories across supported ecosystems.

Authenticate to Maven, PyPI, RubyGems and Nuget private package repositories

To connect to private repositories of Maven, PyPI, RubyGems and Nuget, enter the package manager URL and the package registry credentials such as username and password.

Basic Authentication for package manager integrations

Authenticate to npm private package registries

To connect to npm registry, enter the scope, package manager URL, and either base64-encoded username and password or basic authentication token as authentication method. See base64 encoded token to learn how to generate the token.

Package manager for npm

Authenticate to Packagist private package repositories

To connect to Packagist repository, enter the package manager host and the package registry credentials such as username and password. Select HTTP Basic from the list of AUTHENTICATION FOR PRIVATE REPOSITORIES.

Package manager for Packagist

Test private package manager connection

  1. Select Manage > Integrations from the left sidebar.
  2. Click Manage in the package manager configuration you want to customize.
  3. Click the vertical three dots of the package manager configured and select Test Connection.

Change package manager integration priority

Package manager integrations allow you to set the priority of each package repository used by a package manager in your tenant namespace. This defines the location from which a package manager looks when it attempts to resolve dependencies for a software package.

To change the package manager integration priority:

  1. Click and hold the integration you would like to change the priority of.
  2. Drag the integration to the priority spot that is most frequently used by your organization.

Package manager integrations

The following support matrix details support for package manager integrations:

Language Ecosystem Support mTLS
Java Maven (mvn://)
JavaScript npm (npm://)
Python PyPI (pypi://)
Ruby Gem (gem://)
PHP Composer (composer://)
.NET/C# nuget (nuget://)
Gradle Gradle Properties Supported through API

Private package manager integrations for Maven, PyPI, RubyGems, Nuget using API

Use endorctl to create a package manager resource through an API call and configure authentication for accessing private repositories during scans.

Run the following command to create a package manager resource and authenticate to private repository.

Replace:

  • username with your package registry username
  • xxxx with your package registry password
  • namespace with your namespace.
endorctl api create  -r PackageManager -n <namespace> -d '
{
    "meta": {
        "name": "test",
        "description": "test"
    },
    "spec": {
        "nuget": {
            "priority": 1,
            "url": "package manager url",
            "user": "username",
            "password": "xxxx"
        }
    },
    "propagate": true
} '

Private package manager integration for Gradle using API

Configure private package manager integration with Gradle to authenticate and fetch dependencies from private repositories during scans.

Gradle requires valid credentials, such as AWS access keys and GitHub or GitLab tokens, to access private repositories and fetch dependencies. Provide these credentials through the endorctl API call for GitHub App scans to run successfully.

The variable names you define (like mavenAccessKey, mavenSecretKey) must exactly match the property names used inside your build.gradle file when configuring credentials. For more information on how to align variable names with your build configuration, refer to Declaring private repositories.

Set Gradle credentials

Use endorctl to configure your repository credentials. You can set the necessary Gradle properties, allowing access to private repositories during the Gradle build process.

For example, to authenticate with an AWS S3-backed Maven repository, run the following commands to set the mavenAccessKey and mavenSecretKey properties. Replace namespace with your namespace.

endorctl api create -n <namespace> -r PackageManager -d '{
    "meta": {
        "name": "gradle properties"
    },
    "spec": {
        "gradle": {
            "property_key_name": "mavenAccessKey",
            "property_key_value": "your-access-key"
        }
    }
}'
endorctl api create -n <namespace> -r PackageManager -d '{
    "meta": {
        "name": "gradle properties"
    },
    "spec": {
        "gradle": {
            "property_key_name": "mavenSecretKey",
            "property_key_value": "your-secret-key"
        }
    }
}'

These credentials will then be available to your Gradle build at scan time. All values configured through the API are automatically exported as environment variables.

Considerations

When configuring Gradle credentials, consider the following scenarios:

AWS credentials with scan profile

If a scan profile is linked to your project, AWS credentials are directly written into ~/.gradle/gradle.properties and require exact key matches. You can use one of the following combinations:

  • AWS_ACCESS_KEY and AWS_SECRET_KEY
  • AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY

Authenticate using mutual TLS

Use mutual TLS to securely authenticate to artifact repositories. Currently, mutual TLS can be configured only through the API. See mTLS authentication for more information.

Package manager integration for npm using API

Use endorctl to create a package manager resource for your private npm registry and authenticate using one of the following tokens:

  • Base64-encoded username and password
  • Basic authentication token

Base64-encoded authentication token

  1. Generate base64 token

    To generate the base64 encoded username and password, run the following command. Copy the token generated and store it in a secure place.

    echo -n 'username:plain_password' | openssl base64
    
  2. Create package manager resource

    Run the following command to create a package manager resource and authenticate to npm registry using base64 token without scope.

    Replace:

    • base64 token with the generated base64 encoded username and password in the previous step.
    • namespace with your namespace.
    endorctl api create  -r PackageManager -n <namespace> -d '
    {
        "meta": {
            "name": "test npm with base64",
            "description": "test npm with base 64 token without scope"
        },
        "spec": {
            "npm": {
                "priority": 1,
                "url": "package manager url"
                "token": "base64 token"
            }
        },
        "propagate": true
    } '
    

Basic authentication token

Run the following command to create a package manager resource and authenticate to npm registry using basic authentication token with scope.

Replace:

  • xxx with your authentication token.
  • namespace with your namespace.
  • @scope with your scope. For example, "scope":"@abc-corp".
endorctl api create  -r PackageManager -n <namespace> -d '
{
    "meta": {
        "name": "test npm with auth token",
        "description": "test npm with auth token with scope"
    },
    "spec": {
        "npm": {
            "priority": 1,
            "scope": "@scope",
            "url": "package manager url",
            "auth_token": "xxxx"
        }
    },
    "propagate": true
} '

Package manager integration for Packagist using API

Run the following command to create a package manager resource and authenticate to Packagist repository.

Replace:

  • username with your package registry username.
  • xxxx with your package registry password.
  • namespace with your namespace.
  • your host with your package manager host. For example, "host": "repo.packagist.com".
endorctl api create  -r PackageManager -n <namespace> -d '
{
    "meta": {
        "name": "test packagist",
        "description": "test packagist"
    },
    "spec": {
        "packagist": {
           "auth_kind": "AUTH_KIND_HTTP_BASIC",
            "host": "your host",
            "user": "username",
            "password": "xxxx"
        }
    },
    "propagate": true
} '

Fetch package manager

Run the following command to fetch the package manager using the UUID:

endorctl api get -r packageManager -n <your namespace>  --uuid <take uuid from list command>

Delete package manager

Run the following command to delete the package manager using the UUID:

endorctl api delete -r packageManager -n <your namespace>  --uuid <take uuid from list command>

Authenticate to private packages using mTLS

Learn how to configure custom package repositories for dependency resolution using mTLS.

Configure integration with AWS

Learn how to configure package manager integrations with AWS CodeArtifact.