> ## Documentation Index
> Fetch the complete documentation index at: https://docs.endorlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Package Firewall with AWS CodeArtifact

> Use an AWS CodeArtifact repository as the Package Firewall package source for Maven, npm, PyPI, and RubyGems.

You can use an AWS CodeArtifact repository as a package source for Package Firewall. Package Firewall evaluates each package request against your [policy](https://docs.endorlabs.com/package-firewall/policy.md) 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.


&#x20; flowchart LR
&#x20;   PMC\[Package manager client]
&#x20;   PF\[Package Firewall]
&#x20;   CA\[AWS CodeArtifact]
&#x20;   PUB\[Public registry]
&#x20;   PMC --> PF
&#x20;   PF --> CA
&#x20;   CA --> PUB
&#x20;&#x20;

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](https://docs.endorlabs.com/package-firewall/direct-integration.md#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](https://docs.aws.amazon.com/codeartifact/latest/ug/external-connection.html).

### 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](https://docs.endorlabs.com/integrations/package-managers/aws-codeartifact.md#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](https://docs.aws.amazon.com/codeartifact/latest/ug/auth-and-access-control-permissions-reference.html) and [AWS CodeArtifact authentication and tokens](https://docs.aws.amazon.com/codeartifact/latest/ug/tokens-authentication.html#get-auth-token-permissions).

The AWS managed policy [`AWSCodeArtifactReadOnlyAccess`](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSCodeArtifactReadOnlyAccess.html) 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.

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:GetServiceBearerToken",
      "Resource": "*",
      "Condition": {
        "StringEquals": { "sts:AWSServiceName": "codeartifact.amazonaws.com" }
      }
    },
    {
      "Effect": "Allow",
      "Action": "codeartifact:GetAuthorizationToken",
      "Resource": "arn:aws:codeartifact:<region>:<account-id>:domain/<domain>"
    },
    {
      "Effect": "Allow",
      "Action": [
        "codeartifact:GetRepositoryEndpoint",
        "codeartifact:ReadFromRepository"
      ],
      "Resource": "arn:aws:codeartifact:<region>:<account-id>:repository/<domain>/<repository>"
    },
    {
      "Effect": "Allow",
      "Action": "codeartifact:DescribePackageVersion",
      "Resource": "arn:aws:codeartifact:<region>:<account-id>:package/<domain>/<repository>/*"
    }
  ]
}
```

### Network access

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

```text theme={null}
<domain>-<account-id>.d.codeartifact.<region>.amazonaws.com
```

## 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](https://docs.endorlabs.com/integrations/package-managers/aws-codeartifact.md) 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](https://docs.endorlabs.com/package-firewall/policy.md#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](https://docs.endorlabs.com/package-firewall/direct-integration.md) or [MDM deployment](https://docs.endorlabs.com/package-firewall/mdm-deployment.md) 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](https://docs.endorlabs.com/package-firewall/direct-integration.md#verify-your-setup) for the command for each client, and [View Package Firewall logs](https://docs.endorlabs.com/package-firewall/logs.md) 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](https://docs.endorlabs.com/package-firewall/policy.md#action-when-a-policy-cannot-be-evaluated).

> [!WARNING]
>
> 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](https://docs.endorlabs.com/package-firewall/logs.md).

> [accordion] Why does the integration show as Unreachable?
>
> 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`.

> [accordion] Why does the connection test pass, but installations fail or packages can't be evaluated?
>
> 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.

> [accordion] Why does every installation for an ecosystem fail?
>
> 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.

> [accordion] Why does the download fail with `401` or `403` from an `amazonaws.com` host?
>
> The IAM role is missing `codeartifact:ReadFromRepository`, or the package manager client isn't supported, such as pnpm, Bun, or Poetry.

> [accordion] Why does the download time out or fail to connect to an `amazonaws.com` host?
>
> The network blocks the repository host.

> [accordion] Why can't Package Firewall evaluate a package?
>
> 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.

> [accordion] Why don't my changes to an integration take effect?
>
> Changes to the region or repository of an integration can take up to 30 minutes to apply.

> [accordion] Why can't I delete a package manager integration?
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.