Socket Firewall: Registry Mode Overview

Socket Firewall can be deployed in three modes: Wrapper, Proxy, and Registry. This document covers Registry Mode — the most transparent and infrastructure-native deployment model.

Deployment Modes Compared

Feature	Registry Mode	Wrapper Mode	Proxy Mode
How it works	Replaces registry URL in package manager config	CLI wraps package manager commands (`socket npm install`)	HTTP/HTTPS proxy intercepts traffic
Client changes	Point registry URL to firewall	Install Socket CLI on every machine	Configure proxy env vars (`HTTP_PROXY`)

Infrastructure	Docker container(s)	Per-machine CLI install	Proxy server + CA trust
Coverage	All package installs from configured registries	Only wrapped commands are protected	All traffic through proxy is inspected
Ecosystem support	npm, PyPI, Maven, Cargo, RubyGems, OpenVSX, NuGet, Go	npm, pip	npm, pip, maven, cargo, rubygems, nuget, go
Best for	Production infrastructure, CI/CD, private registries	Developer workstations, quick setup	Org-wide enforcement via network policy

What Is Registry Mode?

In Registry Mode, the Socket Firewall runs as a Docker container that acts as a security-scanning registry proxy. Package managers (npm, pip, mvn, cargo, etc.) are configured to use the firewall as their registry endpoint. The firewall:

Receives package requests from clients
Checks the package against the Socket.dev security API
If safe — proxies the request to the upstream registry and returns the package
If malicious — returns 403 Forbidden with a reason

Developer / CI
      |
      v
Socket Registry Firewall  --->  Socket.dev API (security check)
      |
      v
Upstream Registry (npmjs.org, pypi.org, etc.)

Registry Mode Deployment Topologies

Registry Mode supports two deployment topologies depending on where the firewall sits in your package supply chain:

Downstream Deployment

The firewall sits between developers/CI and the registry (public or private). This is the most common deployment.

Developer / CI  --->  Socket Firewall  --->  Public Registry (npmjs.org)
                                        --->  Private Mirror (Artifactory/Nexus)

Use this when:

You want to protect developer workstations and CI pipelines
You control package manager configuration (registry URLs)
You want to block malicious packages before they reach any machine

See: Downstream Deployment Guide

Upstream Deployment

The firewall sits between your private registry mirror and the public internet. The mirror pulls packages through the firewall.

Developer / CI  --->  Artifactory / Nexus  --->  Socket Firewall  --->  Public Registry

Use this when:

You already have a centralized Artifactory/Nexus instance
You don't want to change developer-side package manager configs
You want a single enforcement point for all package ingestion

See: Upstream Deployment Guide

Supported Registries

Registry	Ecosystem	Upstream URL
npm	JavaScript/Node.js	`registry.npmjs.org`
PyPI	Python	`pypi.org`
Maven	Java/Kotlin/Scala	`repo1.maven.org`
Cargo	Rust	`crates.io`
RubyGems	Ruby	`rubygems.org`
OpenVSX	VS Code Extensions	`open-vsx.org`
NuGet	.NET	`nuget.org`
Go	Go Modules	`proxy.golang.org`

Key Concepts

Routing Models

Registry Mode supports two routing strategies:

Domain-based routing — Each registry gets its own subdomain:

registries:
  npm:
    domains: [npm.company.com]
  pypi:
    domains: [pypi.company.com]

Path-based routing — All registries share a single domain with path prefixes:

path_routing:
  enabled: true
  domain: firewall.company.com
  routes:
    - { path: /npm, upstream: https://registry.npmjs.org, registry: npm }
    - { path: /pypi, upstream: https://pypi.org, registry: pypi }

Fail-Open vs Fail-Closed

Fail-open (default): If the Socket API is unavailable, packages are allowed through. Prioritizes availability.
Fail-closed: If the Socket API is unavailable, all packages are blocked. Prioritizes security.

socket:
  fail_open: true   # default

Caching

The firewall caches security scan results to minimize API calls and reduce latency. Supports local in-memory caching (default) and Redis for distributed deployments.

Next Steps

Downstream Deployment Guide — Protect developers and CI directly
Upstream Deployment Guide — Protect your registry mirror's ingestion
Configuration Reference — Full config options, env vars, SSL, Redis, Splunk