--- updatedAt: 2026-10-05T04:45:38.000Z agentTools: siteIndex: https://docs.jfrog.com/llms.txt projectIndex: https://docs.jfrog.com/security/llms.txt --- # PTC Quick Start Set up Package Traffic Controller (PTC) for a first pilot: Artifactory, workstations, and security edge redirect rules. This Quick Start gets PTC running end-to-end in three ordered phases: configure Artifactory, prepare workstations, then activate your security edge redirect rules. For prerequisites, exhaustive options, and per-vendor portal steps, follow the inline links and [Where to Go When You Need More Detail](#where-to-go-when-you-need-more-detail). For background on what PTC does and how it integrates with your security edge, see the [Package Traffic Controller (PTC) overview](/security/docs/package-traffic-controller). *** ## Required Components PTC deployment involves the following three components. Each must be configured correctly for the integration to work end to end. | Component | Who owns it | What it needs | | ------------- | ----------------------- | ----------------------------------------------------------------------------------------------------- | | Artifactory | JFrog admin | Remote repo per package type, Package Reroute API mapped | | Workstations | IT / endpoint team | Traffic forwarded to your security edge, security edge CA cert trusted by each package manager | | Security edge | Network / security team | Rule to intercept the registry hostnames and redirect them to Artifactory (objects differ per vendor) |
*** ## The Setup, Step by Step **To deploy PTC end to end:** ### Step 1: Configure Artifactory > **Note:** Curation must be enabled in Artifactory before you call the Package Reroute API. The API auto-enrolls the target remote repository in Curation by default (`linked_curation: true`); send `linked_curation: false` to skip Curation enrollment. For each package type you want to govern (npm, PyPI, Docker, Hugging Face, RubyGems, Cargo, Maven, Go): **1. Create a remote repository** pointing at the public registry. * Example: an npm remote called `npm-remote-registry` with upstream URL `https://registry.npmjs.org`. For detailed steps, see [Step 1: Create a Remote Repository](/security/docs/configure-artifactory#step-1-create-a-remote-repository). **2. Make sure JFrog Curation is enabled** in your Artifactory instance. The Package Reroute API in the next sub-step auto-enrolls the repository in Curation by default. See [Configure JFrog Curation](/security/docs/configure-curation). **3. Register the repo with Package Reroute** using the Update Registry Configuration API (`PUT /artifactory/api/package-reroute/config/{type}`). See [Package Reroute Config API](/security/reference/package-reroute-config): ```shell curl -X PUT "https:///artifactory/api/package-reroute/config/npm" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"repo_key": "npm-remote-registry"}' ``` Repeat for each ecosystem, replacing `npm` with `pypi`, `docker`, `huggingfaceml`, `gems`, `cargo`, `maven`, or `go`. This call is mandatory; PTC does not work without it. See [Step 3: Register Repositories with Package Reroute](/security/docs/configure-artifactory#step-3-register-repositories-with-package-reroute-mandatory). **4. Smoke test the redirect endpoint** before touching your security edge: ```shell curl -v "https:///artifactory/api/package-reroute?url=https%3A%2F%2Fregistry.npmjs.org%2Fexpress" ``` You should see an HTTP 302 or 307 response with a `Location` header pointing at your Artifactory repo path. If you do, Artifactory is ready. See [Step 4: Verify the Redirect Endpoint](/security/docs/configure-artifactory#step-4-verify-the-redirect-endpoint). *** ### Step 2: Prepare Workstations Each developer machine needs two things: 1. A way to route its traffic to your SASE provider, usually a SASE provider's client/forwarder on the workstation. See your SASE provider's guide in [Supported Security Edges](/security/docs/package-traffic-controller#supported-security-edges) for the vendor-specific client. 2. The security edge CA certificate trusted by every package manager that will be intercepted (npm, pip, Docker, and so on). **Open-source installation scripts available** The [package-reroute repository](https://github.com/jfrog/package-reroute/tree/main) ships ready-to-use scripts that automate CA certificate installation and environment variable setup across macOS, Windows, and Linux for npm, pip, and other clients. Adapt them to your environment before broad rollout. The CA must be added to application-specific trust stores or environment variables where applicable. The PTC repository ships [installation scripts](/security/docs/configure-workstation#installation-script) that automate this; adapt them to your environment. You can distribute the cert via MDM (Intune, Jamf), an imaging script, or manually. MDM is optional. For trust store requirements per client and OS, see [Configure Workstation for PTC](/security/docs/configure-workstation). Use this procedure to verify PTC is working on a single workstation before running the full installation script. It covers npm only and takes under five minutes. **Before you start:** - Your SASE client must already be configured and running on your machine. - Artifactory must already be configured for PTC (the Package Reroute API must be set up with an npm remote repository). - npm must be installed. ### Step A — Export the SASE CA Certificate Your SASE client installs its CA certificate into your OS trust store when it connects. This step extracts it into a file that npm can read. **macOS — run this in Terminal:** ```shell security find-certificate -a -p \ /System/Library/Keychains/SystemRootCertificates.keychain \ /Library/Keychains/System.keychain \ > ~/package-route.pem ``` This exports all trusted root CAs (including your SASE provider's CA) into a single file at `~/package-route.pem`. No sudo needed. **Verify Step A succeeded:** Check the file exists and has content: ```shell grep -c 'BEGIN CERTIFICATE' ~/package-route.pem ``` You should see a number around 100–150. If you get 0 or a "no such file" error, Step A failed. Check your SASE CA is in the bundle: ```shell openssl crl2pkcs7 -nocrl -certfile ~/package-route.pem | \ openssl pkcs7 -print_certs -noout | \ grep -i "zscaler\|netskope\|cloudflare" ``` You should see at least one line with your SASE provider's name. If you get no output, your SASE client may not be connected — check that it shows as active, then re-run Step A. **Linux** — your SASE admin must provide the CA certificate as a `.pem` file. Use that file path wherever `~/package-route.pem` appears below. **Windows — run this in PowerShell (no administrator needed):** First, find your SASE certificate in the Windows cert store (replace `Zscaler` with your SASE provider name): ```powershell Get-ChildItem Cert:\LocalMachine\Root | Where-Object { $_.Subject -like "*Zscaler*" } | Select-Object Subject, Thumbprint ``` You should see one result. If you see none, try `-like "*Netskope*"` or `-like "*Cloudflare*"`, or ask your IT team what name the certificate is registered under. Then export that certificate to a PEM file: ```powershell $cert = Get-ChildItem Cert:\LocalMachine\Root | Where-Object { $_.Subject -like "*Zscaler*" } | Select-Object -First 1 ("-----BEGIN CERTIFICATE-----`n" + [Convert]::ToBase64String($cert.RawData, 'InsertLineBreaks') + "`n-----END CERTIFICATE-----") | Set-Content "$env:USERPROFILE\package-route.pem" -Encoding utf8 ``` This creates the file at `C:\Users\\package-route.pem`. --- ### Step B — Tell npm to Trust the Certificate Set the `NODE_EXTRA_CA_CERTS` environment variable in your current terminal session. This does not change any permanent settings on your machine. **macOS / Linux:** ```shell export NODE_EXTRA_CA_CERTS=~/package-route.pem ``` **Windows (PowerShell):** ```powershell $env:NODE_EXTRA_CA_CERTS = "$env:USERPROFILE\package-route.pem" ``` --- ### Step C — Confirm the SASE Redirect Rule Is Active Ask your SASE admin to confirm that the redirect rule for `registry.npmjs.org` is enabled and scoped to your machine. If it is not set up yet, point them to the relevant SASE provider guide in [Supported Security Edges](/security/docs/package-traffic-controller#supported-security-edges). > **Important:** Do this after Step B. If the redirect rule is active before your workstation is configured, npm will fail with an SSL error. --- ### Step D — Run a Test Install In the same terminal window, run: ```shell npm install express --loglevel verbose ``` The install should complete normally. If it fails with an SSL error, see the troubleshooting notes below. --- ### Step E — Confirm the Request Went Through PTC In the verbose output, look for GET requests going to your Artifactory hostname instead of `registry.npmjs.org`: ``` npm http fetch GET 200 https:///artifactory/api/npm//express 350ms ``` If you see your Artifactory hostname, PTC is working — the SASE provider intercepted the request and rerouted it through Artifactory. --- ### Troubleshooting **SSL error during npm install** The certificate file is not being picked up. Check: 1. The env var is set in this terminal: run `echo $NODE_EXTRA_CA_CERTS` (macOS/Linux) or `$env:NODE_EXTRA_CA_CERTS` (Windows). It must show the path to `package-route.pem`. 2. The file exists and is not empty: run `ls -lh ~/package-route.pem` (macOS/Linux) or `Get-Item "$env:USERPROFILE\package-route.pem"` (Windows). 3. On macOS, if the file is empty, your SASE client may not be connected. Check that it shows as connected and re-run Step A. **Artifactory hostname not appearing in verbose output** The request was not rerouted. Check: 1. Your SASE client is connected and signed in. 2. The SASE redirect rule is active and covers `registry.npmjs.org` (see Step C). 3. The redirect rule is scoped to include your machine or group. 4. Artifactory has been configured with the npm repo via the Package Reroute Config API. **The npm install was rerouted but Curation blocked the package** This is expected behavior when a Curation policy violation is detected. Check your Curation policy in Artifactory under **Curation > Audit** to understand why the package was blocked. *** ### Step 3: Activate Security Edge Redirect Rules Configure your security edge to intercept the public-registry hostnames in scope and redirect them to your Artifactory `/artifactory/api/package-reroute` endpoint. The exact objects differ per vendor. Follow the guide for your security edge: * **Zscaler ZIA**: URL category + SSL inspection rule + URL filtering redirect rule. See [Configure Zscaler ZIA](/security/docs/configure-zscaler-zia). * **Netskope**: destination profiles + HTTP header profiles + real-time protection policies (Allow for browsers, Redirect for package-manager traffic). See [Configure Netskope](/security/docs/configure-netskope). * **Cloudflare Gateway**: TLS inspection + firewall redirect policies. See [Configure Cloudflare Gateway](/security/docs/configure-cloudflare). For a security edge without a published guide on this page, follow [Other Compatible Security Edges](/security/docs/package-traffic-controller#other-compatible-security-edges). The edge requires: * **URL category:** Match only the registry hostnames in scope. * **SSL inspection:** Decrypt that HTTPS traffic so the redirect can be applied. * **HTTP 307 redirect:** Return HTTP 307 for GET and HEAD to `https:///artifactory/api/package-reroute?url=`. Keep POST off the redirect rule. Commands such as `npm audit` fail when POST is redirected. If the edge also inspects traffic to Artifactory, you exclude the Artifactory hostname from the redirect rule so redirected traffic isn't intercepted again. Save and activate. Allow a few minutes for the policy to propagate. For the full per-vendor steps, see your SASE provider's guide in [Supported Security Edges](/security/docs/package-traffic-controller#supported-security-edges). *** ## Verify End-to-End On a workstation with the security edge client running and all rules active: ```shell npm install express --loglevel verbose ``` In the verbose log, look for HTTP GET lines pointing at your Artifactory hostname (for example, `acme.jfrog.io`) rather than `registry.npmjs.org` — that confirms the redirect. Then confirm the `express` package appears in your remote repo's cached artifacts, and (if Curation is enabled) an Approved entry appears under **Curation > Audit**. *** ## Setup Checklist Confirm these items are in place before enabling redirect rules for a pilot group. ☐ Remote repo per package type
☐ Remote repo per package type
☐ Package Reroute API mapped
☐ `/artifactory/api/package-reroute` returns 302/307
☐ JFrog Curation enabled in Artifactory (auto-enrolled per repo by the API; opt out with `linked_curation: false`) ☐ Traffic forwarded to your security edge
☐ Security edge CA trusted in OS and application trust stores ☐ Registry hostnames to intercept defined
☐ Traffic inspection/decryption enabled
☐ Redirect rule to `/artifactory/api/package-reroute`
☐ Request methods configured per ecosystem
☐ Artifactory host excluded from redirect (if you also inspect Artifactory traffic)
☐ Rules scoped to pilot group first *** ## Common Misconfigurations to Avoid 1. **Activating redirect rules before Artifactory is ready** — installs fail until Artifactory is fully configured. Sequence Artifactory first; see [Deployment Sequence](/security/docs/deployment-and-rollout#deployment-sequence). 2. **Redirecting Artifactory's own traffic** — if your security edge also inspects Artifactory traffic, exclude the Artifactory host from the redirect rule to avoid a loop. 3. **Skipping the Package Reroute API call** — creating the remote repo alone is not enough; the API mapping is mandatory. 4. **Redirecting the wrong HTTP methods** — causes commands like `npm audit` to fail. Use the per-ecosystem method tables. 5. **Going org-wide on day one** — roll out gradually using your security edge group controls. *** ## Where to Go When You Need More Detail | Topic | Page | | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | Deployment order and phased rollout | [Deploy and Roll Out PTC](/security/docs/deployment-and-rollout) | | Prerequisites and installation scripts | [Prerequisites and Installation Script](/security/docs/prerequisites-and-installation-script) | | Artifactory configuration (all steps) | [Configure Artifactory for PTC](/security/docs/configure-artifactory) | | Package Reroute Config API reference | [Package Reroute Config API](/security/reference/package-reroute-config) | | SASE provider portal steps (choose your vendor) | [Supported Security Edges](/security/docs/package-traffic-controller#supported-security-edges) | | Per-ecosystem setup (npm, PyPI, Docker, Hugging Face) | [Configuration by Package Type](/security/docs/configuration-by-package-type) | | Known limitations and troubleshooting | [Limitations and Troubleshooting](/security/docs/limitations-and-troubleshooting) | ## Related Topics * [Package Traffic Controller (PTC) overview](/security/docs/package-traffic-controller) * [Configure Artifactory for PTC](/security/docs/configure-artifactory) * [Supported Security Edges](/security/docs/package-traffic-controller#supported-security-edges) * [Configuration by Package Type](/security/docs/configuration-by-package-type) * [Limitations and Troubleshooting](/security/docs/limitations-and-troubleshooting)