Configuration Reference

Complete reference for Socket Registry Firewall configuration options.

Configuration File (`socket.yml`)

The firewall reads configuration from /app/socket.yml inside the container. Mount your config file:

volumes:
  - ./socket.yml:/app/socket.yml:ro

Core Settings

socket:
  # Socket.dev API endpoint
  api_url: https://api.socket.dev

  # Behavior when Socket API is unreachable
  fail_open: true          # true = allow packages (default), false = block all

  # Corporate egress proxy
  outbound_proxy: http://proxy.company.com:3128
  no_proxy: localhost,127.0.0.1,internal.company.com

  # SSL verification for Socket API calls
  api_ssl_verify: true
  api_ssl_ca_cert: /path/to/corporate-ca.crt

Ports

ports:
  http: 8080    # HTTP port (redirects to HTTPS)
  https: 8443   # HTTPS port

Domain-Based Routing

Assign custom domains per registry. Each domain needs a DNS record pointing to the firewall.

registries:
  npm:
    domains: [npm.company.com]
  pypi:
    domains: [pypi.company.com]
  maven:
    domains: [maven.company.com]
  cargo:
    domains: [cargo.company.com]
  rubygems:
    domains: [rubygems.company.com]
  openvsx:
    domains: [vsx.company.com]
  nuget:
    domains: [nuget.company.com]
  go:
    domains: [go.company.com]

Path-Based Routing

All registries behind 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: /cargo
      upstream: https://index.crates.io
      registry: cargo
    - path: /rubygems
      upstream: https://rubygems.org
      registry: rubygems
    - path: /openvsx
      upstream: https://open-vsx.org
      registry: openvsx
    - path: /nuget
      upstream: https://api.nuget.org
      registry: nuget
    - path: /go
      upstream: https://proxy.golang.org
      registry: go

External Routes File

For 50+ routes, use an external file:

path_routing:
  enabled: true
  domain: firewall.company.com
  routes_file: /config/routes.yml

Auto-Discovery (Artifactory/Nexus)

Automatically sync routes from your artifact manager:

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              # Sync interval
    default_registry: maven   # Fallback for unknown repo types
    include_pattern: ".*"
    exclude_pattern: "(tmp|test)-.*"

Nginx Performance

nginx:
  worker_processes: 2        # Match to CPU cores
  worker_connections: 4096   # Concurrent connections per worker

Resource-Based Recommendations

Resources	worker_processes	worker_connections	Throughput
1 CPU / 1 GB	1	512	~30 req/s
2 CPU / 2 GB	2	1024	~60 req/s
4 CPU / 4 GB	4	4096	~100 req/s
8 CPU / 8 GB	8	8192	~170 req/s

Proxy Timeouts

proxy:
  connect_timeout: 60   # seconds
  send_timeout: 60
  read_timeout: 60

Redis Caching

For distributed / multi-instance deployments:

redis:
  enabled: true
  host: redis.company.com
  port: 6379
  password: your-redis-password
  ttl: 86400   # Cache TTL in seconds (24 hours)

Metadata Filtering

Remove blocked/warned packages from registry metadata responses:

metadata_filtering:
  enabled: true
  filter_blocked: true    # Remove blocked packages from metadata
  filter_warn: false      # Keep warned packages visible

Bulk PURL Lookup

Pre-cache security status for faster lookups:

bulk_purl_lookup:
  enabled: true
  batch_size: 5000

Splunk Integration

Forward security events to Splunk:

splunk:
  enabled: true
  hec_url: https://splunk.company.com:8088/services/collector/event
  hec_token: your-splunk-hec-token
  index: security
  source: socket-firewall

Environment Variables

All configuration can be overridden via environment variables:

# Core
SOCKET_SECURITY_API_TOKEN=your-api-key       # Required
SOCKET_API_URL=https://api.socket.dev        # Default
SOCKET_CACHE_TTL=600                         # Seconds, default: 600
SOCKET_FAIL_OPEN=true                        # Allow on API error

# Ports
HTTP_PORT=8080
HTTPS_PORT=8443

# Redis
REDIS_ENABLED=true
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=secret

# Proxy
SOCKET_OUTBOUND_PROXY=http://proxy:3128
SOCKET_NO_PROXY=localhost,127.0.0.1

SSL/TLS Certificates

Certificates are stored in /etc/nginx/ssl inside the container:

volumes:
  - ./ssl:/etc/nginx/ssl

Files

File	Purpose
`ssl/fullchain.pem`	Certificate chain (cert + intermediates)
`ssl/privkey.pem`	Private key

Auto-Generated

The firewall generates self-signed certs on first run if none exist.

Custom Certificates

cp /path/to/cert.pem ssl/fullchain.pem
cp /path/to/key.pem ssl/privkey.pem

Generate Self-Signed

mkdir -p ssl
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout ssl/privkey.pem \
  -out ssl/fullchain.pem \
  -subj "/CN=*.company.com" \
  -addext "subjectAltName=DNS:firewall.company.com,DNS:npm.company.com"

Docker Compose (Full Example)

services:
  socket-firewall:
    image: socketdev/socket-registry-firewall:latest
    ports:
      - "8080:8080"
      - "8443:8443"
    environment:
      - SOCKET_SECURITY_API_TOKEN=${SOCKET_SECURITY_API_TOKEN}
      - SOCKET_FAIL_OPEN=true
      - SOCKET_CACHE_TTL=600
    volumes:
      - ./socket.yml:/app/socket.yml:ro
      - ./ssl:/etc/nginx/ssl
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-fk", "https://localhost:8443/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  # Optional: Redis for distributed caching
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    command: redis-server --requirepass your-redis-password
    restart: unless-stopped

Health Check

curl -k https://localhost:8443/health
# {"status":"healthy","version":"..."}

Configuration File (socket.yml)