Pull-Through Proxy

Stout can sit between your developers and upstream registries like npm, PyPI, Docker Hub, and more. Packages are fetched from upstream on first pull, scanned for vulnerabilities, checked against your policies, and cached locally. Packages that don't pass your gates are blocked before they reach anyone.

How It Works

First pull — Stout fetches the package from the upstream registry, runs vulnerability scanning, generates an SBOM, checks license compliance, and evaluates your gate policies.
Gate evaluation — If the package passes all policies, it's cached and served. If it fails, the pull is blocked and developers see a clear error with the reason.
Subsequent pulls — Served instantly from the local cache with no upstream dependency.

Configure Upstreams

Define upstream registries per format in your proxy configuration:

# proxy.yaml
upstreams:
  npm:
    url: https://registry.npmjs.org
    format: npm
  pypi:
    url: https://pypi.org
    format: pypi
  docker:
    url: https://registry-1.docker.io
    format: oci
  go:
    url: https://proxy.golang.org
    format: go

Set the PROXY_CONFIG environment variable to the path of your config file, or mount it at /etc/stout/proxy.yaml in Docker.

Configure Gate Policies

Gate policies control what packages are allowed through the proxy. You can set defaults and per-format overrides:

# gate-policy.yaml
policies:
  default:
    vulnerability:
      block_severity: critical    # block critical CVEs
      warn_severity: high         # warn on high CVEs
    license:
      deny: [AGPL-3.0, SSPL-1.0, BUSL-1.1]
      warn: [GPL-3.0]
    review:
      require: false              # don't require community reviews
    sbom:
      require: true               # generate SBOM for every package

  npm:
    vulnerability:
      block_severity: high        # stricter for npm
    review:
      require: true
      min_score: 3.0              # minimum review score to pass gate

  oci:
    vulnerability:
      block_severity: critical
    review:
      require: false

Policy Options

Policy	Options	Description
`vulnerability.block_severity`	`critical`, `high`, `medium`, `low`	Block packages with CVEs at or above this severity
`vulnerability.warn_severity`	`critical`, `high`, `medium`, `low`	Log warnings for CVEs at or above this severity
`license.deny`	List of SPDX IDs	Block packages with these licenses
`license.warn`	List of SPDX IDs	Log warnings for these licenses
`review.require`	`true` / `false`	Require community reviews before allowing through
`review.min_score`	`0.0` – `5.0`	Minimum aggregate review score to pass
`sbom.require`	`true` / `false`	Generate and attach SBOM for proxied packages

Client Configuration

Client configuration is transparent — point your package manager at Stout the same way you would for direct registry use. See the format-specific guides for details:

npm — set registry in .npmrc
pip — set index-url in pip.conf
Docker — docker login to your Stout instance
Go — set GOPROXY
Maven — add repository to pom.xml

When a package isn't found in the local registry, Stout automatically fetches it from the configured upstream, applies your gate policies, and serves it — or blocks it.

Monitoring

Every proxied package is recorded in the audit log with scan results, policy evaluation outcomes, and the requesting user. Use the admin API to review proxy activity:

curl -H "Authorization: Bearer $STOUT_TOKEN" \
  https://registry.stout.io/api/v1/admin/proxy/audit