Skip to content

Client Setup

Jump to bottom
github-actions[bot] edited this page Jul 27, 2026 · 6 revisions

Package Manager Configuration for Socket Firewall

This guide explains how to configure various package managers to work with Socket Firewall, an HTTP proxy that provides security scanning for package installations.

Certificate Authority Setup

Socket Firewall uses a custom Certificate Authority (CA) to intercept HTTPS traffic. Before configuring package managers, you need to install and trust the CA certificate.

Note: If you're running Socket Firewall in service mode, you'll first need to generate the CA keypair and configure your service to use it. See Generating Keys for instructions on creating your CA keypair.

Installing the CA Certificate

Linux (Ubuntu/Debian)

# Copy the CA certificate to the system certificate directory
sudo cp /path/to/socketFirewallCa.crt /usr/local/share/ca-certificates/socketFirewallCa.crt

# Update the system certificate store
sudo update-ca-certificates

Linux (RedHat/CentOS/Fedora)

# Copy the CA certificate to the system certificate directory
sudo cp /path/to/socketFirewallCa.crt /etc/pki/ca-trust/source/anchors/socketFirewallCa.crt

# Update the system certificate store
sudo update-ca-trust

macOS

Terminal Method
# Add the CA certificate to the system keychain
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /path/to/socketFirewallCa.crt

# Verify the certificate was added. You may need to replace "Socket" with the name you provided
# when originally generating the CA key-pair.
security find-certificate -c "Socket" /Library/Keychains/System.keychain
GUI Method (Alternative)
  1. Double-click the socketFirewallCa.crt file to open Keychain Access
  2. Select "System" keychain when prompted
  3. Enter your administrator password
  4. Find the certificate in Keychain Access and double-click it
  5. Expand "Trust" section and set "When using this certificate" to "Always Trust"
  6. Close the dialog and enter your password again to save changes

For more details, see Apple's documentation on certificate trust settings.

Windows

PowerShell Method (Run as Administrator)
# Import the CA certificate to the Trusted Root Certification Authorities store
Import-Certificate -FilePath "C:\path\to\socketFirewallCa.crt" -CertStoreLocation Cert:\LocalMachine\Root

# Verify the certificate was imported
Get-ChildItem -Path Cert:\LocalMachine\Root | Where-Object {$_.Subject -like "*Socket Proxy CA*"}
GUI Method (Alternative)
  1. Right-click the socketFirewallCa.crt file and select "Install Certificate"
  2. Choose "Local Machine" and click "Next"
  3. Select "Place all certificates in the following store"
  4. Click "Browse" and select "Trusted Root Certification Authorities"
  5. Click "Next" then "Finish"
  6. Click "Yes" when prompted about installing the certificate

For more details, see Microsoft's documentation on managing certificates.

Java Applications (Maven, Gradle)

If Java is installed, add the CA certificate to the Java keystore:

keytool -import -trustcacerts -cacerts -noprompt \
    -storepass changeit \
    -alias socket-proxy-ca \
    -file /usr/local/share/ca-certificates/socketFirewallCa.crt

Verify CA is installed correctly

Run the following in the terminal to validate the Socket Firewall CA has been installed as a trusted root certificate:

openssl s_client -connect your-firewall-host:443 -prexit

Near the top of the output, you should see something like the following:

Certificate chain
 0 s:CN=your-firewall-host
   i:CN=Socket Security CA, O=Socket Security
   a:PKEY: RSA, 2048 (bit); sigalg: sha256WithRSAEncryption
   v:NotBefore: Aug 24 02:02:23 2025 GMT; NotAfter: Aug 24 02:02:23 2026 GMT

If you're not sure of the output, check it against the output from this command; they should look the same:

openssl s_client -connect your-firewall-host:443 -prexit -CAfile ./path/to/socketFirewallCa.crt

Package Manager Configurations

Node.js Package Managers

npm

npm supports configuration via the npm config command or by editing .npmrc files directly. The relevant config options are:

  • proxy - Proxy for outgoing HTTP requests
  • https-proxy - Proxy for outgoing HTTPS requests
  • cafile - Path to a file containing CA signing certificates

Using npm config (recommended):

npm config set proxy "https://your-firewall-host:https-port"
npm config set https-proxy "https://your-firewall-host:https-port"
npm config set cafile "/path/to/socketFirewallCa.crt"

Alternative: Editing .npmrc directly:

You can also add these settings to your .npmrc file (user-level at ~/.npmrc or project-level at .npmrc in your project root):

proxy=https://your-firewall-host:https-port
https-proxy=https://your-firewall-host:https-port
cafile=/path/to/socketFirewallCa.crt

Alternative for Node.js >= 23:

If you're using Node.js 23 or later, you can use the --use-system-ca flag instead of setting cafile, which tells Node.js to use the system's trusted CA certificates:

npm config set proxy "https://your-firewall-host:https-port"
npm config set https-proxy "https://your-firewall-host:https-port"
export NODE_OPTIONS="--use-system-ca"

Note: Firewall requires npm version 10 or higher. Previous versions of npm included an abstraction incompatible with how we intercept traffic.

Yarn

Environment Variables:

export YARN_HTTP_PROXY="https://your-firewall-host:https-port"
export YARN_HTTPS_PROXY="https://your-firewall-host:https-port"
export NODE_EXTRA_CA_CERTS="/path/to/socketFirewallCa.crt"
export YARN_HTTPS_CA_FILE_PATH="/path/to/socketFirewallCa.crt"

Alternative for Node.js > 23:

export YARN_HTTP_PROXY="https://your-firewall-host:https-port"
export YARN_HTTPS_PROXY="https://your-firewall-host:https-port"
export NODE_OPTIONS="--use-system-ca"

pnpm

pnpm uses the same .npmrc configuration file format as npm. The relevant config options are:

  • proxy / http-proxy - Proxy for outgoing HTTP requests
  • https-proxy - Proxy for outgoing HTTPS requests
  • cafile - Path to a file containing CA signing certificates

Using pnpm config (recommended):

pnpm config set proxy "https://your-firewall-host:https-port"
pnpm config set https-proxy "https://your-firewall-host:https-port"
pnpm config set cafile "/path/to/socketFirewallCa.crt"

Alternative: Editing .npmrc directly:

You can also add these settings to your .npmrc file (user-level at ~/.npmrc or project-level at .npmrc in your project root):

proxy=https://your-firewall-host:https-port
https-proxy=https://your-firewall-host:https-port
cafile=/path/to/socketFirewallCa.crt

Alternative: Using environment variables:

pnpm also respects standard proxy environment variables, though the .npmrc approach above is recommended for persistence:

export HTTP_PROXY="https://your-firewall-host:https-port"
export HTTPS_PROXY="https://your-firewall-host:https-port"
export NODE_EXTRA_CA_CERTS="/path/to/socketFirewallCa.crt"

Alternative for Node.js >= 23:

If you're using Node.js 23 or later, you can use the --use-system-ca flag instead of setting cafile:

pnpm config set proxy "https://your-firewall-host:https-port"
pnpm config set https-proxy "https://your-firewall-host:https-port"
export NODE_OPTIONS="--use-system-ca"

Python Package Managers

pip

Environment Variables:

export HTTP_PROXY="https://your-firewall-host:https-port"
export HTTPS_PROXY="https://your-firewall-host:https-port"
export PIP_CERT="/path/to/socketFirewallCa.crt"

Poetry

Poetry is not currently supported by Socket Firewall

uv

Environment Variables:

export HTTP_PROXY="https://your-firewall-host:https-port"
export HTTPS_PROXY="https://your-firewall-host:https-port"
export PIP_CERT="/path/to/socketFirewallCa.crt"

Go

Environment Variables:

export HTTP_PROXY="https://your-firewall-host:https-port"
export HTTPS_PROXY="https://your-firewall-host:https-port"

Rust (Cargo)

Configuration File: Create .cargo/config.toml in your project or home directory:

[http]
cainfo = "/path/to/socketFirewallCa.crt"
proxy = 'your-firewall-host:http-port'
proxy-cainfo = "/path/to/socketFirewallCa.crt"
multiplexing = false

Known Issue: Cargo currently has limited support for HTTPS proxies. Use the HTTP port of Socket Firewall instead.

Ruby Package Managers

gem and Bundler read the same ~/.gemrc file and honor the same proxy environment variables. Prefer .gemrc: with environment variables, Bundler needs http_proxy specifically — see the Known Issue under Bundler below.

Note: Point both tools at the HTTP port of Socket Firewall. Neither opens a TLS connection to the proxy itself, so a https:// proxy URL is spoken as plaintext rather than TLS (net/http added the capability, but the HTTP stacks vendored by RubyGems and Bundler do not use it). HTTPS between Socket Firewall and the gem source is unaffected.

RubyGems (gem)

Configuration File: Create ~/.gemrc:

---
http_proxy: http://your-firewall-host:http-port

http_proxy is the only proxy key .gemrc has, and it does more than its name suggests:

  • RubyGems applies it to every fetch regardless of the URL scheme, so it covers https:// gem sources.
  • It takes precedence over the proxy environment variables.
  • A https_proxy: key is dead config — nothing in RubyGems or Bundler reads it. Do not add one: if it is your only proxy setting, gem and Bundler connect directly to the gem source and never reach Socket Firewall at all.

Alternative: Environment variables:

export http_proxy="http://your-firewall-host:http-port"
export https_proxy="http://your-firewall-host:http-port"

Set both variables (Bundler needs http_proxy; see the Known Issue below). The uppercase HTTP_PROXY/HTTPS_PROXY spellings work as well, but RubyGems' vendored net/http warns that HTTP_PROXY is discouraged, so the lowercase form is quieter.

Bundler

Configuration: Bundler reads the same ~/.gemrc file and the same environment variables as RubyGems (gem) above.

Known Issue: Configured by environment variable, Bundler needs http_proxy (or HTTP_PROXY) — HTTPS_PROXY alone silently leaves package metadata unproxied, because Bundler's vendored copy of net-http-persistent resolves the proxy for its metadata connection from http_proxy/HTTP_PROXY only.

  • What breaks: with only https_proxy/HTTPS_PROXY set, Bundler's compact index and dependency metadata requests go direct to index.rubygems.org, bypassing Socket Firewall — or fail with Could not reach host index.rubygems.org if direct egress is blocked — while .gem downloads still go through the proxy.
  • What to do: set both variables, or use the .gemrc http_proxy: key, which Bundler applies to its metadata connection and its .gem downloads alike.
  • What is unaffected: .gemrc configuration — this is an environment-variable-only failure mode — and the sfw wrapper, which sets all four proxy variables for you.

Java Package Managers

Maven

Configuration File: Edit /usr/share/maven/conf/settings.xml (or ~/.m2/settings.xml):

<settings>
  <proxies>
    <proxy>
      <id>http-proxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>your-firewall-host</host>
      <port>http-port</port>
    </proxy>
    <proxy>
      <id>https-proxy</id>
      <active>true</active>
      <protocol>https</protocol>
      <host>your-firewall-host</host>
      <port>http-port</port>
    </proxy>
  </proxies>
</settings>

Known Issue: Maven uses Apache HttpClient, which doesn't support HTTPS requests through HTTPS proxies. Use the HTTP port for both protocols.

Gradle

Configuration File: Create ~/.gradle/gradle.properties:

systemProp.http.proxyHost=your-firewall-host
systemProp.http.proxyPort=http-port
systemProp.https.proxyHost=your-firewall-host
systemProp.https.proxyPort=http-port

Known Issue: Gradle uses Apache HttpClient, which doesn't support HTTPS requests through HTTPS proxies. Use the HTTP port for both protocols.

.NET (NuGet)

Environment Variables:

export HTTP_PROXY="https://your-firewall-host:https-port"
export HTTPS_PROXY="https://your-firewall-host:https-port"

Important Notes

HTTPS Proxy Limitations

Several package managers have limitations with HTTPS proxies:

  • Cargo: Limited HTTPS proxy support (issue)
  • Maven/Gradle: Apache HttpClient doesn't support HTTPS through HTTPS proxy (issue)
  • RubyGems/Bundler: Their vendored HTTP stacks never negotiate TLS with the proxy (see above)

For these tools, use the HTTP port of Socket Firewall instead of the HTTPS port.

Environment Variable Priority

Most package managers respect standard HTTP proxy environment variables:

  • HTTP_PROXY / http_proxy
  • HTTPS_PROXY / https_proxy

Always set both, even for registries reached only over HTTPS — not every tool reads both.

Some tools have their own specific environment variables (e.g., YARN_HTTP_PROXY, PIP_CERT).

Clone this wiki locally