Configuration

Configuration Files

By default, Socket Firewall 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

SOCKET_API_KEY

Required: ✅

Socket API token with required scopes: packages, entitlements:list. Get your API key from socket.dev.

SFW_HOSTNAME

Required: ✅

The hostname which will be used to address the proxy server.

SFW_CA_CERT_PATH

Required: ✅

Path to a PEM-encoded CA certificate file. See Generating Keys for instructions.

SFW_CA_KEY_PATH

Required: ✅

Path to a PEM-encoded CA key file. See Generating Keys for instructions.

SFW_CONFIG_RELATIVE_PATHS

Determines whether Firewall config will be loaded from paths relative to the current working directory.

SFW_HTTP_PORT

Port on which to listen for HTTP CONNECT requests. Defaults to 80.

SFW_HTTPS_PORT

Port on which to listen for HTTPS CONNECT requests. Defaults to 443.

SFW_ALLOW_BAD_DESTINATION_CERT

ill ignore SSL errors when connecting to destination hosts. Must be set to the string true for the option to take effect.

SFW_CUSTOM_REGISTRIES

A comma-delimited set of custom registry entries. See Custom Registries documentation below for details

Example

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

SFW_UNKNOWN_HOST_ACTION

Action to take when encountering unknown hosts. Valid values: block, warn, or ignore. Defaults to block.

SFW_JSON_REPORT_PATH

Path to write a JSON report of blocked packages.

SFW_DEBUG

Enable debug logging. Must be set to the string true to enable.

SFW_TELEMETRY_DISABLED

Disables telemetry reporting to Socket. Must be set to the string true to disable.

SFW_TELEMETRY_ENDPOINT

Custom URL endpoint for telemetry data. Must be a valid URL. Defaults to https://api.socket.dev/v0/telemetry.

SFW_REPORT_MESSAGE

Custom message to display in the report when packages are blocked. Useful for linking to internal documentation (Wiki, Confluence) or providing organization-specific guidance. The message is displayed exactly as provided in the "Need help?" section of the report.

Example

export SFW_REPORT_MESSAGE="For internal guidance, see [https://wiki.example.com/security/sfw](https://wiki.example.com/security/sfw)"

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'