Skip to content

Configuration

Jump to bottom
github-actions[bot] edited this page Oct 24, 2025 · 3 revisions

Socket Firewall Configuration

Socket Firewall Enterprise can be configured through environment variables or configuration files. Configuration applies to both Wrapper Mode and Service Mode.

Configuration Files

By default, the proxy loads configuration from .sfw.config in your home directory and /run/secrets/dot-env-secrets (designed for use with Docker).

If the SFW_CONFIG_RELATIVE_PATHS environment variable is set, Socket Firewall will load configuration from multiple sources in order:

  1. .sfw.config (current directory)
  2. .sfw.config (parent directories)
  3. .sfw.config (home directory)
  4. /run/secrets/dot-env-secrets

Configuration files use dotenv format:

SOCKET_API_KEY=sktsec_your_api_key_here_api
SFW_HOSTNAME=your.proxy.hostname

Configuration Options

Configuration Variable Valid Modes Is Required Instructions
SOCKET_API_KEY ✅ Service Mode
✅ Wrapper Mode		 Yes Socket API token with required scopes: packages, entitlements:list.

Get your API key from socket.dev.

Example:
export SOCKET_API_KEY=sktsec_your_api_key_here_api
SFW_CONFIG_RELATIVE_PATHS ✅ Service Mode
✅ Wrapper Mode		 No Determines whether Firewall config will be loaded from paths relative to the current working directory. This is particularly useful if you're running in CLI wrapper mode and want to use different configurations for different local projects.

Example:
export SFW_CONFIG_RELATIVE_PATHS=true
SFW_HOSTNAME ✅ Service Mode
❌ Wrapper Mode		 Yes (service mode) The hostname which will be used to address the proxy server.

Example:
export SFW_HOSTNAME=your.proxy.hostname
SFW_CA_CERT_PATH ✅ Service Mode
❌ Wrapper Mode		 Yes (service mode) Path to a PEM-encoded CA certificate file. See Generating Keys for instructions.

Example:
export SFW_CA_CERT_PATH=/path/to/ca.crt
SFW_CA_KEY_PATH ✅ Service Mode
❌ Wrapper Mode		 Yes (service mode) Path to a PEM-encoded CA key file. See Generating Keys for instructions.

Example:
export SFW_CA_KEY_PATH=/path/to/ca.key
SFW_HTTP_PORT ✅ Service Mode
✅ Wrapper Mode		 No Port on which to listen for HTTP CONNECT requests. Defaults to 80.

Example:
export SFW_HTTP_PORT=8080
SFW_HTTPS_PORT ✅ Service Mode
✅ Wrapper Mode		 No Port on which to listen for HTTPS CONNECT requests. Defaults to 443.

Example:
export SFW_HTTPS_PORT=8443
SFW_ALLOW_BAD_DESTINATION_CERT ✅ Service Mode
✅ Wrapper Mode		 No Will ignore SSL errors when connecting to destination hosts. Must be set to the string true for the option to take effect.

Warning: Only use this option if you understand the security implications.

Example:
export SFW_ALLOW_BAD_DESTINATION_CERT=true
SFW_CUSTOM_REGISTRIES ✅ Service Mode
✅ Wrapper Mode		 No A comma-delimited set of custom registry entries. See Custom Registries below for details.

Example:
export SFW_CUSTOM_REGISTRIES='npm:packages.example.com/npm-mirror,pypi:packages.example.com/pypi-mirror'
SFW_UNKNOWN_HOST_ACTION ✅ Service Mode
✅ Wrapper Mode		 No Action to take when encountering unknown hosts. Valid values: block, warn, ignore. Defaults to block.

Example:
export SFW_UNKNOWN_HOST_ACTION=warn
SFW_JSON_REPORT_PATH ✅ Service Mode
✅ Wrapper Mode		 No Path to write a JSON report of blocked packages.

Example:
export SFW_JSON_REPORT_PATH=/path/to/report.json
SFW_DEBUG ✅ Service Mode
✅ Wrapper Mode		 No Enable debug logging. Must be set to the string true to enable.

Example:
export SFW_DEBUG=true
SFW_TELEMETRY_DISABLED ✅ Service Mode
✅ Wrapper Mode		 No Disables telemetry reporting to Socket. Must be set to the string true to disable.

Example:
export SFW_TELEMETRY_DISABLED=true
SFW_TELEMETRY_ENDPOINT ✅ Service Mode
✅ Wrapper Mode		 No Custom URL endpoint for telemetry data. Must be a valid URL. Defaults to https://api.socket.dev/v0/telemetry.

Example:
export SFW_TELEMETRY_ENDPOINT=https://custom.telemetry.endpoint/v0/telemetry

Custom Registries

Socket Firewall can filter traffic for custom registries. Each entry must take the form kind:fqdn or kind:fqdn/url-prefix.

Valid Registry Kinds

  • npm - npm registry
  • pypi - Python Package Index
  • maven - Maven repository
  • golang - Go modules proxy
  • gem - RubyGems registry
  • cargo - Rust crates registry
  • nuget - NuGet package registry
  • block - All traffic to the specified host will be blocked
  • wrap - All traffic to the specified host will be blindly forwarded without inspecting requests

FQDN Matching

The FQDN value should match the exact hostname that your package manager is configured to use.

URL Prefix (Optional)

An optional URL prefix is allowed. Some private registry services support multiple types of package manager, determined by the first part of the path. For example, you might have an .npmrc file that looks something like this:

; The trailing slash is required
registry=https://packages.example.com/npm-mirror/

; Auth token scoped to the exact host + path prefix
always-auth=true
//packages.example.com/npm-mirror/:_authToken=${NPM_TOKEN}

; You've installed the Socket Firewall CA locally, so you can trust the proxied TLS connection
strict-ssl=true

If this were your npm configuration, the corresponding custom registry config would look like this:

export SFW_CUSTOM_REGISTRIES='npm:packages.example.com/npm-mirror'

When configured in this way, Socket Firewall will intercept traffic to packages.example.com in the same way it does for standard public registries.

Multiple Custom Registries

Multiple prefixed registry entries are allowed. For example, the following configuration is valid:

export SFW_CUSTOM_REGISTRIES='npm:packages.example.com/npm-mirror,pypi:packages.example.com/pypi-mirror'
Clone this wiki locally