- 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 aspublic: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 conditionsts:AWSServiceNameset tocodeartifact.amazonaws.com, to get a bearer token for AWS CodeArtifact.codeartifact:GetAuthorizationTokenon the domain to get an authorization token for the repository.codeartifact:GetRepositoryEndpointon the repository to get the repository URL.codeartifact:ReadFromRepositoryon the repository to read packages from the repository.codeartifact:DescribePackageVersionon the packages in the repository to read package version metadata, such as the publish time and license.
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:Configure the AWS CodeArtifact integration
Select the package source
Configure package manager clients
Verify your setup
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.
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.Why does the integration show as Unreachable?
Why does the integration show as Unreachable?
sts:GetServiceBearerToken, codeartifact:GetAuthorizationToken, or codeartifact:GetRepositoryEndpoint.Why does the connection test pass, but installations fail or packages can't be evaluated?
Why does the connection test pass, but installations fail or packages can't be evaluated?
codeartifact:ReadFromRepository and codeartifact:DescribePackageVersion permissions. Ensure that the IAM role has both permissions.Why does every installation for an ecosystem fail?
Why does every installation for an ecosystem fail?
Why does the download fail with 401 or 403 from an amazonaws.com host?
Why does the download fail with 401 or 403 from an amazonaws.com host?
codeartifact:ReadFromRepository, or the package manager client isn’t supported, such as pnpm, Bun, or Poetry.Why does the download time out or fail to connect to an amazonaws.com host?
Why does the download time out or fail to connect to an amazonaws.com host?
Why can't Package Firewall evaluate a package?
Why can't Package Firewall evaluate a package?
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.Why don't my changes to an integration take effect?
Why don't my changes to an integration take effect?
Why can't I delete a package manager integration?
Why can't I delete a package manager integration?