PTC Quick Start

A concise walkthrough of the steps needed to get Package Traffic Controller (PTC) working end-to-end. For exhaustive options, edge cases, and troubleshooting, follow the links in Where to Go When You Need More Detail.

What PTC Does

Developers and agents can install packages directly from public registries (registry.npmjs.org, pypi.org, Docker Hub, and so on), bypassing Artifactory and any policies you have configured in JFrog Curation.

PTC fixes that without changing how developers work.

It uses Zscaler to silently intercept those public-registry requests at the network layer and redirect them through your Artifactory instance. Developers keep running npm install, pip install, docker pull, and so on — but now every request flows through Artifactory, where Curation policies, caching, and audit logs apply.

The Three Pieces You Need

PTC coordinates three systems. If any one of them is not ready, package installs will break.

Order of Operations

The order matters. Enabling Zscaler redirect rules before Artifactory and workstation trust are ready causes every developer install to fail with SSL or HTTP errors.

The Setup, Step by Step

Step 1 — Configure Artifactory

Note: Curation must be enabled on the remote repository for policy enforcement to apply.

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. 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 type you enable — replace npm with pypi, docker, or huggingfaceml. The API validates that the repository exists before accepting the configuration. PTC does not work without this call. See Step 2: Register Repositories with Package Reroute.

3. Enable anonymous access on the remote repo.

Zscaler redirects traffic without user credentials. Artifactory must accept anonymous requests on the PTC remote. Grant the anonymous user Read + Deploy/Cache, scoped to the PTC remote only. See Step 4: Configure Anonymous Access.

4. Turn on JFrog Curation for the same remote repo.

• Navigate to Administration > Curation > Curated Repositories and enable Curation for the remote.
• Also enable the Compliant Version Selection (CVS) flag on the same remote, so Curation automatically serves the nearest compliant version when the requested version is blocked by policy.
• PTC works without Curation. Curation adds the governance layer on top.

See Step 3: Enable JFrog Curation.

5. Smoke test the redirect endpoint before touching Zscaler:

curl -v "https://<YOUR_ARTIFACTORY_URL>/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 5: Verify the Redirect Endpoint.

Step 2 — Prepare Workstations

Each developer machine needs two things:

1. Zscaler Client Connector (ZCC) installed and routing traffic through Zscaler.
2. The Zscaler 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 Prerequisites and Installation Script.

Step 3 — Activate Zscaler ZIA Rules

In the ZIA Admin Portal, configure the following in order:

1. A no-inspection rule for Artifactory traffic (do this first)

• Add a bypass (no SSL inspection) rule for your Artifactory hostname — for JFrog Cloud, typically *.jfrog.io; for self-hosted, your own DNS name.
• This prevents ZIA from re-intercepting traffic on its way from the workstation to Artifactory after the redirect, which would break the flow.

2. A custom URL Category — for example JFrog_Target_Registries

• Add the hostnames for every package ecosystem in scope. See Reference: Public Registry Hostnames for the full list.

3. An SSL Inspection rule

• Apply it to the URL category above. Action: Inspect.

4. A URL Filtering redirect rule

• URL Categories: the same category.
• Protocols: HTTPS only.
• Request Methods: configure per ecosystem — see the per-ecosystem tables.
• User Agent: set to Other.
• Action: Block, with Redirect URL: https://<YOUR_ARTIFACTORY_URL>/package-reroute.

Save and activate. Allow a few minutes for the policy to propagate.

For complete ZIA configuration steps, see Configure Zscaler ZIA.

Verify End-to-End

On a workstation with ZCC running and all rules active:

npm install express --loglevel verbose

In the verbose log, look for HTTP GET lines whose URL points at your Artifactory hostname (for example acme.jfrog.io) — not only at registry.npmjs.org. That confirms the client followed the redirect into Artifactory and the install should complete successfully.

Also verify:

1. Artifactory UI — navigate to your remote repo. The express package should appear in the cached artifacts.
2. Curation audit — navigate to Curation > Audit and confirm an Approved entry appears.

Roll Out Gradually

Note: Do not enable PTC org-wide on day one. Use Zscaler Groups to limit who is affected, and start with one ecosystem.

Within each phase, start with npm only, then add PyPI, Docker, and Hugging Face one at a time as each stabilizes.

For phased rollout guidance, see Gradual Rollout Recommendation.

Setup Checklist

Use this checklist before you enable ZIA redirect rules for a pilot group.

Top Mistakes to Avoid

1. Activating Zscaler rules before Artifactory is ready — every install breaks immediately.
2. Skipping the no-inspection bypass for Artifactory — causes a redirect loop back through ZIA.
3. Skipping the Package Reroute API call — creating the remote repo alone is not enough; the API mapping is mandatory.
4. Forgetting anonymous access — redirected requests arrive without user credentials.
5. Redirecting the wrong HTTP methods — breaks commands like npm audit. Use the per-ecosystem method tables.
6. Going org-wide on day one — roll out gradually using ZIA Groups.

Where to Go When You Need More Detail