Socket Registry Firewall

Enterprise-grade security proxy that protects package registries by scanning packages with Socket's security API in real-time to block malicious packages before they reach your systems.

Overview

Socket Registry Firewall runs as a Docker container that acts as a security-scanning registry proxy. Package managers are configured to use the firewall as their registry endpoint. The firewall intercepts all package requests, checks them against the Socket.dev security API, and blocks malicious packages before they can be installed.

Request Flow:

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

How it works:

1. Client requests package from firewall
2. Firewall extracts package name/version
3. Firewall checks Socket API for security issues
4. If safe → proxy to upstream and return package
5. If malicious → return 403 Forbidden with reason

Supported Ecosystems

Package registries support both metadata parsing and direct download protection. Hugging Face is scoped to model file downloads. See Hugging Face below.

Hugging Face

Hugging Face model downloads get malware and cooldown checks. The firewall inspects requests to /{namespace}/{model}/resolve/{revision}/{file} and resolves the revision to its commit SHA. Datasets, Spaces, and the Hub JSON API pass through without analysis. Hugging Face support requires Socket Firewall 2.0.10 or later.

Models without a Socket verdict yet are allowed by default. ecosystem_params.huggingface.allow_unknown has no effect, and fail_open_unscanned: false blocks models Socket has never seen but still allows models whose scan is pending.

Three requirements apply that the other registries do not have.

⚠️ Hugging Face requires path-based routing. Domain-based routing has no huggingface parser. A registries: block naming it is skipped with a config warning instead of a hard error, so no nginx site is generated and nothing is gated. If you are rolling the firewall out through split-horizon DNS, add a Hugging Face path route alongside that work rather than inside it.

path_routing:
  enabled: true
  domain: firewall.company.com
  routes:
    - path: /huggingface
      upstream: https://huggingface.co
      registry: huggingface

⚠️ Set the route's upstream to https://huggingface.co itself. Any other upstream, such as a Nexus or Artifactory Hugging Face proxy, adds a repository_url qualifier to the package URL the firewall looks up. Those lookups come back as pending scan, so known malware is allowed. A repository manager can sit in front of the firewall, but not between the firewall and Hugging Face.

Clients need both environment variables:

export HF_ENDPOINT=https://firewall.company.com/huggingface
export HF_HUB_DISABLE_XET=1

HF_ENDPOINT sends Hub requests through the firewall, which checks each /resolve/ request before serving it. A blocked model returns 403 whether or not Xet is enabled. HF_HUB_DISABLE_XET=1 turns off the Xet storage backend that recent huggingface_hub versions use by default. With Xet on, the client also requests a Xet access token from huggingface.co directly and pulls file content from Xet storage, traffic the firewall never sees. Setting HF_HUB_DISABLE_XET without HF_ENDPOINT sends every request straight to huggingface.co, so nothing is checked.

Deployment Topologies

Socket Registry Firewall supports three deployment topologies depending on where it sits in your package supply chain:

1. Downstream Deployment (Client-Facing)

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

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

Use when:

• You want to protect developer workstations and CI pipelines directly
• You control package manager configuration (registry URLs)
• You want to block malicious packages before they reach any machine
• You don't have a centralized registry mirror

Configuration:

# Default mode - generates API paths for clients
# No special config_mode needed
path_routing:
  enabled: true
  domain: firewall.company.com
  routes:
    - path: /npm
      upstream: https://registry.npmjs.org
      registry: npm

Client configuration:

npm config set registry https://firewall.company.com/npm/
pip config set global.index-url https://firewall.company.com/pypi/simple

See: Downstream Deployment Guide

2. Upstream Deployment (Registry-Facing)

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

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

Use 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
• Your mirror caches packages (most installs don't hit firewall after first fetch)

Configuration:

# Generates direct paths for registry-to-registry communication
config_mode: upstream
path_routing:
  enabled: true
  domain: socket-firewall.internal.company.com
  routes:
    - path: /npm
      upstream: https://registry.npmjs.org
      registry: npm
      mode: rewrite # Default - rewrites URLs for caching

Artifactory configuration:

# Point Artifactory remote repo to firewall
Remote URL: https://socket-firewall.internal.company.com/npm

See: Upstream Deployment Guide

3. Middle Deployment (Registry-to-Registry)

The firewall sits between two private registries (e.g., on-premise Artifactory → Production Artifactory). Both API and direct paths are generated, and URLs are passed through unchanged.

On-Premise Artifactory  --->  Socket Firewall  --->  Artifactory Production
      ^                                              ^
      |                                              |
  Virtual Repo                                 Remote Repo

Use when:

• You have multiple Artifactory/Nexus instances (On-Premise → Prod, Regional → Central)
• Downstream registry needs to resolve relative URLs
• You want to scan packages flowing between internal registries
• You need both metadata inspection and direct download protection

Configuration:

# Generates both API and direct paths with no URL rewriting
config_mode: middle
path_routing:
  enabled: true
  domain: socket-firewall.internal.company.com
  routes:
    - path: /pypi
      upstream: https://artifactory-prod.company.com/artifactory/api/pypi/pypi-remote
      registry: pypi
      mode: proxy # IMPORTANT - passes URLs unchanged

Key differences from upstream:

• mode: proxy - No URL rewriting (downstream registry resolves relative URLs)
• config_mode: middle - Generates both API and direct paths
• Supports Artifactory virtual repos aggregating remote repos

See: Artifactory Guide and Nexus Guide for details

Deployment Topology Comparison

Key Features

✅ Real-time Security - Blocks malicious packages before installation using Socket.dev's security API
✅ Multi-Ecosystem - Supports 9 major package ecosystems plus Hugging Face model downloads
✅ Flexible Topologies - Downstream, upstream, or middle deployments
✅ Flexible Routing - Domain-based or path-based routing
✅ Auto-Discovery - Sync routes from Artifactory/Nexus automatically
✅ High Performance - Intelligent caching with stale-while-revalidate (local or Redis)
✅ Enterprise Ready - Outbound proxy support, custom CAs, Splunk integration, webhook events
✅ Production Proven - Fail-open/closed modes, health checks, comprehensive logging

Routing Strategies

Path-Based Routing (Recommended)

All registries share a single domain with path prefixes. Requires only one DNS record and one SSL certificate.

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
    - path: /maven
      upstream: https://repo1.maven.org/maven2
      registry: maven
    - path: /huggingface
      upstream: https://huggingface.co
      registry: huggingface

Client usage:

npm config set registry https://firewall.company.com/npm/
pip config set global.index-url https://firewall.company.com/pypi/simple
export HF_ENDPOINT=https://firewall.company.com/huggingface
export HF_HUB_DISABLE_XET=1

Domain-Based Routing

Each registry gets its own subdomain. Requires multiple DNS records and certificates (or wildcard cert).

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

Client usage:

npm config set registry https://npm.company.com/
pip config set global.index-url https://pypi.company.com/simple

📝 Domain-based routing covers npm, PyPI, Maven, Cargo, RubyGems, OpenVSX, NuGet, Go, and Conda. Hugging Face is path-routing only. See Hugging Face.

Auto-Discovery (Artifactory/Nexus)

Automatically sync repository routes from your artifact manager. No manual route configuration needed!

path_routing:
  enabled: true
  domain: firewall.company.com
  mode: artifactory # or 'nexus'

  private_registry:
    api_url: https://artifactory.company.com/artifactory
    api_key: your-artifactory-api-key
    interval: 5m # Auto-sync every 5 minutes
    ignore_ssl_errors: false # Disable SSL cert verification (default: false)
    include_pattern: ".*" # Include all repos
    exclude_pattern: "(tmp|test)-.*" # Exclude temp/test repos

Routes update automatically when you add/remove repositories in Artifactory/Nexus!

See: Artifactory Guide | Nexus Guide for details

Caching Strategy

The firewall uses stale-while-revalidate caching to minimize API calls and ensure high performance:

• Fresh zone (default 600s): Cached results returned immediately
• Stale zone (up to 24h): Revalidate with Socket API, fallback to stale on error
• Redis support: For distributed deployments with multiple firewall instances

cache:
  ttl: 600 # Fresh window (10 minutes)

redis:
  enabled: true
  host: redis.company.com
  port: 6379
  ttl: 86400 # Stale window (24 hours)

Fail-Safe Behavior

Control what happens when the Socket API is unavailable:

socket:
  fail_open: true # Allow packages if API is down (default - prioritizes availability)
  # fail_open: false  # Block all packages if API is down (prioritizes security)

Recommendation: Use fail_open: true for development/CI environments, fail_open: false for production registries.

Getting Started

1. Installation Guide - Pre-built image or tarball installation
2. Choose your topology:
   • Downstream Deployment - Protect developers and CI directly
   • Upstream Deployment - Protect registry mirror ingestion
   • Artifactory Integration - Auto-discovery and configuration
   • Nexus Integration - Auto-discovery and configuration
3. Configuration Reference - Full config options, environment variables, SSL, Redis, Splunk

Common Use Cases

Use Case 1: Protect Developer Workstations

Topology: Downstream
Setup: Developers configure npm/pip/mvn to point at firewall
Benefit: Block malicious packages before they reach developer machines

See Downstream Guide →

Use Case 2: Centralized Protection with Artifactory

Topology: Upstream
Setup: Artifactory remote repos point to firewall
Benefit: Single enforcement point, no developer config changes

See Artifactory Guide →

Use Case 3: Nexus Repository Manager

Topology: Upstream
Setup: Nexus proxy repos point to firewall
Benefit: Protect package ingestion without client changes

See Nexus Guide →

Use Case 4: Multi-Tier Artifactory (On-Premise → Production)

Topology: Middle
Setup: On-premise Artifactory virtual repo → Firewall → Production Artifactory
Benefit: Scan packages flowing between internal registries

See Artifactory Guide - Middle Deployment →

Architecture

┌────────────────┐
│  Client / CI   │
└───────┬────────┘
        │
        v
┌────────────────────────────────┐
│   Socket Registry Firewall     │
│  ┌──────────────────────────┐  │
│  │  Package Parser (Lua)    │  │  Extract package name/version
│  └──────────┬───────────────┘  │
│             v                  │
│  ┌──────────────────────────┐  │
│  │  Socket Client (Lua)     │◄─┼─► Socket.dev API
│  │  + Redis Cache           │  │    (security check)
│  └──────────┬───────────────┘  │
│             v                  │
│  ┌──────────────────────────┐  │
│  │  Upstream Proxy (nginx)  │  │  Forward safe packages
│  └──────────┬───────────────┘  │
└─────────────┼──────────────────┘
              v
    ┌──────────────────┐
    │ Upstream Registry│
    │ (npmjs.org, etc.)│
    └──────────────────┘

Components:

• Package Parsers - Ecosystem-specific Lua modules that extract package identifiers from requests
• Socket Client - Communicates with Socket.dev API, manages caching
• Upstream Proxy - NGINX reverse proxy that forwards requests to upstream registries
• Config Tool - Generates NGINX configurations from socket.yml

Documentation

• Installation Guide - Pre-built Docker image and tarball installation
• Downstream Deployment - Protect developers and CI directly
• Upstream Deployment - Protect registry mirror ingestion
• Artifactory Integration - Auto-discovery, upstream/middle deployment
• Nexus Integration - Auto-discovery, upstream/middle deployment
• Configuration Reference - All config options, environment variables, SSL, Redis, Splunk

Support

• Documentation: https://docs.socket.dev
• Tarball Releases: https://github.com/SocketDev/socket-registry-firewall
• Email: [email protected]