@snyk/docker-registry-v2-client

OCI Distribution client library.

Specification

• Open Container Initiative Distribution Specification
• Docker Registry HTTP API V2 Specification

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 |

Options

Every public function accepts an options argument typed as ClientOptions. The shape is defined in src/options.ts and exported from the package.

Common fields:

• headers?: Record<string, string> — extra request headers, merged on top of library defaults.
• qs?: Record<string, string> — extra query string parameters.
• protocol?: string — override the URL scheme (e.g. "http:").
• hostMappings?: Array<[RegExp | string, string]> — rewrite the request host before sending.
• acceptManifest?: string (read by getManifest / getAttestationManifest), acceptLayer?: string (read by getLayer / downloadLayer) — override the Accept header for those calls.
• allowedHosts, disallowDangerousHosts, ssrfProtectionDryRun — see "Host Filtering" below.
• timeout, response_timeout, open_timeout, read_timeout — pass-through to the underlying needle HTTP client.

The library defensively deep-clones the options object at every public entry point. This means:

• Callers may safely share a single options object across concurrent calls; the library will not mutate it and concurrent calls do not interfere with each other through it.
• Callers may continue to mutate the options object after a call returns. Earlier calls have already taken their own copy.
• Library-internal fields (notably snykInternalOutputStream, used to stream layer downloads to a file) are not part of ClientOptions and cannot be set by callers — they are merged into the request config by the library after the caller's options.

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