Networking

Configure VM/runtime network capabilities and destination-based proxy routing using structured fields. Settings can be defined globally and overridden per-app or per-launch profile.

What You'll Learn

How to define network capabilities and proxy catalogs across global, app, and launch profile scopes
How proxy routing rules are evaluated, prioritized, and merged
Patterns for ZTNA egress, QUIC/DoH controls, and local egress proxy injection

Where to configure

Global (all launches): configuration.network (NetworkConfig)
Per-app (for that app’s launches): apps[].modifications.network (NetworkOverrides)
Per-launch profile (only when that launch profile is selected): apps[].profiles[].network (NetworkOverrides)

Support notes

Capabilities
- outboundAllowed, inboundAllowed, ports allow/deny, and TCP/UDP protocol gating are supported by the runtime.
- dnsAllowed, dnsServers, and dnsSearchSuffixes are supported when the runtime provides DNS control. If not supported by the environment, these are ignored safely.
- protocols: "tcp" and "udp" are supported. "icmp" may be runtime-dependent.
- egressDefaultAction is enforced by policy evaluation when no proxyRouting rule matches (ports/protocols still apply).
Proxies
- Proxy types supported in policy: "http", "https", and "socks5".
- HTTP/HTTPS proxies carry TCP streams. UDP through proxy is runtime-dependent; SOCKS5 may support UDP ASSOCIATE, but verify in your environment. Prefer direct routing for UDP unless validated.
- credentialsRef and tls.caBundleRef are opaque references; policy never contains secrets or raw PEM content.
- useTls: true wraps a SOCKS5 proxy connection in TLS (SOCKS5-over-TLS via stunnel, nginx stream, or similar). tlsSkipVerify: true skips certificate verification; use only on trusted networks with self-signed certs.
- resolveViaProxy: false tells the launcher this proxy cannot resolve hostnames — typical for internal SOCKS5 endpoints addressed by raw IP. When every eligible proxy for the selected site has resolveViaProxy: false, the launcher emits --disable-proxy-resolve-via-proxy and the client performs DNS locally. The launcher emits this flag before the CLI picks a single proxy from the fallback list, so proxies in the same routing group should agree; mixed groups keep the default of DNS-via-proxy.
- Site anchors: Site profiles can anchor to proxies via profiles[].anchor.proxyRef. See Sites.

Field reference

Global (NetworkConfig)

json

{
  "configuration": {
    "network": {
      "capabilities": {
        "outboundAllowed": true,
        "inboundAllowed": false,
        "dnsAllowed": true,
        "protocols": ["tcp", "udp"],
        "ports": { "allow": ["80", "443", "10000-10100"], "deny": ["25"] },
        "dnsServers": ["1.1.1.1", "2606:4700:4700::1111"],
        "dnsSearchSuffixes": ["corp.local"],
        "egressDefaultAction": "deny"
      },
      "proxies": [
        {
          "id": "corp-proxy",
          "type": "https",
          "url": "https://proxy.corp.local:8443",
          "credentialsRef": "corp-proxy-service-acct",
          "bypassHosts": [ { "pattern": "*.corp.local", "patternType": "glob" } ],
          "connectTimeoutMs": 5000,
          "tls": { "verify": true, "caBundleRef": "corp-root-bundle" }
        },
        {
          "id": "socks-exit",
          "type": "socks5",
          "url": "socks5://socks-gw.corp.local:1080",
          "credentialsRef": "socks-user",
          "useTls": true
        },
        {
          "id": "socks-internal-ip",
          "type": "socks5",
          "url": "socks5://10.0.0.20:1080",
          "credentialsRef": "socks-user",
          "resolveViaProxy": false
        }
      ],
      "proxyRouting": [
        {
          "id": "rfc1918-direct",
          "enabled": true,
          "priority": 900,
          "match": { "cidrs": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"] },
          "action": { "type": "direct" }
        },
        {
          "id": "cdn-direct",
          "enabled": true,
          "priority": 850,
          "match": {
            "hosts": [ { "pattern": "*.cdn.example.com", "patternType": "glob" } ],
            "ports": ["443"],
            "protocol": "tcp"
          },
          "action": { "type": "direct" }
        },
        {
          "id": "internet-via-proxy",
          "enabled": true,
          "priority": 800,
          "match": { "hosts": [ { "pattern": "*", "patternType": "glob" } ], "protocol": "tcp" },
          "action": { "type": "proxy", "proxyRef": "corp-proxy", "failover": "deny" }
        }
      ]
    }
  }
}

Per-app overrides (NetworkOverrides)

json

{
      "id": "sensitive-editor",
      "displayName": "Sensitive Editor",
      "enabled": true,
      "priority": 300,
      "matchAll": [
        { "type": "targetPath", "pattern": "**\\\\SensitiveEditor.exe", "patternType": "glob" }
      ],
      "action": "allow",
  "modifications": {
    "network": {
      "capabilities": { "egressDefaultAction": "deny" },
      "proxyRouting": [
        {
          "id": "vendor-api-direct",
          "enabled": true,
          "priority": 950,
          "match": {
            "hosts": [ { "pattern": "api.vendor.example", "patternType": "exact" } ],
            "ports": ["443"],
            "protocol": "tcp"
          },
          "action": { "type": "direct" }
        }
      ]
    }
  }
}

Per-launch profile overrides (NetworkOverrides)

json

{
  "id": "diagnostic-mode",
  "displayName": "Run (Diagnostic)",
  "network": {
    "capabilities": { "egressDefaultAction": "allow" }
  }
}

Credentials and secret storage

Do not embed secrets in policy. Use proxies[].credentialsRef to reference credentials stored by the client or enterprise tooling. The value is an opaque key resolved at runtime. See Variable Substitution for how to use these references securely.
For HTTPS proxies, enable certificate verification (tls.verify: true) and pin trust using tls.caBundleRef when required. See Security Best Practices.
Proxy performance data and user selections are maintained outside policy (see Proxy Settings); proxies.json persists latency measurements and selection but does not contain secrets.

Destination matching

hosts: Array of HostPatternSpec objects with pattern and patternType (glob recommended, e.g., "*.corp.local"). Case-insensitive.
cidrs: Array of IPv4/IPv6 CIDRs (e.g., "10.0.0.0/8", "2001:db8::/32").
ipRanges: Explicit from/to IP ranges.
ports: Array of PortSpec strings (single "443" or range "10000-10100").
protocol: "tcp" | "udp" | "icmp" (runtime support for icmp may vary).

Evaluation and precedence

Merge scopes: Global → App (Policy) → Launch Profile. For capabilities, booleans last-wins, arrays last-wins replacement, and the ports object replaces as a whole across scopes. Within a scope, ports.deny overrides ports.allow.
Choose a routing rule: Collect enabled rules from all scopes. For a connection, evaluate rules whose match passes; select highest priority (descending), then rule id alphabetical. Apply its action: proxy, direct, or deny.
- Deny short-circuits (connection is blocked).
- If action = proxy and the proxy endpoint fails, apply failover when present ("direct" or "deny"). Otherwise the connection fails.
Apply posture controls: Regardless of routing outcome, enforce outboundAllowed/inboundAllowed, protocol, and port constraints. If no rule matched, fall back to egressDefaultAction along with protocols/ports.

Local egress proxy pattern (header/tag injection)

To add headers or tags (e.g., an App-ID for a downstream device), route matching traffic to a local proxy that performs the injection, then forwards to the destination.
Define a loopback proxy and a routing rule targeting it:

json

{
  "proxies": [
    { "id": "local-egress", "type": "http", "url": "http://127.0.0.1:8080" }
  ],
  "proxyRouting": [
    {
      "id": "tag-sensitive-traffic",
      "enabled": true,
      "priority": 925,
      "match": { "hosts": [ { "pattern": "*.sensitive.example", "patternType": "glob" } ], "ports": ["443"], "protocol": "tcp" },
      "action": { "type": "proxy", "proxyRef": "local-egress", "failover": "deny" }
    }
  ]
}

The local proxy can inject headers (for example, X-App-Id) or adjust SNI before forwarding to the enterprise proxy or direct internet, according to your security tooling (e.g., Palo Alto Networks).

Identity-aware networking and ZTNA integration

ZTNA agents or sidecars are typically exposed as local or near-edge proxies (for example, https://127.0.0.1:8443 or a gateway host).
Model these components as entries in configuration.network.proxies and pin application egress to them using proxyRouting rules and NetworkOverrides.
Session-level and identity-centric decisions (user identity, device posture, and risk signals) are made by the ZTNA platform; the Launcher enforces which flows must traverse the ZTNA path and which are denied or allowed directly.
For sensitive applications, combine per-app network.capabilities.egressDefaultAction: "deny" with narrow allow rules so that any traffic not explicitly routed to the ZTNA proxy is blocked.

Example (ZTNA agent as local egress)

json

{
  "configuration": {
    "network": {
      "proxies": [
        {
          "id": "ztna-agent",
          "type": "https",
          "url": "https://127.0.0.1:8443"
        }
      ],
      "proxyRouting": [
        {
          "id": "internal-direct",
          "enabled": true,
          "priority": 900,
          "match": {
            "cidrs": ["10.0.0.0/8", "172.16.0.0/12"]
          },
          "action": { "type": "direct" }
        },
        {
          "id": "sensitive-app-via-ztna",
          "enabled": true,
          "priority": 800,
          "match": {
            "hosts": [
              { "pattern": "*.corpapps.example", "patternType": "glob" }
            ],
            "protocol": "tcp"
          },
          "action": { "type": "proxy", "proxyRef": "ztna-agent", "failover": "deny" }
        }
      ]
    }
  },
  "apps": [
    {
      "id": "sensitive-editor",
      "modifications": {
        "network": {
          "capabilities": {
            "egressDefaultAction": "deny"
          }
        }
      }
    }
  ]
}

Notes

Per-app and per-profile overrides allow you to require ZTNA for specific applications while leaving less sensitive apps on standard enterprise proxy paths.
Use identity-aware routing together with ABAC and Identity Access policy to align SSO and network enforcement.

Modern protocols: QUIC and secure DNS (DoH/DoT)

QUIC and HTTP/3 are UDP-based protocols (typically using port 443). They are governed by capabilities.protocols and the allowed port ranges in capabilities.ports.
To disable QUIC for all applications while keeping HTTPS over TCP, configure protocols to include only "tcp". This prevents all UDP traffic, including QUIC, from leaving the runtime.

Example (disable UDP/QUIC, allow HTTPS)

json

{
  "configuration": {
    "network": {
      "capabilities": {
        "outboundAllowed": true,
        "protocols": ["tcp"],
        "ports": {
          "allow": ["80", "443"],
          "deny": ["25"]
        },
        "egressDefaultAction": "deny"
      }
    }
  }
}

Secure DNS behavior

dnsAllowed, dnsServers, and dnsSearchSuffixes control classic DNS flows (typically UDP/TCP 53) when the runtime has DNS control.
DNS over HTTPS (DoH) and DNS over TLS (DoT) are carried as normal TLS/HTTPS traffic to resolver endpoints and are therefore governed by proxyRouting host/port/protocol matching and capabilities.

Common patterns

Enforce enterprise DNS or DoH:
- Disable direct DNS where required (dnsAllowed: false and/or deny port 53).
- Allow HTTPS egress only to enterprise resolver endpoints (for example, dns.corp.local) either directly or through an enterprise proxy.
Block consumer DoH/DoT resolvers:
- Add proxyRouting rules that match known consumer DNS endpoints by host and set action.type = "deny".

Example (enterprise DoH gateway with consumer DoH blocked)

json

{
  "configuration": {
    "network": {
      "capabilities": {
        "dnsAllowed": false,
        "protocols": ["tcp"],
        "ports": {
          "allow": ["443"],
          "deny": ["53"]
        },
        "egressDefaultAction": "deny"
      },
      "proxyRouting": [
        {
          "id": "block-consumer-doh",
          "enabled": true,
          "priority": 950,
          "match": {
            "hosts": [
              { "pattern": "*.dns.google", "patternType": "glob" },
              { "pattern": "mozilla.cloudflare-dns.com", "patternType": "exact" }
            ]
          },
          "action": { "type": "deny" }
        },
        {
          "id": "enterprise-doh",
          "enabled": true,
          "priority": 900,
          "match": {
            "hosts": [
              { "pattern": "dns.corp.local", "patternType": "exact" }
            ],
            "ports": ["443"],
            "protocol": "tcp"
          },
          "action": { "type": "proxy", "proxyRef": "corp-proxy", "failover": "deny" }
        }
      ]
    }
  }
}

Notes

There is no special DoH/DoT object in the schema; DNS resolver control is expressed via capabilities (protocols/ports/DNS settings) and proxyRouting host/port rules.
When QUIC is disabled via protocols, HTTP/3 falls back to HTTP/2 or HTTP/1.1 over TCP, so proxy and inspection behavior remains deterministic.

Forward compatibility

To support future vendor-specific options without breaking existing policies, the schema may introduce opaque extension bags on proxies and routing actions (e.g., proxies[].extensions and proxyRouting[].action.extensions). Until then, prefer the local egress proxy pattern above for per-flow tagging.

Semantics and precedence (summary)

Scope precedence: Launch Profile > Policy (App) > Global.
Capabilities:
- Booleans last-wins by scope (e.g., outboundAllowed, inboundAllowed, dnsAllowed).
- Arrays (protocols, dnsServers, dnsSearchSuffixes) last-wins by scope (replacement).
- ports.allow/ports.deny: within a scope, deny overrides allow at evaluation time; across scopes, last-wins replacement of the entire ports object.
- egressDefaultAction: last-wins by scope.
Proxy catalog (proxies[]): defined globally only at configuration.network.proxies. App/profile scopes reference proxies via proxyRef and cannot define new proxies.
Proxy routing rules:
- Rules are additive across scopes.
- For a connection: evaluate enabled rules whose match passes; choose the rule with highest priority (descending), then rule id alphabetical. Apply its action (proxy/direct/deny). Deny short-circuits. If action = proxy and the proxy endpoint fails, apply failover when present.

Cross-references

Schema Reference → NetworkConfig, NetworkOverrides, Proxy, ProxyRoutingRule, NetworkCapabilities
Security Best Practices → Network hardening, credentialsRef, tls.caBundleRef, QUIC/DoH/DoT patterns
Troubleshooting → Proxy testing and proxies.json
Variable Substitution → Variable Substitution

Networking ​

Networking