Egress policies

Egress policies control outbound connections from your workloads. Use them to filter traffic, inject Vault secrets into requests, or route traffic through another domain.

Filter

Control egress traffic

Inject secrets

Protect credentials

Proxy

Route through another domain

Create an egress policy

Define the policy’s tag, mode, rules, managed rulesets, and deep packet inspection setting in a JSON configuration file. For example, the following policy allows the traffic required by GitHub Actions, plus requests to example.com. It also injects a Vault secret into the Authorization header for requests to example.com:

{
  "tag": "your-network-policy",
  "description": "CI with access to example.com",
  "mode": "BLOCK",
  "deep_packet_inspection": true,
  "additional_rulesets": ["github-actions"],
  "rules": [
    {
      "op": "ALLOW",
      "matcher": {
        "match_domains": ["example.com"]
      }
    },
    {
      "op": "INJECT",
      "matcher": {
        "match_domains": ["example.com"]
      },
      "inject": {
        "header_name": "Authorization",
        "from_secret_id": "sec_example"
      }
    }
  ]
}

Save the configuration as egress-policy.json, then create the policy:

nsc egress policy create --spec_file egress-policy.json

The nsc egress policy commands require nsc v0.0.554 or later.

See nsc egress policy create for configuration field descriptions.

Rules

Rules are evaluated in order and apply to matching domains.

Filter traffic

ALLOW rules permit requests to matching domains. In BLOCK mode, the policy denies all requests that are not allowed.

{
  "op": "ALLOW",
  "matcher": {
    "match_domains": ["example.com"]
  }
}

Policies can additionally include managed rulesets for GitHub Actions runners, Devboxes, and macOS workloads. Namespace keeps these rulesets current as workload requirements change. Use the github-actions ruleset for GitHub Actions runners and the devbox ruleset for Devboxes so the policy allows the traffic required for their functionality. The optional macos ruleset permits routine connections from macOS to Apple services. macOS workloads can operate without it, but recurring denied requests to these services can add noise to the egress logs and make other relevant entries more difficult to identify.

Inject secrets

INJECT rules set an HTTP header to a value from Namespace Vault. The secret is resolved outside the workload and its value is never exposed to it. INJECT requires deep packet inspection.

{
  "op": "INJECT",
  "matcher": {
    "match_domains": ["example.com"]
  },
  "inject": {
    "header_name": "Authorization",
    "from_secret_id": "sec_example"
  }
}

Proxy traffic

PROXY rules route matching outbound HTTP traffic through another domain instead of connecting to the destination directly. Set proxy.via_domain to the domain that should proxy those connections. PROXY requires deep packet inspection.

{
  "op": "PROXY",
  "matcher": {
    "match_domains": ["example.com"]
  },
  "proxy": {
    "via_domain": "proxy.example.com"
  }
}

Start in advisory mode

{
  "tag": "your-network-policy",
  "description": "CI with access to example.com",
  "mode": "ADVISORY",

Use ADVISORY mode to evaluate and record the same policy decisions as BLOCK mode without denying requests. Review the per-instance egress traffic, add any required domains, and then update mode to BLOCK. This avoids unexpectedly breaking a workload while building its allow-list from real traffic.

nsc egress policy update your-network-policy --spec_file egress-policy.json

Use an egress policy

Workspace policies can be reused across GitHub Actions runner profiles, Devboxes, and instances created through the Compute API.

GitHub Actions runner profiles

Apply an egress policy to GitHub Actions runners through a runner profile. Open the profile in the web UI and select a workspace policy in its network policy settings. The selected policy applies to every runner created from that profile.

Include the github-actions additional ruleset in policies used with GitHub Actions runners. It allows the traffic required for runner functionality.

You can also configure it from the CLI:

nsc github profile create \
  --tag "runner-with-policy" \
  --egress_policy_tag "your-network-policy"

Devboxes

Apply an egress policy to Devboxes through a blueprint. Open the blueprint in the web UI and select a workspace policy in its network policy settings. The selected policy applies to every Devbox created from that blueprint.

Include the devbox additional ruleset in policies used with Devboxes. It allows the traffic required for Devbox functionality.

Compute API

To apply a policy per instance, set network_policy.egress_policy_tag on the CreateInstance request. The tag must identify a policy in the instance’s workspace and is mutually exclusive with an inline network_policy.egress configuration. See the CreateInstanceRequest.NetworkPolicy API reference for the complete schema.

Observe egress traffic

Workspace traffic

Namespace records outbound policy decisions and shows them in the Egress Filtering dashboard. Requests are grouped by base domain and split into Allowed and Denied, so you can confirm that required destinations are reachable and spot unexpected traffic. You can also inspect decisions with nsc egress logs.

Per-instance egress traffic

The workspace dashboard aggregates traffic across all workloads. To inspect a single workload, open the instance and select its Egress tab. The per-instance view lists allowed and denied requests.

Products

Platform

Administration

Filter

Inject secrets

Proxy

Create an egress policy

Rules

Filter traffic

Inject secrets

Proxy traffic

Start in advisory mode

Use an egress policy

GitHub Actions runner profiles

Devboxes

Compute API

Observe egress traffic

Workspace traffic

Per-instance egress traffic

Filter

Inject secrets

Proxy

​Create an egress policy

​Rules

​Filter traffic

​Inject secrets

​Proxy traffic

​Start in advisory mode

​Use an egress policy

​GitHub Actions runner profiles

​Devboxes

​Compute API

​Observe egress traffic

​Workspace traffic

​Per-instance egress traffic

Create an egress policy

Rules

Filter traffic

Inject secrets

Proxy traffic

Start in advisory mode

Use an egress policy

GitHub Actions runner profiles

Devboxes

Compute API

Observe egress traffic

Workspace traffic

Per-instance egress traffic