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.

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-runners"],
  "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

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 also include managed rulesets for GitHub Actions runners, Devboxes, and macOS. Namespace keeps these rulesets current as workload requirements change.

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 instances created through the Compute API and GitHub Actions runner profiles.

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.

You can also configure it from the CLI:

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

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.