Organization network access policies

Network access policies are organization policies that control outbound connections from sandboxes. When an organization policy is enforced for a developer, their sandboxes can reach only the destinations your network rules allow. Each policy contains one or more rules that allow the hosts, IP ranges, and ports a workflow needs, or block destinations that should stay unavailable. Rules can also match the HTTP method and path of a request, so a policy can allow part of an API without allowing all of it.

Developers can also add network rules on their own machines with local policy, but under an enforced organization policy, only your allow rules grant access. For more details, see How organization policy relates to local and kit rules.

For destinations you want a person to confirm, a policy can require approval instead of granting access outright. This page explains what a rule can match, how approval works, and when your changes reach developers. To create a network access policy, see Create and manage organization policies.

What a network rule can match

Each rule has an optional Rule name, a Type that decides what the rule matches, and a Decision of Allow or Deny. The type is either All traffic, which covers whole destinations, or HTTP, which covers specific requests to one destination.

All traffic rules

An All traffic rule matches every request to the destinations you list, on any port, method, and path.

• Under Protocols, select TCP, UDP, or Both.
• Under Destinations, add the hosts, IP addresses, or CIDR ranges the rule covers. A destination matches any port unless you add one, such as example.com:8080.

HTTP rules

An HTTP rule matches only HTTP requests with the methods and paths you specify.

• In Destination, enter the host or IP address the rule covers. It matches any port unless you add one. Enter the destination with no scheme and no path, so api.github.com rather than https://api.github.com/repos.
• Under HTTP methods, select the methods the rule applies to. Use Select all to select every method, or Read-only to select GET, HEAD, and OPTIONS. Select at least one method. A rule with no methods selected fails validation. The composer doesn't list CONNECT or TRACE, which differs from the CLI, where --method ANY matches every HTTP method.
• Under Path patterns, add one or more paths the rule covers, such as /repos/* and /v1/**. Leave it empty to match any path.

An HTTP rule's paths all belong to its one destination, so to cover paths on a second host, add a second rule. For the pattern syntax and how HTTP rules combine with All traffic rules, see HTTP rules.

Approval-required access

A network access policy can require approval instead of granting access outright. Destinations the policy allows aren't reachable until the developer confirms them, which keeps an allowlist broad enough to be usable while still putting a person in front of each destination an agent reaches for. To turn it on when you create or edit a policy, see Create and manage organization policies.

In an organization policy, approval is a property of the policy rather than of individual rules, so turning it on applies it to every allow rule in that policy. A destination stays directly reachable only when no policy that allows it requires approval. If a policy that requires approval also matches, the request needs approval regardless of what the other policies allow.

A request is handled as follows:

flowchart TD
  request["Sandbox sends an outbound request"] --> denied{"Does any deny rule match?"}
  denied -->|"Yes, from any source"| block["Block request"]
  denied -->|"No"| orgallow{"Does an organization policy allow it?"}
  orgallow -->|"No"| block
  orgallow -->|"Yes"| needs{"Does any allowing policy require approval?"}
  needs -->|"No"| allow["Allow request"]
  needs -->|"Yes"| approved{"Did the developer already approve this destination?"}
  approved -->|"Yes"| allow
  approved -->|"No"| ask["Block request and ask the developer to approve"]
  ask -.->|"Later requests after approval"| allow

Only a destination the developer has already approved satisfies the requirement. Preset rules, kit rules, and rules the developer added with sbx policy allow network don't answer it. An approval also can't reach a destination the organization doesn't allow at all, and it can't override a deny rule. To withdraw a destination, add a deny rule, which takes precedence over any approval already recorded.

Developers respond to approval requests from the command line. For what they see and how they respond, see Respond to approval requests.

When changes take effect

Network policy is evaluated on every outbound request. Once a policy change has synced to the developer's machine, it applies immediately to subsequent requests.

An approval requirement applies from the point the policy change syncs. Destinations a developer already approved stay reachable, because the approval is recorded on the developer's machine.