Service Setup

Socket Firewall Service Setup

Socket Firewall can run as a persistent service, making it ideal for Docker deployments, CI/CD pipeline integration, and environments where you need manual proxy configuration. In service mode, the proxy server runs continuously.

Service Mode Configuration

Run Socket Firewall as a persistent service:

# Required environment variables for service mode
# Required scopes: packages, entitlements:list
export SOCKET_API_KEY=sktsec_your_api_key_here_api
export SFW_HOSTNAME=your.proxy.hostname
export SFW_CA_CERT_PATH=/path/to/ca.crt
export SFW_CA_KEY_PATH=/path/to/ca.key

# Optional environment variables (with defaults)
export SFW_HTTP_PORT=80
export SFW_HTTPS_PORT=443

sfw --service

Note: These environment variables are only required for service mode. In wrapper mode, the CLI handles configuration automatically, requiring only the SOCKET_API_KEY.

Docker Deployment

The Socket Firewall docker image can be used for running on-prem. It can be found on Docker Hub.

To ensure you have access to the image on Docker Hub, please run docker manifest inspect socketdev/socket-firewall:latest. If you see an no such manifest message, make sure you are logged in with docker login.

You can use the following Docker Compose file as a starting point:

name: socket-firewall
services:
  firewall:
    image: socketdev/socket-firewall:latest
    ports:
      - "80:80"
      - "443:443"
    environment:
      - SFW_HTTP_PORT=80
      - SFW_HTTPS_PORT=443
      - SFW_HOSTNAME=your.proxy.hostname
      - SFW_CA_CERT_PATH=/app/certs/ca.crt
      - SFW_CA_KEY_PATH=/app/certs/ca.key
    volumes:
      # You need to generate these and provide in PEM format
      - path/to/socketFirewallCa.crt:/app/certs/ca.crt:ro
      - path/to/socketFirewallCa.key:/app/certs/ca.key:ro
    secrets:
      - dot-env-secrets
    healthcheck:
      test: ["CMD", "nc", "-w", "1", "-z", "localhost", "443"]
      interval: 5s
      timeout: 2s
      retries: 5

secrets:
  dot-env-secrets:
    # Should include your SOCKET_API_KEY as an entry in dotenv format
    # Required scopes: packages, entitlements:list
    file: ./.env.secrets

Configuration Files

The proxy loads 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 (Docker secrets)

Verify service is functioning correctly

After standing up the service, you should confirm that the service is healthy and ready to filter network traffic from package managers.

You can accomplish this in the terminal:

curl -v \
  --proxy https://your-firewall-host:443 \
  --proxy-cacert path/to/socketFirewallCa.crt \
  --cacert path/to/socketFirewallCa.crt \
  https://registry.npmjs.org/lodash/-/lodash-1.0.0.tgz

You should make sure to pick a package URL that you know will be filtered based on your Socket org preferences.

If the CA is configured correctly, if the service is running, and if Socket determines the package should be blocked, you'll see output similar to the following:

* Host your-firewall-host:443 was resolved.
* IPv6: (none)
* IPv4: x.x.x.x
*   Trying x.x.x.x:443...
* Connected to your-firewall-host (x.x.x.x) port 443
* ALPN: curl offers http/1.1
* (304) (OUT), TLS handshake, Client hello (1):
*  CAfile: /path/to/socketFirewallCa.crt
*  CApath: none
* (304) (IN), TLS handshake, Server hello (2):
* (304) (IN), TLS handshake, Unknown (8):
* (304) (IN), TLS handshake, Certificate (11):
* (304) (IN), TLS handshake, CERT verify (15):
* (304) (IN), TLS handshake, Finished (20):
* (304) (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.3 / AEAD-AES256-GCM-SHA384 / [blank] / UNDEF
* ALPN: server accepted http/1.1
* Proxy certificate:
*  subject: CN=your-firewall-host
*  start date: Aug 24 02:02:23 2025 GMT
*  expire date: Aug 24 02:02:23 2026 GMT
*  subjectAltName: host "your-firewall-host" matched cert's "your-firewall-host"
*  issuer: CN=Socket Security CA; O=Socket Security
*  SSL certificate verify ok.
* CONNECT tunnel: HTTP/1.1 negotiated
* allocate connect buffer
* Establish HTTP proxy tunnel to registry.npmjs.org:443
> CONNECT registry.npmjs.org:443 HTTP/1.1
> Host: registry.npmjs.org:443
> User-Agent: curl/8.7.1
> Proxy-Connection: Keep-Alive
>
< HTTP/1.1 200 Connection Established
<
* CONNECT phase completed
* CONNECT tunnel established, response 200
* ALPN: curl offers h2,http/1.1
* (304) (OUT), TLS handshake, Client hello (1):
* (304) (IN), TLS handshake, Server hello (2):
* (304) (IN), TLS handshake, Unknown (8):
* (304) (IN), TLS handshake, Certificate (11):
* (304) (IN), TLS handshake, CERT verify (15):
* (304) (IN), TLS handshake, Finished (20):
* (304) (OUT), TLS handshake, Finished (20):
* SSL connection using TLSv1.3 / AEAD-CHACHA20-POLY1305-SHA256 / [blank] / UNDEF
* ALPN: server did not agree on a protocol. Uses default.
* Server certificate:
*  subject: CN=registry.npmjs.org
*  start date: Aug 24 02:08:28 2025 GMT
*  expire date: Aug 24 02:08:28 2026 GMT
*  subjectAltName: host "registry.npmjs.org" matched cert's "registry.npmjs.org"
*  issuer: CN=Socket Security CA; O=Socket Security
*  SSL certificate verify ok.
* using HTTP/1.x
> GET /lodash/-/lodash-1.0.0.tgz HTTP/1.1
> Host: registry.npmjs.org
> User-Agent: curl/8.7.1
> Accept: */*
>
* Request completely sent off
< HTTP/1.1 403 Forbidden
< Content-Type: text/plain
< Connection: close
< X-Block-Reason: npm package '[email protected]' was blocked
<
* Closing connection
Package blocked for violating organization security policy