Skip to main content
You can use an AWS CodeArtifact repository as a package source for Package Firewall. Package Firewall evaluates each package request against your policy before it allows the download. Developers configure their package manager clients to use Package Firewall as the registry and authenticate with a Package Firewall API key. They don’t need AWS credentials, because Endor Labs uses an IAM role that you create to access your AWS CodeArtifact repository. Package Firewall doesn’t send the package file to the package manager client. When a package passes the policy, Package Firewall redirects the package manager client, which downloads the package file directly from your AWS CodeArtifact repository. Package Firewall supports the following package manager clients with AWS CodeArtifact:
  • npm, Yarn Classic, and Yarn Berry
  • pip and uv
  • Maven
  • gem and Bundler

Prerequisites

Ensure that you meet the following requirements before you configure Package Firewall:

Endor Labs requirements

  • The Admin role to add the integration and change the Package Firewall policy.
  • A Package Firewall API key. Package manager clients use the API key and secret as their username and password. See Create an API key for the Package Firewall to create the key.

AWS CodeArtifact repository

Create an AWS CodeArtifact repository for each ecosystem you want to use, and add an external connection to that ecosystem’s public registry, such as public:npmjs, public:pypi, public:maven-central, or public:ruby-gems-org. A repository can have only one external connection. You can configure the external connection on the repository or one of its upstream repositories. For more information, refer to Connect a CodeArtifact repository to a public repository.

IAM permissions

Create an IAM role that Endor Labs can use to access your AWS CodeArtifact repository. See Create an IAM role with trust policies to set up the role and its trust policy. The role needs the following permissions:
  • sts:GetServiceBearerToken, with the condition sts:AWSServiceName set to codeartifact.amazonaws.com, to get a bearer token for AWS CodeArtifact.
  • codeartifact:GetAuthorizationToken on the domain to get an authorization token for the repository.
  • codeartifact:GetRepositoryEndpoint on the repository to get the repository URL.
  • codeartifact:ReadFromRepository on the repository to read packages from the repository.
  • codeartifact:DescribePackageVersion on the packages in the repository to read package version metadata, such as the publish time and license.
For more information, refer to AWS CodeArtifact permissions reference and AWS CodeArtifact authentication and tokens. The AWS managed policy AWSCodeArtifactReadOnlyAccess includes these permissions, but it grants read access to every domain in the account. Grant the role permission to only read from the repository. Each download redirect includes a token with the role’s permissions, so anyone who has the token can use the same permissions. The following policy grants only the permissions that Package Firewall needs, for one domain and one repository. Replace <region>, <account-id>, <domain>, and <repository> with your values.

Network access

Ensure that developer machines and CI runners can access Package Firewall and the AWS CodeArtifact repository host:

Configure Package Firewall

Package Firewall reaches your AWS CodeArtifact repository through a package manager integration in Endor Labs, which you then select as the package source in your Package Firewall policy. Complete the following steps:
1

Configure the AWS CodeArtifact integration

Add an AWS CodeArtifact integration for each ecosystem you want to use with Package Firewall, in your tenant’s root namespace, where the Package Firewall policy is configured. Select the corresponding package manager, such as npm for npm packages. See Configure integration with AWS CodeArtifact to set up the integration.If you already use an AWS CodeArtifact integration in your tenant’s root namespace for scans, you can use the same integration for Package Firewall. An integration in a child namespace doesn’t appear in Package Sources.
2

Select the package source

In your Package Firewall policy, select the AWS CodeArtifact repository you configured as the package source for each ecosystem. See Select package sources to configure the package source.Ecosystems without an AWS CodeArtifact package source continue to use their public registry, so you can set up AWS CodeArtifact for one ecosystem at a time.
3

Configure package manager clients

Configure developer machines and CI runners to use Package Firewall as their package registry. See direct integration or MDM deployment to configure the clients.
4

Verify your setup

Install a package that doesn’t contain harmful code but that Endor Labs has classified as malware for testing, such as endor-firewall-test version 1.0.0, or io.github.endorlabs:endor-java-webapp-demo:4.1 for Maven. Package Firewall blocks the installation and returns an HTTP 403. See Verify your setup for the command for each client, and View Package Firewall logs to review the event.To confirm that the IAM role can read from your AWS CodeArtifact repository and that your network can reach it, install a package that passes your policy. The installation succeeds, and the package appears in the repository in the AWS Management Console.

Limitations

Package Firewall evaluates packages from AWS CodeArtifact against your configured policies, with the following exceptions:
  • AWS CodeArtifact doesn’t report gem publish times, so Package Firewall skips the minimum package age check for gems in AWS CodeArtifact.
  • For packages that you publish to AWS CodeArtifact yourself, Package Firewall applies only the restricted license and minimum package age checks. It doesn’t apply the malware and vulnerability checks, because Endor Labs has no malware or vulnerability data for private packages.
  • AWS CodeArtifact can take a few seconds to import a package version from the public registry. Until the import completes, Package Firewall can’t evaluate minimum package age for Maven or restricted licenses for PyPI. Package Firewall then applies your configured action for packages that cannot be evaluated.
Package Firewall passes an AWS CodeArtifact token to the package manager client in each download redirect. The token is valid for up to 35 minutes. A proxy that inspects TLS traffic and logs HTTP headers can record it.

Troubleshooting

The following are common issues and their possible causes. A package manager client’s error can show the Package Firewall URL even if AWS CodeArtifact rejected the request. To check whether Package Firewall blocked the package, see View Package Firewall logs.
The connection test failed. The OIDC provider URL or audience is wrong, the trust policy doesn’t match the audience or namespace, or the IAM role is missing sts:GetServiceBearerToken, codeartifact:GetAuthorizationToken, or codeartifact:GetRepositoryEndpoint.
When you save the integration, the connection test doesn’t check the codeartifact:ReadFromRepository and codeartifact:DescribePackageVersion permissions. Ensure that the IAM role has both permissions.
The IAM role or trust policy changed after you saved the integration, or Package Firewall can’t reach the repository. It doesn’t fall back to the public registry.
The IAM role is missing codeartifact:ReadFromRepository, or the package manager client isn’t supported, such as pnpm, Bun, or Poetry.
The network blocks the repository host.
The IAM role is missing codeartifact:DescribePackageVersion, or the repository hasn’t imported the version yet. Retry after a few seconds. For RubyGems, a missing codeartifact:ReadFromRepository permission also stops the restricted license check.
Changes to the region or repository of an integration can take up to 30 minutes to apply.
The integration is configured as a package source in Package Firewall, and the error message names the ecosystems that use it. Select another package source for those ecosystems, then delete the integration.