> For the complete documentation index, see [llms.txt](https://docs.stepsecurity.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stepsecurity.io/packages/secure-registry/setup-guide.md).

# Setup Guide

The **Setup Guide** tab provides your credentials and step-by-step instructions to configure your package manager to proxy through Secure Registry. Once configured, the security controls set in the [Policy](/packages/secure-registry/policy.md) tab are applied to every request.

Use the **Registry** selector to choose an ecosystem (e.g **npm**). The credentials, the available integration paths, and the setup steps all change with the selected ecosystem.

{% hint style="info" %}
Maven, NuGet and Go are in **Beta**, indicated by a badge next to each in the **Registry** selector.
{% endhint %}

<figure><img src="/files/14vFl4PBiDMu7RSgCscQ" alt=""><figcaption></figcaption></figure>

### Your credentials

The Setup Guide displays the credentials your clients need to authenticate to Secure Registry:

* **Registry URL**: the Secure Registry endpoint to use as your upstream, which differs per ecosystem.
* **Username**: your tenant username.
* **API Key**: select **Primary** or **Secondary** from the dropdown and reveal or copy the key.

| Ecosystem | Registry URL                                  | Upstream registry                                                               |
| --------- | --------------------------------------------- | ------------------------------------------------------------------------------- |
| npm       | `https://registry.stepsecurity.io/javascript` | `https://registry.npmjs.org`                                                    |
| PyPI      | `https://registry.stepsecurity.io/python`     | `https://pypi.org` for metadata, `https://files.pythonhosted.org` for downloads |
| Maven     | `https://registry.stepsecurity.io/java`       | `https://repo1.maven.org/maven2`                                                |
| NuGet     | `https://registry.stepsecurity.io/dotnet`     | `https://api.nuget.org/v3/index.json`                                           |
| Go        | `https://registry.stepsecurity.io/go`         | `https://proxy.golang.org` for modules, `https://sum.golang.org` for checksums  |

See [Upstream registries](#upstream-registries) for what each of these means in practice.

{% hint style="info" %}
Primary and Secondary API keys are supported so you can rotate without downtime: issue the Secondary, switch clients over, then rotate the Primary.
{% endhint %}

### Upstream registries

Each Secure Registry endpoint proxies to one public registry: the same host your package client would contact directly if it were not configured to go through Secure Registry. Requests reach Secure Registry first, are evaluated against your Policy, and are then forwarded upstream if allowed.

Two ecosystems use more than one upstream host, because their default clients split metadata and downloads:

* **PyPI.** The client fetches package metadata from `pypi.org` and downloads the distribution files themselves from a separate host, `files.pythonhosted.org`. Secure Registry proxies both.
* **Go.** Module downloads are served from the module proxy at `proxy.golang.org`. Checksum verification is a separate lookup against the checksum database at `sum.golang.org`. Secure Registry proxies both, so you can leave `GOSUMDB` at its default and keep checksum verification switched on.

NuGet resolves everything from a single V3 service index, `https://api.nuget.org/v3/index.json`, so the client discovers the package content and metadata endpoints from that document rather than from separate configured URLs.

{% hint style="info" %}
**Egress allowlists.** When a client is configured to use Secure Registry, its outbound connections go to `registry.stepsecurity.io`, not to the upstream registries. The upstream connections are made by Secure Registry on your behalf. If you enforce an egress allowlist on CI runners or developer machines, `registry.stepsecurity.io` is the host to allow.
{% endhint %}

{% hint style="warning" %}
**npm is an exception worth knowing about.** npm metadata responses contain absolute tarball URLs that point at `registry.npmjs.org`. Unless Tarball URL Rewriting is enabled, the client will follow those URLs and download tarballs directly from the public npm registry, bypassing Secure Registry for the download itself. Enable Tarball URL Rewriting so downloads are routed through Secure Registry and appear in the Policy Evaluations log.
{% endhint %}

### Integration paths

Pick the path that matches how packages reach your environment, then follow the in-app instructions. Not every path is offered for every ecosystem.

| Integration path              | npm | PyPI        | Maven       | NuGet       | Go  |
| ----------------------------- | --- | ----------- | ----------- | ----------- | --- |
| **JFrog Artifactory**         | Yes | Yes         | Yes         | Yes         | Yes |
| **Google Artifact Registry**  | Yes | Yes         | Yes         | Not offered | No  |
| **Sonatype Nexus Repository** | Yes | Not offered | Yes         | Yes         | Yes |
| **AWS CodeArtifact**          | Yes | Not offered | Not offered | Not offered | No  |
| **Direct**                    | Yes | Yes         | Yes         | Yes         | Yes |

* **Artifact repository managers** (JFrog Artifactory, Google Artifact Registry, Sonatype Nexus Repository, AWS CodeArtifact): for teams that already proxy packages through a manager. Create a remote repository, set its upstream URL to your Secure Registry endpoint, and add your credentials as the repository authentication. Your existing configuration stays unchanged; only the remote repository's upstream points to Secure Registry.
* **Direct**: for teams without an artifact manager, configuring the package client to point at Secure Registry itself.

On the **Direct** path, a **Package manager** selector switches the instructions to match your client:

| Ecosystem | Package manager options            |
| --------- | ---------------------------------- |
| npm       | npm (`.npmrc`)                     |
| PyPI      | pip                                |
| Maven     | Maven, Gradle                      |
| NuGet     | .NET CLI, NuGet CLI, Visual Studio |
| Go        | Go toolchain (`GOPROXY`)           |

{% hint style="info" %}
**JFrog Artifactory authentication differs by ecosystem.** For PyPI and Maven, enable **Token Authentication** so the Authorization header is sent as Bearer rather than Basic. For NuGet, enable **Force Authentication** instead. Follow the in-app instructions for the ecosystem you are configuring rather than reusing a previous setup.
{% endhint %}

The diagram below shows the request flow for the JFrog Artifactory path. Your existing Artifactory configuration stays unchanged; only the remote repository's upstream points to Secure Registry, where policy validation runs before requests reach the public npm registry. Each request is recorded in the Policy Evaluations log, attributed to the developer machine or CI job that made it.

<figure><img src="/files/Oy5SRTeW1SyXypvaz0hh" alt=""><figcaption></figcaption></figure>

After configuring, use the test sequence in the Setup Guide to confirm requests are flowing through Secure Registry.

### Setting up source attribution

Source attribution lets you trace each request in the [Policy Evaluations](/packages/secure-registry/policy-evaluations.md) log back to the developer machine or CI pipeline that made it. It is configured by appending an identifier suffix to your API key in the auth token. Attribution is optional: clients without a suffix still work, but their requests appear in the log without a source.

The token format is the API key, followed by `::`, followed by the identifier:

```
<your-api-key>::<IDENTIFIER>
```

#### Developer machines

To attribute requests to a developer machine, append the device serial ID using the `dev:` prefix:

```
npm config set //registry.stepsecurity.io/javascript/:_authToken "<your-api-key>::dev:<DEVICE-SERIAL-ID>"
```

In the Policy Evaluations log, these requests show a **Developer Machine** source, and the Source Identifier links to that device's page.

#### CI/CD pipelines (GitHub Actions)

To attribute requests to a specific pipeline run, store the API key as a secret and append a `gha:` identifier built from the workflow context. Store the key as a secret (for example, `STEPSECURITY_NPM_TOKEN`) rather than committing it:

```yaml
- name: Configure npm registry
  env:
    IDENTIFIER: "gha:${{ github.repository }}/${{ github.run_id }}/${{ job.check_run_id }}"
    NPM_TOKEN: ${{ secrets.STEPSECURITY_NPM_TOKEN }}
  run: |
    npm config set registry https://registry.stepsecurity.io/javascript
    npm config set //registry.stepsecurity.io/javascript/:_authToken "${NPM_TOKEN}::${IDENTIFIER}"

- name: Install dependencies
  run: npm ci
```

In the Policy Evaluations log, these requests show a **GitHub Actions** source, and the Source Identifier links to the corresponding Harden-Runner workflow run.

{% hint style="warning" %}
Never commit the raw API key. Use an environment variable or CI secret, as shown above.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.stepsecurity.io/packages/secure-registry/setup-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.