Socket - Formal Documentation

Overview

A Socket resource routes package manager traffic through a Socket Registry Firewall. Formal applies access policies and sends matching registry requests to the firewall, which retrieves packages from the upstream registry.

package manager  →  Formal  →  Socket Registry Firewall  →  origin registry

Configure the Socket Registry Firewall

Configure the firewall to use path routing. Formal maps each supported package registry to the corresponding path:

Ecosystem	Recognized hostnames	Expected `path` in `socket.yml`	Example rewrite
npm	`registry.npmjs.org`, `registry.npmjs.com`, `registry.yarnpkg.com`	`/npm`	`registry.npmjs.org/lodash` → `/npm/lodash`
PyPI	`pypi.org`, `pypi.python.org`, `files.pythonhosted.org`	`/pypi`	`pypi.org/simple/numpy/` → `/pypi/simple/numpy/`
Maven	`repo1.maven.org`, `repo.maven.apache.org`	`/maven`	`repo1.maven.org/maven2/org/foo` → `/maven/org/foo`
Cargo	`crates.io`, `index.crates.io`, `static.crates.io`	`/cargo`	`crates.io/api/v1/crates/serde/...` → `/cargo/api/v1/crates/serde/...`
RubyGems	`rubygems.org`, `index.rubygems.org`, `bundler.rubygems.org`	`/rubygems`	`rubygems.org/gems/rake-13.0.6.gem` → `/rubygems/gems/rake-13.0.6.gem`
OpenVSX	`open-vsx.org`, `openvsx.eclipsecontent.org`, `openvsxorg.blob.core.windows.net`	`/openvsx`	`open-vsx.org/api/...` → `/openvsx/api/...`
NuGet	`api.nuget.org`, `www.nuget.org`, `packages.nuget.org`, `globalcdn.nuget.org`	`/nuget`	`api.nuget.org/v3/...` → `/nuget/v3/...`
Go	`proxy.golang.org`	`/go`	`proxy.golang.org/github.com/...` → `/go/github.com/...`
conda	`repo.anaconda.com`	`/conda`	`repo.anaconda.com/pkgs/main/linux-64/...` → `/conda/linux-64/...`

Add a route for each ecosystem you want to proxy:

path_routing:
  enabled: true
  domain: sfw.your_company.com
  routes:
    - path: /npm
      upstream: https://registry.npmjs.org
      registry: npm
    - path: /pypi
      upstream: https://pypi.org
      registry: pypi
    - path: /maven
      upstream: https://repo1.maven.org/maven2
      registry: maven

Formal supports only Socket’s recommended path for each registry.

Create a Socket Resource

Create a socket using the firewall’s hostname and port:

resource "formal_resource" "socket_firewall" {
  name       = "socket-registry-firewall"
  technology = "socket"
  hostname   = "sfw.your_company.com"
  port       = 8443
}

Configure Resource TLS

Formal must trust the certificate presented by the Socket Registry Firewall. Export the CA certificate that issued the firewall’s server certificate. If the server certificate is self-signed, export that certificate instead. In the Formal Console, add a TLS configuration to the Socket resource, select Verify Full, and add the PEM-encoded certificate to the CA trust store. With Terraform, use a formal_resource_tls_configuration resource:

resource "formal_resource_tls_configuration" "socket_firewall" {
  resource_id       = formal_resource.socket_firewall.id
  tls_config        = "verify-full"
  tls_min_version   = "TLSv1.2"
  tls_ca_truststore = file("${path.module}/socket-firewall-ca.pem")
}

The firewall certificate must include the resource hostname in its subject alternative names. This TLS configuration is used for direct Endpoint connections and Connector connections. Connectors also use it when running resource health checks. See Resource TLS Configuration for the available verification modes. If the firewall requires authentication, configure a Bearer Token Native User.

Native User authentication is supported only when Socket traffic is routed through a Formal Connector.

Route Package Manager Traffic

Create a network rule from the Socket Registry Firewall template. Select the Socket resource, replace sfw.your_company.com with the firewall hostname, and keep only the ecosystems configured in the firewall:

{
  "condition": {
    "pre_tls": (socket_ecosystem in ["npm", "pypi"] && !connection_process.is_browser) || hostname == "sfw.your_company.com",
    "post_tls": true
  },
  "outputs": {
    "resource_name": "socket-registry-firewall"
  }
}

The ecosystem condition intercepts requests to public package registries. The hostname condition intercepts package download URLs returned by the firewall. The browser exclusion prevents ordinary browser traffic to public registry websites from matching the rule.

Route Every Supported Ecosystem

Use the Socket Registry Firewall (All) template when socket.yml configures every ecosystem listed above. The is_socket_ecosystem input matches any hostname recognized as a supported Socket registry. Replace sfw.your_company.com with your firewall hostname:

{
  "condition": {
    "pre_tls": (is_socket_ecosystem && !connection_process.is_browser) || hostname == "sfw.your_company.com",
    "post_tls": true
  },
  "outputs": {
    "resource_name": "socket-registry-firewall"
  }
}

This template matches all supported Socket ecosystems. Do not use this template if your Socket firewall does not opt in to all supported ecosystems. Use the selective Socket Registry Firewall template instead.

Without a Connector

Use this mode when each workstation running the Formal Endpoint can reach the Socket Registry Firewall directly:

Install and enable the Formal Endpoint transparent proxy.
Make the firewall hostname resolvable and reachable from the workstation.
Select the Socket resource in the network rule.
Leave Forward To Connector disabled ("forward_to_connector": false).

Traffic follows this path:

package manager  →  Formal Endpoint  →  Socket Registry Firewall

The Formal Endpoint does not apply Native User credentials in this mode. The firewall must accept the Endpoint’s requests without Native User authentication.

With a Connector

Use this mode when the firewall is reachable only from the network where a Formal Connector runs, or when the firewall requires authentication from package manager clients.

Create a listener on the Connector.
Add a listener rule that points to the Socket resource.
Enable Forward To Connector in the network rule ("forward_to_connector": true).

For example:

resource "formal_connector_listener" "socket_firewall" {
  connector_id = formal_connector.example.id
  name         = "socket-registry-firewall"
  port         = 9443
}

resource "formal_connector_listener_rule" "socket_firewall" {
  connector_listener_id = formal_connector_listener.socket_firewall.id
  type                  = "resource"
  rule                  = formal_resource.socket_firewall.id
}

The listener port is the port used to reach the Connector and does not need to match the firewall resource port. Traffic follows this path:

package manager  →  Formal Endpoint  →  Formal Connector  →  Socket Registry Firewall

Policy Evaluation

Socket’s response headers are available to response policies through input.socket. For example, the following policy blocks a request when the firewall reports a fail-open decision:

package formal.v2

post_request := {
  "action": "block",
  "type": "block_with_formal_message",
  "reason": "Socket fail-open is not allowed",
} if {
  input.socket.decision == "fail_open"
}

Socket Policy Input

input.socket can contain the following fields:

Field	Type	Description
`ecosystem`	string	Package ecosystem for a public registry request
`decision`	string	Socket decision: `allowed`, `blocked`, `fail_open`, or `forbidden`
`request_id`	string	Socket request identifier
`block_reasons`	array of strings	Reasons Socket blocked the package
`warn_reasons`	array of strings	Reasons Socket warned about the package
`monitor_reasons`	array of strings	Reasons Socket marked the package for monitoring
`ignore_reasons`	array of strings	Reasons Socket ignored findings
`unscanned`	boolean	Whether Socket skipped scanning the artifact

ecosystem is available when Formal classifies a supported public registry.

Limitations

Socket resources use the fixed path prefixes listed above. Custom path prefixes, domain-based routing, and Artifactory auto-discovery mode are not supported.
Socket response bodies stream through Formal to the package manager and are not available to response-body policies. Response header rewrites and blocks remain supported.

​Overview

​Configure the Socket Registry Firewall

​Create a Socket Resource

​Configure Resource TLS

​Route Package Manager Traffic

​Route Every Supported Ecosystem

​Without a Connector

​With a Connector

​Policy Evaluation

​Socket Policy Input

​Limitations

Overview

Configure the Socket Registry Firewall

Create a Socket Resource

Configure Resource TLS

Route Package Manager Traffic

Route Every Supported Ecosystem

Without a Connector

With a Connector

Policy Evaluation

Socket Policy Input

Limitations