ts network-rule

Show and manage a network access rule: an allow, read-only, or deny decision for the hosts a session connects to. Use it to script the allow-list that the Administration site edits under Workspaces → Policy, on the Network tab.

Usage

ts network-rules [--csv] [--no-trunc]
ts network-rule <id>
ts network-rule <id> <property>
ts network-rule new --file=<path>
ts network-rule set <id> <property> <value>
ts network-rule set <id> --file=<path>
ts network-rule delete <id> [--force]

Description

A rule matches destinations by host name, through its own hosts and the destination classes it names in classes, optionally only on some ports, and applies its action. Rules are evaluated from the highest priority down, and the first rule whose host and port match decides. A connection no rule matches gets the Default Action on the Network tab, configuration.network.capabilities.egressDefaultAction in ts policy. Every network access rule is evaluated before any routing rule. The macOS client and the Windows sandbox service enforce the rules per connection.

ts network-rules lists each rule's name, action, destinations (classes, then hosts), ports, priority, whether it is enabled, and its ID; an allow rule that routes through a proxy shows as allow via <proxy>. Every singular form takes the ID. A new server starts with rules named launch-… that deny paste, file-drop, and tunnel services and allow what a sandboxed project needs to build; you can change or delete them like any other.

The Document

{
  "id": "4b8e2f1a-9c3d-4e7f-a6b5-0d1c2e3f4a5b",
  "name": "corp-mirrors",
  "enabled": true,
  "priority": 600,
  "description": "Internal Git and package mirrors, through the office proxy.",
  "hosts": ["git.corp.example.com", "*.pkg.example.com"],
  "classes": [],
  "ports": ["443"],
  "action": "allow",
  "proxyRef": "hq-socks"
}

• name — Letters, digits, ., _, and -, up to 128 characters, unique ignoring case. It appears in connection audit records and cannot change after the rule is created.
• enabled — A disabled rule is kept but not served. Defaults to true.
• priority — 0 to 9999, highest first. Defaults to 500.
• hosts — Host names. One containing * is a wildcard, and *.example.com does not match example.com itself. A URL, a host with a port, or a wildcard that could match any name (*, example.*) is refused. In a read rule, host/path/ limits an exact host to a path, such as storage.googleapis.com/example-builds/.
• classes — Destination class keys, built-in or your own. The server expands them into hosts when it serves the policy. A rule needs at least one host or class.
• ports — Ports, or ranges such as 8000-8100. Empty matches every port. The Windows sandbox service supports single ports only.
• action — allow, read, or deny, and required. read lets data in and limits what a connection sends; Windows applies it as allow. The built-in sharedHosting class can only be denied.
• proxyRef — For an allow rule, the key of a proxy to route through instead of connecting directly; null connects directly. A read or deny rule cannot have one.

id is ignored on write, so new with a printed document and a new name makes a copy.

Reading and Writing

ts network-rule <id> prints the document as the server sends it, compact on one line, and set --file takes the same shape back, so print, edit, and set is a faithful round trip. new and set read the document from --file; - reads standard input. A whole-document set replaces every field, and a field the document leaves out takes its default.

ts network-rule <id> <property> reads one field, and set <id> <property> <value> writes one and leaves the rest as it was. Properties are the document's fields, in kebab case or as written (proxy-ref or proxyRef), and a value takes the type of the field it replaces. hosts, classes, and ports are lists, which only --file changes. After an accessor write, ts reads the field back and fails if the server kept another value, so clear proxyRef by setting it to null with --file.

new prints only Created network access rule; find the new ID with ts network-rules, or under --format=json as result.entity.id. delete confirms first, and reports success even when no rule has the ID. Creating, changing, and deleting a rule are recorded in the audit log. Every form, reading included, needs a Server Administrator.

WARNING

The server saves a rule the Windows sandbox service cannot enforce, and that service refuses a sandboxed launch rather than ignore the rule. After a change, open the Network tab: it warns when the Windows sandbox service would refuse sandboxed launches under the policy.

Options

Flag	Description	Default/Values	Notes
--file	JSON document to send.	PATH, or - for standard input	Required by new. set needs it only for the whole-document form.
--force, -f	Delete without confirming.		delete only. Required when there is no terminal.
--csv	Tab-separated output, nothing truncated.		ts network-rules only.
--no-trunc	Do not truncate columns.		ts network-rules only.

Examples

# The allow-list, highest priority first
ts network-rules

# One rule, formatted for reading
ts network-rule 4b8e2f1a-9c3d-4e7f-a6b5-0d1c2e3f4a5b | jq .

# Allow internal mirrors through the office proxy, ahead of the default rules
cat <<'JSON' | ts network-rule new --file=-
{ "name": "corp-mirrors", "priority": 600,
  "hosts": ["git.corp.example.com", "*.pkg.example.com"], "ports": ["443"],
  "action": "allow", "proxyRef": "hq-socks" }
JSON

# Let sessions download one bucket's builds, read only
cat <<'JSON' | ts network-rule new --file=-
{ "name": "read-example-builds", "hosts": ["storage.googleapis.com/example-builds/"],
  "ports": ["443"], "action": "read" }
JSON

# Take a rule out of service without losing it
ts network-rule set 4b8e2f1a-9c3d-4e7f-a6b5-0d1c2e3f4a5b enabled false

# Add a host: hosts is a list, so edit the document
ts network-rule 4b8e2f1a-9c3d-4e7f-a6b5-0d1c2e3f4a5b | jq . > rule.json
$EDITOR rule.json
ts network-rule set 4b8e2f1a-9c3d-4e7f-a6b5-0d1c2e3f4a5b --file=rule.json

# Remove a rule
ts network-rule delete 4b8e2f1a-9c3d-4e7f-a6b5-0d1c2e3f4a5b --force

# A whole-document set replaces every field. This document leaves out enabled,
# priority, ports, and proxyRef, so the rule comes back enabled, at priority
# 500, on every port, connecting directly.
echo '{ "hosts": ["git.corp.example.com"], "action": "allow" }' \
  | ts network-rule set 4b8e2f1a-9c3d-4e7f-a6b5-0d1c2e3f4a5b --file=-

Output

A server that still has the rules it started with lists them like this, untruncated. In a narrow terminal the widest columns are shortened with ..., the ID among them; --no-trunc or --csv prints them whole.

NAME                       ACTION  DESTINATIONS                                                                         PORTS   PRIORITY  ENABLED  ID
launch-block-exfiltration  deny    exfiltration                                                                                 900       yes      0c4f6a2e-8b1d-4e3a-9f57-2d6c8e0a1b34
launch-certificate-checks  allow   certificateAuthority                                                                 80,443  500       yes      5a9e3c71-2f4b-4d8e-a613-7b0c9d2e4f58
launch-defaults            allow   modelApi,agentService,packageRegistry,containerRegistry,toolchainDownload,gitRemote  443     500       yes      91d2b7e4-6c3a-4f15-8e29-c4a0f1d3b6e7
launch-git-ssh             allow   gitRemote                                                                            22      500       yes      2e7f0a5c-4d19-4b6e-bc83-1f9a6d2c7e40
launch-reference-reads     read    reference                                                                            443     500       yes      d6b31f8a-0e52-47c9-9a4d-3c8e7b1f2a96

A single-field read prints the bare value, 500 or true, and a list as JSON.

Exit Codes

0 on success, including a delete of an ID no rule has. -1 when the server refuses the document: a missing, malformed, taken, or changed name, a priority out of range, no hosts or classes, a host that is not a host name, a path outside a read rule, an unknown class or proxy, a proxyRef on a read or deny rule, a missing or unknown action, or a port that is not one. -1 also when an accessor write reads back another value, and when you decline the delete prompt. -2 when the accessor names a list, and when set is given both a property and --file. -4 when no account is signed in. -5 when the account is not a Server Administrator. -6 when the ID is not a GUID or no rule has it, when the --file path does not exist, and when a property is not a field of the document.

Related Commands

• ts destination-class — The named host sets a rule's classes name.
• ts proxy — The proxies an allow rule's proxyRef routes through.
• ts routing-rule — Proxy routing, evaluated after every network access rule.
• ts policy — The launch policy, which holds the default action for unmatched connections.
• ts audit — Who changed the allow-list, and when.