npm package: @snyk/docker-registry-v2-client
Description: Docker Registry HTTP V2 API client
Author: snyk.io
Latest version: 2.24.4

# @snyk/docker-registry-v2-client

OCI Distribution client library.

## Specification

- [Open Container Initiative Distribution Specification](https://github.com/opencontainers/distribution-spec/blob/main/spec.md)
- [Docker Registry HTTP API V2 Specification](https://github.com/distribution/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md)

## API

| Function                           | OCI Distribution Specification endpoint | Description                                                                     |
| ---------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------- |
| checkSupport                       | `/v2/`                                  | Check whether or not the registry implements the OCI Distribution Specification |
| getRepos                           | `/v2/_catalog`                          | Fetches a list of repositories                                                  |
| getTags                            | `/v2/<name>/tags/list`                  | Fetches a list of tags                                                          |
| getManifest                        | `/v2/<name>/manifests/<reference>`      | Pulls a manifest for platform                                                   |
| getAttestationManifest             | `/v2/<name>/manifests/<reference>`      | Pulls a attestation manifest for platform                                       |
| getImageConfig                     | `/v2/<name>/blobs/<digest>`             | Pulls a blob with image config content type                                     |
| getImageSize                       | `/v2/<name>/blobs/<digest>`             | Calculates the size of an image                                                 |
| downloadLayer                      | `/v2/<name>/blobs/<digest>`             | Pulls a blob with layer content type                                            |
| getLayer                           | `/v2/<name>/blobs/<digest>`             | Pulls a blob with layer content type                                            |
| getAuthTokenForEndpoint(:endpoint) | `/v2/:endpoint`                         | Retrieves an authentication token for endpoint                                  |

## Tests

### Infrastructure

| Container Registry                            | How to access                                                                                                 |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Amazon Elastic Container Registry (ecr)       | 1Password: `Development > AWS Test Account - ECR`                                                             |
| Azure Container Registry (acr)                |                                                                                                               |
| Docker Hub (docker-hub)                       | [DockerHub](https://hub.docker.com/), then 1Password: `Development > Okta - team magma Docker Hub`            |
| Google Artifact Registry (google-artifact-cr) | [GCP Console Project `snyk-magma`](https://console.cloud.google.com/artifacts?project=snyk-magma)             |
| Google Container Registry (gcr)               | [GCP Console Project `snyk-magma`](https://console.cloud.google.com/gcr/images/snyk-magma?project=snyk-magma) |
| Quay Container Registry (quay-cr)             | 1Password: `Development > Quay - Team Magma`, then 1Password: `Development > Red Hat - Team Magma`            |

### Local

Set up your local env with the following env vars (see 1Password):

```console
export SNYK_DRA_ARTIFACTORY_PASSWORD=<See 1password: Development/DRA env>
export SNYK_DRA_ARTIFACTORY_REGISTRY_BASE=dockere2e.artifactory.dev.snyk.io
export SNYK_DRA_ARTIFACTORY_REPOSITORY=goof
export SNYK_DRA_ARTIFACTORY_STORAGE_API_BASE=artifactory.dev.snyk.io/artifactory/api/storage/dockere2e
export SNYK_DRA_ARTIFACTORY_USERNAME=snyk-e2e-test

export SNYK_DRA_AZURE_PASSWORD=<See 1password: Development/Azure Container Registry (ACR) - Docker Registry Agent>
export SNYK_DRA_AZURE_REGISTRY_BASE=snykgoof.azurecr.io
export SNYK_DRA_AZURE_USERNAME=snykgoof
export SNYK_DRA_AZURE_REPOSITORY=snykgoof/azure-goof

export SNYK_DRA_DOCKER_HUB_PASSWORD=<See 1password: Development/DockerHub - snykgoof user>
export SNYK_DRA_DOCKER_HUB_REGISTRY_BASE=registry-1.docker.io
export SNYK_DRA_DOCKER_HUB_REPOSITORY=snykgoof/dockerhub-goof
export SNYK_DRA_DOCKER_HUB_USERNAME=snykgoof

export SNYK_AGENT_ACCESS_KEY_ID="AKIAX2FLE4CDHRAFCLS4"
export SNYK_DRA_ELASTIC_REGION=eu-west-3
export SNYK_DRA_ELASTIC_REPOSITORY=amazon-goof
export SNYK_AGENT_SECRET_ACCESS_KEY=<See 1password: Development/Elastic Container Registry (ECR) - Docker Registry Agent (role based auth)

export SNYK_DRA_GOOGLE_PASSWORD='<See 1Password: Development/GCR Google Container Registry snyk-magma>'
export SNYK_DRA_GOOGLE_REGISTRY_BASE=gcr.io
export SNYK_DRA_GOOGLE_REPOSITORY=snyk-magma/google-goof
export SNYK_DRA_GOOGLE_USERNAME=_json_key

export SNYK_DRA_QUAY_PASSWORD=<See 1password: Development/Quay - Team Magma>
export SNYK_DRA_QUAY_REPOSITORY=snyk_magma/goof
export SNYK_DRA_QUAY_REGISTRY_BASE=quay.io
export SNYK_DRA_QUAY_USERNAME=snyk_magma

export SNYK_OCI_AZURE_REPOSITORY=snykgoof/oci-goof
export SNYK_OCI_DOCKER_HUB_REPOSITORY=snykgoof/oci-goof
export SNYK_OCI_MULTI_ARCH_DOCKER_HUB_REPOSITORY=snykgoof/nodejs18
```

To run the tests:

```console
$ npm run test
```

Open `coverage/index.html` in your web browser to view the coverage reports

## Linting and formatting

> Note: Linting tasks are also run as part of the test run. However, due to
> their execution speed, it can be useful to run them as you develop, to keep
> your code organized.

To run the code formatting tasks:

```console
$ npm run format
```

To run the linting tasks:

```console
$ npm run lint
```

## Host Filtering

Set the `allowedHosts: string[]` option to allow connections to only the specified hosts.
Set the `disallowDangerousHosts: boolean` option to disallow connections to hosts which are
IPs, are in the `.cluster.local` subdomain or do not have a TLD+1
(i.e. disallow `example` but allow `example.com`).

## Known limitations

### GitlabCR

There are known limitations with GitlabCR for listing registries/repositories.
The workaround for the below limitations is to ensure that the account that is
used to access these endpoints must be the administrator account. Please see
the bug reports.

- https://gitlab.com/gitlab-org/gitlab/-/issues/22635
- https://gitlab.com/gitlab-org/gitlab/-/issues/23696