Configuration Reference

Complete reference for Socket Registry Firewall configuration options. All options can be set in socket.yml or overridden via environment variables.

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 Socket Settings

socket:
  # Socket.dev API endpoint (required)
  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 for all upstream connections
  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       # Verify SSL for Socket API (default: true)
  api_ssl_ca_cert: /path/to/corporate-ca.crt  # Custom CA cert
  
  # SSL verification for upstream registry connections
  upstream_ssl_verify: true  # Verify SSL for upstream registries (default: true)
  upstream_ssl_ca_cert: /path/to/upstream-ca.crt  # Custom CA for upstreams
  
  # Request behavior
  request_id_header: X-Socket-Request-ID  # Custom request ID header name

Environment variables:

SOCKET_SECURITY_API_TOKEN=your-api-key  # Required
SOCKET_API_URL=https://api.socket.dev
SOCKET_FAIL_OPEN=true
SOCKET_OUTBOUND_PROXY=http://proxy:3128
SOCKET_NO_PROXY=localhost,127.0.0.1

Ports

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

Environment variables:

HTTP_PORT=8080
HTTPS_PORT=8443

Deployment Mode

Controls path generation for different deployment topologies:

# Default (downstream) - Client → Firewall → Registry
# Generates API paths for package manager clients
# No config_mode needed

# Upstream mode - Registry → Firewall → Public
# Generates direct paths for registry-to-registry communication
config_mode: upstream

# Middle mode - Registry → Firewall → Registry
# Generates both API and direct paths for multi-tier registries
config_mode: middle

Mode	Use When	Paths Generated	URL Rewriting
(default)	Client → FW → Registry	API paths	Yes
`upstream`	Private Registry → FW → Public	Direct paths	Yes
`middle`	Private Registry → FW → Private	Both API+Direct	No (proxy)

Environment variable:

CONFIG_MODE=upstream  # or 'middle'

Path-Based Routing

All registries behind a single domain with path prefixes. Recommended for most deployments.

path_routing:
  enabled: true
  domain: firewall.company.com
  
  routes:
    - path: /npm
      upstream: https://registry.npmjs.org
      registry: npm
      mode: rewrite  # 'rewrite' (default) or 'proxy'
      
    - path: /pypi
      upstream: https://pypi.org
      registry: pypi
      mode: rewrite
      
    - 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
      
    - path: /conda
      upstream: https://conda.anaconda.org
      registry: conda

Route Options

Field	Required	Description	Values
`path`	Yes	URL path prefix (must start with `/`)	`/npm`, `/pypi`, etc.
`upstream`	Yes	Upstream registry URL	HTTPS URL
`registry`	Yes	Registry type/ecosystem	npm, pypi, maven, etc.
`mode`	No	URL rewriting mode	`rewrite` (default), `proxy`

Route Mode: rewrite vs proxy

mode: rewrite (default) - Rewrites package URLs to point back through the firewall:

Use for: Downstream, Upstream deployments
URL in metadata → https://firewall.company.com/npm/package.tgz
Clients fetch packages through firewall

mode: proxy - Passes URLs through unchanged:

Use for: Middle deployments (Registry → FW → Registry)
URL in metadata → ../../packages/package.tgz (relative) or original upstream URL
Downstream registry resolves relative URLs
Required when using config_mode: middle

External Routes File

For 50+ routes or dynamic route management, use an external file:

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

routes.yml format:

routes:
  - path: /npm-public
    upstream: https://registry.npmjs.org
    registry: npm
  - path: /npm-internal
    upstream: https://nexus.company.com/repository/npm-internal
    registry: npm
  # ... many more routes

Mount the routes file:

volumes:
  - ./routes.yml:/config/routes.yml:ro

Auto-Discovery (Artifactory/Nexus)

Automatically sync routes from your artifact manager. Routes update on interval without restarting the firewall!

path_routing:
  enabled: true
  domain: firewall.company.com
  mode: artifactory  # or 'nexus'
  
  private_registry:
    # Artifactory settings
    api_url: https://artifactory.company.com/artifactory
    api_key: your-artifactory-api-key  # Or use API_KEY env var
    username: admin  # Optional - for basic auth
    password: secret  # Optional - for basic auth
    
    # Sync settings
    interval: 5m              # Auto-sync interval (e.g., 30s, 5m, 1h)
    default_registry: maven   # Fallback for unknown/unsupported repo types
    
    # Filtering (regex patterns)
    include_pattern: ".*"              # Include all repos (default)
    exclude_pattern: "(tmp|test)-.*"   # Exclude temp/test repos

Artifactory Auto-Discovery

Discovers all remote repositories in Artifactory and creates firewall routes automatically.

Supported repository types:

npm
pypi
maven
cargo (bower in Artifactory)
rubygems
nuget
go (golang in Artifactory)
conda (conda in experimental support)

Example discovered routes:

/npm-public       → https://registry.npmjs.org
/pypi-public      → https://pypi.org
/maven-central    → https://repo1.maven.org/maven2
/cargo-crates     → https://index.crates.io

Nexus Auto-Discovery

Discovers all proxy repositories in Nexus and creates firewall routes automatically.

path_routing:
  mode: nexus
  private_registry:
    api_url: https://nexus.company.com
    api_key: your-nexus-api-token
    interval: 5m

Supported repository formats:

npm
pypi
maven2
cargo
rubygems
nuget
golang
conda

Route naming: Routes are named after the repository name in Nexus (e.g., /npm-proxy, /pypi-proxy)

Auto-Discovery Environment Variables

AUTO_DISCOVERY_MODE=artifactory  # or 'nexus'
AUTO_DISCOVERY_API_URL=https://artifactory.company.com/artifactory
AUTO_DISCOVERY_API_KEY=your-api-key
AUTO_DISCOVERY_INTERVAL=5m
AUTO_DISCOVERY_DEFAULT_REGISTRY=maven
AUTO_DISCOVERY_INCLUDE_PATTERN=".*"
AUTO_DISCOVERY_EXCLUDE_PATTERN="(tmp|test)-.*"

Domain-Based Routing

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

registries:
  npm:
    domains: [npm.company.com]
    upstream: https://registry.npmjs.org  # Optional - defaults to public registry
    
  pypi:
    domains: [pypi.company.com, python.company.com]  # Multiple domains supported
    upstream: https://pypi.org
    
  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]
    
  conda:
    domains: [conda.company.com]

Client usage:

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

DNS requirements:
Each domain needs an A or CNAME record pointing to the firewall host.

SSL requirements:
Either provide individual certs for each domain, or use a wildcard cert (*.company.com).

Caching

Local In-Memory Cache (Default)

cache:
  ttl: 600  # Freshness window in seconds (10 minutes default)

Cached results are stored in nginx shared memory. Fresh for ttl seconds, then becomes stale but is retained for revalidation.

Environment variable:

SOCKET_CACHE_TTL=600

Redis Cache (Distributed)

For multi-instance deployments or persistent caching across restarts:

redis:
  enabled: true
  host: redis.company.com
  port: 6379
  password: your-redis-password  # Optional
  db: 0  # Redis database number (default: 0)
  ttl: 86400   # Stale window in seconds (24 hours default)
  
  # SSL/TLS settings
  ssl: true
  ssl_verify: true
  ssl_ca_cert: /path/to/redis-ca.pem
  ssl_client_cert: /path/to/client-cert.pem  # For mTLS
  ssl_client_key: /path/to/client-key.pem   # For mTLS
  ssl_server_name: redis.company.com  # SNI hostname

Stale-while-revalidate behavior:

Fresh zone (0 to cache.ttl seconds): Return cached value immediately
Stale zone (cache.ttl to redis.ttl seconds): Revalidate with Socket API, fallback to stale on error
Expired (after redis.ttl): Key removed by Redis, fetch fresh from Socket API

Environment variables:

REDIS_ENABLED=true
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=secret
REDIS_DB=0
REDIS_TTL=86400
REDIS_SSL=true
REDIS_SSL_VERIFY=true

Nginx Performance

nginx:
  worker_processes: 2        # Number of worker processes (match CPU cores)
  worker_connections: 4096   # Max concurrent connections per worker

Resource-Based Recommendations

Resources	worker_processes	worker_connections	Est. Throughput
1 CPU / 1 GB RAM	1	512	~30 req/s
2 CPU / 2 GB RAM	2	1024	~60 req/s
4 CPU / 4 GB RAM	4	4096	~100 req/s
8 CPU / 8 GB RAM	8	8192	~170 req/s
16 CPU / 16 GB	16	16384	~300 req/s

Environment variables:

WORKER_PROCESSES=2
WORKER_CONNECTIONS=4096

Proxy Timeouts

Configure timeouts for upstream registry connections:

proxy:
  connect_timeout: 60  # Seconds to establish connection
  send_timeout: 60     # Seconds to send request
  read_timeout: 60     # Seconds to read response
  
  # Buffer sizes (advanced)
  buffer_size: 4k      # Initial buffer for response headers
  buffers_count: 8     # Number of buffers for response body
  buffers_size: 4k     # Size of each buffer
  busy_buffers_size: 8k  # Buffers that can be sent to client while reading

For large packages (e.g., Maven artifacts > 100MB):

proxy:
  connect_timeout: 120
  send_timeout: 300
  read_timeout: 300

Environment variables:

PROXY_CONNECT_TIMEOUT=60
PROXY_SEND_TIMEOUT=60
PROXY_READ_TIMEOUT=60

Metadata Filtering

Requires version 1.1.108 or higher.

Remove blocked or warned package versions from registry metadata responses before clients see them, preventing installation attempts of unsafe packages entirely. Supports all 9 ecosystems with ecosystem-appropriate filtering granularity.

metadata_filtering:
  enabled: true
  filter_blocked: true              # Remove blocked/error packages from metadata
  filter_warn: false                # Keep warned packages visible (show warnings only)
  include_unchecked_versions: true  # Include versions not yet checked by Socket (default: true)
  max_versions: 100                 # Max versions to check per package (default: 100, newest first)
  cache_ttl: 3600                   # Cache TTL for metadata PURL lookups (default: 3600s = 1 hour)
  batch_size: 4000                  # Max PURLs per batch (Socket API limit ~4K)

Options

Field	Default	Description
`enabled`	`false`	Enable metadata filtering
`filter_blocked`	`true`	Remove packages with `block` or `error` actions from metadata
`filter_warn`	`false`	Remove packages with `warn` actions from metadata
`include_unchecked_versions`	`true`	Keep versions not yet scanned by Socket (`false` = strict security posture)
`max_versions`	`100`	Max versions to check per package (newest first; older versions kept as-is)
`cache_ttl`	`3600`	Cache TTL in seconds for metadata PURL lookups (separate from download TTL)
`batch_size`	`4000`	Max PURLs per Socket API batch call (~4K API limit)

How It Works

Client requests package metadata (e.g., npm install lodash, pip install requests)
Firewall fetches the full metadata response from the upstream registry
Extracts all package versions/artifacts and builds Package URLs (PURLs)
Calls the Socket API in batches to check security status of each version
Removes blocked (and optionally warned) versions from the response
Returns sanitized metadata to the client

When filtering is disabled, responses stream through unchanged with no buffering.

Supported Ecosystems

Per-artifact filtering — individual artifacts within a version can be selectively removed:

Ecosystem	Metadata Format	Notes
PyPI	HTML (PEP 503) and JSON (PEP 691) `/simple/{package}/`	Filters tar.gz, wheels, eggs, zips independently
Maven	HTML directory listings and `maven-metadata.xml`	Filters by classifier and extension (e.g., `?classifier=sources&ext=jar`)

Per-version filtering — if any artifact is blocked, the entire version is removed:

Ecosystem	Metadata Format	Notes
npm	Package JSON (`/{package}`)	Filters `versions`, `dist-tags`, and `time` objects
NuGet	Registration catalog JSON (`/v3/registration5-gz-semver2/`)	Removes entries from catalog pages
RubyGems	CompactIndex (`/info/{gem}`) and JSON API (`/api/v1/versions/`)	Line-based and JSON array formats
Cargo	Sparse index NDJSON (`/{2-chars}/{2-chars}/{crate}`)	One version per NDJSON line
Go	`/@v/list` (newline-separated) and `/@latest` (JSON)	Source-only, no binary artifacts
Conda	`repodata.json` (`packages` and `packages.conda` objects)	Uses PyPI PURLs (Socket API fallback)
OpenVSX	Extension detail JSON (`/api/{namespace}/{extension}`)	Single .vsix per version

Use Cases

Prevent accidental installation of malicious or vulnerable packages
Remove flagged packages from search results and dependency resolution
Enforce strict security posture by excluding unchecked versions (include_unchecked_versions: false)
Pre-warm the PURL cache from metadata lookups, speeding up subsequent download checks

Environment Variables

METADATA_FILTERING_ENABLED=true
METADATA_FILTER_BLOCKED=true
METADATA_FILTER_WARN=false
METADATA_INCLUDE_UNCHECKED_VERSIONS=true
METADATA_MAX_VERSIONS=100
METADATA_CACHE_TTL=3600
METADATA_FILTER_BATCH_SIZE=4000

Bulk PURL Lookup

Note: Bulk PURL lookup is now integrated into metadata filtering (v1.1.108+). The batch_size option under metadata_filtering controls the batch size for API calls. The standalone bulk_purl_lookup configuration below is deprecated.

Pre-cache security status for multiple packages in a single API call for faster lookups:

# Deprecated - use metadata_filtering.batch_size instead
bulk_purl_lookup:
  enabled: true
  batch_size: 5000        # Max PURLs per batch (default: 5000)
  ecosystems: [npm, pypi]  # Limit to specific ecosystems (optional)

How it works:

When metadata filtering is enabled, extracts all package identifiers from metadata
Batches them into groups of batch_size
Calls Socket API in batches
Caches results for faster subsequent lookups

Benefits:

Reduces API call latency for large metadata responses
Pre-warms cache with one call instead of hundreds
More efficient for package managers that fetch full indexes

Environment variables:

# Deprecated - use METADATA_FILTER_BATCH_SIZE instead
BULK_PURL_LOOKUP_ENABLED=true
BULK_PURL_LOOKUP_BATCH_SIZE=5000

Splunk Integration

Forward security events to Splunk HTTP Event Collector (HEC):

splunk:
  enabled: true
  hec_url: https://splunk.company.com:8088/services/collector/event
  hec_token: your-splunk-hec-token
  index: security           # Splunk index name
  source: socket-firewall   # Splunk source name
  sourcetype: socket:registry:firewall  # Splunk sourcetype
  
  # SSL settings
  ssl_verify: true
  ssl_ca_cert: /path/to/splunk-ca.pem
  
  # Event batching
  batch_size: 100          # Events per batch (default: 100)
  flush_interval: 10       # Seconds between flushes (default: 10)

Event types logged:

Package blocks (malicious/supply-chain attacks)
Package warnings
API errors
Cache hits/misses
Request/response metadata

Example Splunk event:

{
  "time": 1709078400,
  "event": {
    "action": "block",
    "ecosystem": "npm",
    "package": "malicious-package",
    "version": "1.0.0",
    "reason": "Known malware",
    "severity": "critical",
    "client_ip": "203.0.113.10",
    "request_id": "abc123xyz",
    "user_agent": "npm/8.19.2"
  },
  "source": "socket-firewall",
  "sourcetype": "socket:registry:firewall",
  "index": "security"
}

Environment variables:

SPLUNK_ENABLED=true
SPLUNK_HEC_URL=https://splunk.company.com:8088/services/collector/event
SPLUNK_HEC_TOKEN=your-token
SPLUNK_INDEX=security
SPLUNK_SOURCE=socket-firewall

SSL/TLS Certificates

Certificates are stored in /etc/nginx/ssl inside the container. Mount from host:

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

Required Files

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

Auto-Generated Certificates

The firewall generates self-signed certs on first run if none exist. Located at /etc/nginx/ssl/.

Custom Certificates (Production)

Place your organization's certificates in the ssl/ directory on the host:

mkdir -p ssl
cp /path/to/cert.pem ssl/fullchain.pem
cp /path/to/key.pem ssl/privkey.pem
chmod 644 ssl/fullchain.pem ssl/privkey.pem

Generate Self-Signed Certificates

Single domain:

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

Wildcard (multiple subdomains):

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:*.company.com,DNS:company.com,DNS:localhost"
chmod 644 ssl/fullchain.pem ssl/privkey.pem

Trust Self-Signed Certificates

macOS:

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain ssl/fullchain.pem

Linux:

sudo cp ssl/fullchain.pem /usr/local/share/ca-certificates/socket-firewall.crt
sudo update-ca-certificates

Windows:

Import-Certificate -FilePath ssl\fullchain.pem -CertStoreLocation Cert:\LocalMachine\Root

Environment Variables Reference

All configuration can be overridden via environment variables. Useful for Docker/Kubernetes deployments.

Core Settings

# Required
SOCKET_SECURITY_API_TOKEN=your-api-key        # Socket.dev API key

# Socket API
SOCKET_API_URL=https://api.socket.dev         # Default
SOCKET_FAIL_OPEN=true                         # Allow on API error (default: true)
SOCKET_CACHE_TTL=600                          # Freshness window (seconds)

# Ports
HTTP_PORT=8080                                # HTTP port
HTTPS_PORT=8443                               # HTTPS port

# Deployment mode
CONFIG_MODE=upstream                          # 'upstream' or 'middle'

# SSL verification
SOCKET_API_SSL_VERIFY=true                    # Verify Socket API SSL
SOCKET_API_SSL_CA_CERT=/path/to/ca.crt       # Custom Socket API CA
SOCKET_UPSTREAM_SSL_VERIFY=true              # Verify upstream registry SSL
SOCKET_UPSTREAM_SSL_CA_CERT=/path/to/ca.crt  # Custom upstream CA

# Corporate proxy
SOCKET_OUTBOUND_PROXY=http://proxy:3128      # Egress proxy
SOCKET_NO_PROXY=localhost,127.0.0.1          # No-proxy exceptions

Redis

REDIS_ENABLED=true                            # Enable Redis
REDIS_HOST=redis.company.com                  # Redis hostname
REDIS_PORT=6379                               # Redis port
REDIS_PASSWORD=secret                         # Redis password
REDIS_DB=0                                    # Redis database number
REDIS_TTL=86400                               # Stale window (seconds)

# Redis SSL
REDIS_SSL=true                                # Enable SSL
REDIS_SSL_VERIFY=true                         # Verify Redis SSL
REDIS_SSL_CA_CERT=/path/to/redis-ca.pem      # Redis CA cert
REDIS_SSL_SERVER_NAME=redis.company.com       # SNI hostname

Nginx Performance

WORKER_PROCESSES=2                            # nginx worker processes
WORKER_CONNECTIONS=4096                       # Connections per worker

Proxy Timeouts

PROXY_CONNECT_TIMEOUT=60                      # Connection timeout (seconds)
PROXY_SEND_TIMEOUT=60                         # Send timeout
PROXY_READ_TIMEOUT=60                         # Read timeout

Auto-Discovery

AUTO_DISCOVERY_MODE=artifactory               # 'artifactory' or 'nexus'
AUTO_DISCOVERY_API_URL=https://artifactory.company.com/artifactory
AUTO_DISCOVERY_API_KEY=your-api-key          # Or use username/password
AUTO_DISCOVERY_USERNAME=admin                 # Basic auth username
AUTO_DISCOVERY_PASSWORD=secret                # Basic auth password
AUTO_DISCOVERY_INTERVAL=5m                    # Sync interval (30s, 5m, 1h)
AUTO_DISCOVERY_DEFAULT_REGISTRY=maven         # Fallback registry type
AUTO_DISCOVERY_INCLUDE_PATTERN=".*"           # Include pattern
AUTO_DISCOVERY_EXCLUDE_PATTERN="(tmp|test)-.*"  # Exclude pattern

Metadata Filtering

METADATA_FILTERING_ENABLED=true               # Enable filtering (v1.1.108+)
METADATA_FILTER_BLOCKED=true                  # Filter blocked packages
METADATA_FILTER_WARN=false                    # Filter warned packages
METADATA_INCLUDE_UNCHECKED_VERSIONS=true      # Keep unchecked versions
METADATA_MAX_VERSIONS=100                     # Max versions to check per package
METADATA_CACHE_TTL=3600                       # Cache TTL for metadata lookups (seconds)
METADATA_FILTER_BATCH_SIZE=4000               # Max PURLs per batch

Bulk PURL Lookup (Deprecated)

# Deprecated in v1.1.108 - use METADATA_FILTER_BATCH_SIZE instead
BULK_PURL_LOOKUP_ENABLED=true                 # Enable bulk lookups
BULK_PURL_LOOKUP_BATCH_SIZE=5000             # PURLs per batch

Splunk

SPLUNK_ENABLED=true                           # Enable Splunk
SPLUNK_HEC_URL=https://splunk.company.com:8088/services/collector/event
SPLUNK_HEC_TOKEN=your-hec-token              # Splunk HEC token
SPLUNK_INDEX=security                         # Splunk index
SPLUNK_SOURCE=socket-firewall                 # Splunk source
SPLUNK_SOURCETYPE=socket:registry:firewall    # Splunk sourcetype
SPLUNK_SSL_VERIFY=true                        # Verify Splunk SSL
SPLUNK_BATCH_SIZE=100                         # Events per batch
SPLUNK_FLUSH_INTERVAL=10                      # Flush interval (seconds)

Docker Compose Examples

Minimal Configuration

services:
  socket-firewall:
    image: socketdev/socket-registry-firewall:latest
    ports:
      - "8080:8080"
      - "8443:8443"
    environment:
      - SOCKET_SECURITY_API_TOKEN=${SOCKET_SECURITY_API_TOKEN}
    volumes:
      - ./socket.yml:/app/socket.yml:ro
      - ./ssl:/etc/nginx/ssl
    restart: unless-stopped

Full Configuration with Redis

services:
  socket-firewall:
    image: socketdev/socket-registry-firewall:latest
    ports:
      - "8080:8080"
      - "8443:8443"
    environment:
      # Core
      - SOCKET_SECURITY_API_TOKEN=${SOCKET_SECURITY_API_TOKEN}
      - SOCKET_FAIL_OPEN=true
      - SOCKET_CACHE_TTL=600
      
      # Redis
      - REDIS_ENABLED=true
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - REDIS_PASSWORD=${REDIS_PASSWORD}
      - REDIS_TTL=86400
      
      # Performance
      - WORKER_PROCESSES=4
      - WORKER_CONNECTIONS=8192
      
      # Corporate proxy
      - SOCKET_OUTBOUND_PROXY=http://proxy.company.com:3128
      - SOCKET_NO_PROXY=localhost,127.0.0.1
      
    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
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis-data:/data
    restart: unless-stopped

volumes:
  redis-data:

With Splunk Integration

services:
  socket-firewall:
    image: socketdev/socket-registry-firewall:latest
    ports:
      - "8080:8080"
      - "8443:8443"
    environment:
      - SOCKET_SECURITY_API_TOKEN=${SOCKET_SECURITY_API_TOKEN}
      
      # Splunk
      - SPLUNK_ENABLED=true
      - SPLUNK_HEC_URL=https://splunk.company.com:8088/services/collector/event
      - SPLUNK_HEC_TOKEN=${SPLUNK_HEC_TOKEN}
      - SPLUNK_INDEX=security
      - SPLUNK_SOURCE=socket-firewall
      
    volumes:
      - ./socket.yml:/app/socket.yml:ro
      - ./ssl:/etc/nginx/ssl
    restart: unless-stopped

Health Checks

The firewall exposes a health endpoint at /health:

curl -k https://localhost:8443/health

Response:

{
  "status": "healthy",
  "version": "1.1.94"
}

HTTP status codes:

200 OK - Firewall is healthy
503 Service Unavailable - Firewall is unhealthy (nginx not running, config error)

Docker healthcheck:

healthcheck:
  test: ["CMD", "curl", "-fk", "https://localhost:8443/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 10s

Complete Configuration Example

socket.yml:

# Core Socket settings
socket:
  api_url: https://api.socket.dev
  fail_open: true
  outbound_proxy: http://proxy.company.com:3128
  no_proxy: localhost,127.0.0.1,internal.company.com
  api_ssl_verify: true
  api_ssl_ca_cert: /etc/ssl/certs/corporate-ca.crt
  upstream_ssl_verify: true

# Ports
ports:
  http: 8080
  https: 8443

# Deployment mode
config_mode: upstream

# Path-based routing with auto-discovery
path_routing:
  enabled: true
  domain: socket-firewall.company.com
  mode: artifactory
  
  private_registry:
    api_url: https://artifactory.company.com/artifactory
    api_key: ${ARTIFACTORY_API_KEY}
    interval: 5m
    default_registry: maven
    exclude_pattern: "(tmp|test|snapshot)-.*"

# Caching
cache:
  ttl: 600

redis:
  enabled: true
  host: redis.company.com
  port: 6380
  password: ${REDIS_PASSWORD}
  ttl: 86400
  ssl: true
  ssl_verify: true
  ssl_ca_cert: /etc/redis/ssl/ca-cert.pem

# Performance
nginx:
  worker_processes: 8
  worker_connections: 16384

proxy:
  connect_timeout: 120
  send_timeout: 300
  read_timeout: 300

# Advanced features (v1.1.108+)
metadata_filtering:
  enabled: true
  filter_blocked: true
  filter_warn: false
  include_unchecked_versions: true
  max_versions: 100
  cache_ttl: 3600
  batch_size: 4000

splunk:
  enabled: true
  hec_url: https://splunk.company.com:8088/services/collector/event
  hec_token: ${SPLUNK_HEC_TOKEN}
  index: security
  source: socket-firewall
  sourcetype: socket:registry:firewall
  ssl_verify: true

Configuration Reference

Configuration File (socket.yml)

Core Socket Settings

Ports

Deployment Mode

Path-Based Routing

Route Options

Route Mode: rewrite vs proxy

External Routes File

Auto-Discovery (Artifactory/Nexus)

Artifactory Auto-Discovery

Nexus Auto-Discovery

Auto-Discovery Environment Variables

Domain-Based Routing

Caching

Local In-Memory Cache (Default)

Redis Cache (Distributed)

Nginx Performance

Resource-Based Recommendations

Proxy Timeouts

Metadata Filtering

Options

How It Works

Supported Ecosystems

Use Cases

Environment Variables

Bulk PURL Lookup

Splunk Integration

SSL/TLS Certificates

Required Files

Auto-Generated Certificates

Custom Certificates (Production)

Generate Self-Signed Certificates

Trust Self-Signed Certificates

Environment Variables Reference

Core Settings

Redis

Nginx Performance

Proxy Timeouts

Auto-Discovery

Metadata Filtering

Bulk PURL Lookup (Deprecated)

Splunk

Docker Compose Examples

Minimal Configuration

Full Configuration with Redis

With Splunk Integration

Health Checks

Complete Configuration Example

Configuration File (`socket.yml`)