PTC Quick Start

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.

For background on what PTC does and how it integrates with your security edge, see the Package Traffic Controller (PTC) overview.

Required Components

PTC deployment involves the following three components. Each must be configured correctly for the integration to work end to end.

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):

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.

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.

3. Register the repo with Package Reroute using the Update Registry Configuration API:

curl -X PUT "https://<YOUR_ARTIFACTORY_URL>/artifactory/api/package-reroute/config/npm" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"repo_key": "npm-remote-registry"}'

Repeat for each ecosystem, replacing npm with pypi, docker, huggingfaceml, gems, or cargo. This call is mandatory; PTC does not work without it. See Step 3: Register Repositories with Package Reroute.

4. Smoke test the redirect endpoint before touching your security edge:

curl -v "https://<YOUR_ARTIFACTORY_URL>/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.

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 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).

The CA must be added to application-specific trust stores or environment variables where applicable. The PTC repository ships installation scripts 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 find-certificate -a -p \
    /System/Library/Keychains/SystemRootCertificates.keychain \
    /Library/Keychains/System.keychain \
    > ~/package-route.pem

grep -c 'BEGIN CERTIFICATE' ~/package-route.pem

openssl crl2pkcs7 -nocrl -certfile ~/package-route.pem | \
  openssl pkcs7 -print_certs -noout | \
  grep -i "zscaler\|netskope\|cloudflare"

Get-ChildItem Cert:\LocalMachine\Root |
  Where-Object { $_.Subject -like "*Zscaler*" } |
  Select-Object Subject, Thumbprint

$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

export NODE_EXTRA_CA_CERTS=~/package-route.pem

$env:NODE_EXTRA_CA_CERTS = "$env:USERPROFILE\package-route.pem"

npm install express --loglevel verbose

npm http fetch GET 200 https://<your-artifactory>/artifactory/api/npm/<repo-key>/express 350ms

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.
• Netskope: destination profiles + HTTP header profiles + real-time protection policies (Allow for browsers, Redirect for package-manager traffic). See Configure Netskope.
• Cloudflare Gateway: TLS inspection + firewall redirect policies. See Configure Cloudflare Gateway.

General guidance that applies to any security edge:

• Match only the registry hostnames in scope (per ecosystem).
• Inspect or decrypt that traffic so the redirect can be applied.
• Redirect matching requests to https://<YOUR_ARTIFACTORY_URL>/artifactory/api/package-reroute.
• Configure request methods per ecosystem. Keep POST off where it would cause commands like npm audit to fail.
• If your security edge also inspects traffic to Artifactory, exclude the Artifactory host from the redirect rule so redirected traffic is not re-intercepted (avoids a loop). Inspecting Artifactory traffic itself is fine if you want it.

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.

Verify End-to-End

On a workstation with the security edge client running and all rules active:

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.

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.
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

Related Topics

• Package Traffic Controller (PTC) overview
• Configure Artifactory for PTC
• Supported Security Edges
• Configuration by Package Type
• Limitations and Troubleshooting