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

# Private Registries

> Connect your private container and package registries once, then scan images and resolve dependencies without re-entering credentials.

## Overview

A **registry connection** stores one set of credentials for a private registry at the
organization level so ZeroPath can reach it whenever it needs to — without you pasting a
token into every scan. Connect once, ZeroPath validates the credentials live before saving,
and every later scan reuses the stored connection.

There are two kinds of connection, managed from the same place:

<Columns cols={2}>
  <Card title="Container registries" icon="box">
    Let [Container Scanning](/docs/scanning/container-scanning) pull and scan images from a private
    registry — Docker Hub, GHCR, ECR, GAR, ACR, Artifactory, or any OCI registry.
  </Card>

  <Card title="Package registries" icon="cubes">
    Let [dependency analysis](/docs/sca/overview) resolve internal **npm** and **Maven** packages
    hosted on a private registry (Artifactory, Nexus, and the like), so private transitive
    dependencies stop showing up as coverage gaps.
  </Card>
</Columns>

<Info>
  **How credentials are handled.** Secrets are encrypted at rest (AES-256-GCM) and decrypted
  exactly once, at the point of use. They are never returned by any API, never written to logs,
  and never included in error messages. Creating a connection runs a live probe against the
  registry first — nothing is stored if the credentials or host fail validation.
</Info>

## Prerequisites

* The **Create Integrations** permission to open the **Manage Registries** dialog and to create,
  edit, or delete a connection. Using an existing **container** connection from the **Scan image**
  dialog's Connected registry picker needs only organization membership, so developers who should
  not handle raw credentials can still scan with a saved connection.
* The registry must be **reachable from ZeroPath over the public internet**. Hosts that resolve
  to private or loopback addresses are rejected when the connection is created. That includes
  registries inside a VPC or behind a firewall ZeroPath cannot traverse. ZeroPath does not ship a
  customer-side relay or broker.
* Where the provider supports it, use **read-only scopes** and a dedicated token or
  service account rather than a personal password.

## Open the Registries manager

<Steps>
  <Step title="Go to Integrations">
    Open [Settings → Integrations](https://zeropath.com/app/settings/integrations).
  </Step>

  <Step title="Add the Registries integration">
    Click **Add Integration** and choose **Registries** (described as *"Connect container and
    npm/Maven package registries for scanning"*).
  </Step>

  <Step title="Manage connections">
    The **Manage Registries** dialog has two sections — **Container registries** and
    **Package registries** — where you add, edit, and delete connections.
  </Step>
</Steps>

## Container registries

Container connections let a scan pull a private image without inline credentials. Each provider
collects the credentials it needs to list and pull:

| Provider                             | What you provide                                                                                                          |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| **Docker Hub**                       | Username, a read-only access token, and the namespace to browse                                                           |
| **GitHub Container Registry (GHCR)** | The GitHub username that owns the token, the org whose packages you browse, and a classic PAT with `read:packages`        |
| **Amazon ECR**                       | AWS account ID, region, and a least-privilege access key / secret pair                                                    |
| **Google Artifact Registry (GAR)**   | The `{location}-docker.pkg.dev` host, GCP project ID, and a service-account JSON key with `roles/artifactregistry.reader` |
| **Azure Container Registry (ACR)**   | The login server plus a repository-scoped token or a service principal                                                    |
| **JFrog Artifactory**                | The base host, a username, and an identity token                                                                          |
| **Generic OCI registry**             | Any OCI-compliant registry (Harbor, Quay, GitLab, `registry:2`): host, username, and a token or password                  |

For AWS and Google, static keys are never used to pull directly — ZeroPath exchanges them for a
short-lived pull token per scan (ECR authorization tokens last 12 hours; GAR access tokens last
60 minutes) and never persists the minted token.

<Note>
  Full per-provider credential instructions, the scan-dialog **Connected registry** mode, and the
  API/CLI ways to reference a connection live on the
  [Container Scanning](/docs/scanning/container-scanning#connect-a-registry) page. Connect the registry
  here, then scan from there.
</Note>

## Package registries

If your npm or Maven builds pull internal packages from a private registry, dependency analysis
cannot resolve those packages without credentials — their transitive dependencies stay invisible
and surface as [coverage](/docs/sca/coverage) gaps. A package-registry connection gives the resolver
the credentials it needs so private packages resolve alongside public ones.

<Info>
  Point ZeroPath at a **virtual / group repository that also proxies the public upstream** (for
  example an Artifactory npm-virtual or a Maven group repo), not at a private-only repository.
  The resolver uses the one connected URL for the whole ecosystem, so it must serve both your
  internal packages and their public dependencies.
</Info>

**Scope:** one connection per ecosystem per organization — at most one npm connection and one
Maven connection. npm and Maven are the only supported ecosystems today.

### Fields

<AccordionGroup>
  <Accordion title="npm">
    * **Registry URL** — the full base URL, e.g.
      `https://mycorp.jfrog.io/artifactory/api/npm/npm-virtual/`. A trailing slash is optional.
      Must be `https`, and must not contain a newline, `#`, or `;` (those characters would corrupt
      the generated npm config).
    * **Authentication** — **Basic** (username + password/token) or **Bearer token**.
    * **Username** — required for Basic auth only; omit it for Bearer.
    * **Password / identity token** or **Bearer token** — the secret.

    At scan time ZeroPath generates a scoped `.npmrc` inside the resolver's manifest-only
    workspace pointing npm at your registry with the stored credentials. The secret is written to
    a private (`0600`) file and discarded when the scan finishes.
  </Accordion>

  <Accordion title="Maven">
    * **Registry URL** — the full base URL of your Maven repository, e.g.
      `https://mycorp.jfrog.io/artifactory/maven-virtual/`. Same `https` and
      no-`newline`/`#`/`;` rules as npm.
    * **Authentication** — **Basic** (username + password/token) or **Bearer token**.
    * **Username** — required for Basic auth only.
    * **Password / identity token** or **Bearer token** — the secret.

    ZeroPath threads these credentials through the engine's POM/BOM fetcher (parent chains and
    imported BOMs) and generates a `settings.xml` mirror so Maven resolution reaches your
    registry.

    <Warning>
      **Maven coverage is partial.** ZeroPath's own POM/BOM fetcher uses your credentials, but the
      Trivy-based Maven walk resolves remote POMs with a separate fetcher that does **not** use
      them. A package whose metadata exists **only** on your private registry (never on a public
      upstream) can still resolve incompletely. Pointing the connection at a virtual repo that
      proxies the public upstream keeps this to a minimum.
    </Warning>
  </Accordion>
</AccordionGroup>

### How it behaves

* **Automatic once connected.** There is nothing to enable per scan. The next dependency analysis
  for the organization picks up the connection and uses it to resolve that ecosystem.
* **No connection means no change.** With no package-registry connection present, resolution is
  byte-for-byte identical to before — the feature is fully config-gated.
* **Bad configuration fails loudly.** If a stored connection cannot be used — the host became
  unreachable or private, the secret cannot be decrypted, or the URL is malformed — the scan
  fails with an actionable, secret-free message rather than silently falling back to an anonymous
  (and incomplete) resolution.

## Managing connections

* **Edit** — update the URL, auth mode, username, or secret. Leave the secret field blank to keep
  the stored one. Switching between **Basic** and **Bearer** auth requires re-entering the secret.
* **Delete** — remove the connection. Container scans then need inline credentials again, and
  affected package resolution reverts to public-only. A container registry connection cannot be
  deleted while container images still reference it — the platform reports which images are
  blocking the deletion (up to ten) so you can remove or reassign them first.

<Note>
  Opening the **Manage Registries** dialog requires the **Create Integrations** permission; without
  it, the dialog fails to load. Members without the permission can still pick an existing container
  connection from the **Scan image** dialog using organization membership alone.
</Note>

## Not included in this version

These are deliberate v1 boundaries, not bugs:

* **No auto-import or sync policies.** You choose which images to scan and monitor; there is no
  rule that imports every new tag automatically. Recurring container re-scans use each image's
  [monitoring schedule](/docs/scanning/container-scanning) instead.
* **No ECR cross-account role assumption.** Container ECR connections use static access keys.
* **No customer-side relay/broker.** The registry must be reachable from ZeroPath's egress.
* **Package registries cover npm and Maven only.** Other ecosystems are not accepted yet.
* **No push-triggered scans.** Monitoring polls on a schedule rather than reacting to a registry push.