Network Policy - Upstash Documentation

Network policies control outbound network access from a box.

Use them when you want to:

block all outbound traffic
allow only specific public domains
restrict egress to specific CIDR ranges

By default, boxes use:

{ mode: "allow-all" }

{"mode": "allow-all"}

Modes#

Mode	Description
`allow-all`	Default. No outbound restrictions.
`deny-all`	Block all outbound network access.
`custom`	Allowlist. Only the listed domains and CIDR ranges are reachable, minus any `deniedCidrs`. Everything else is blocked.

The SDK type is:

type NetworkPolicy =  | { mode: "allow-all" | "deny-all" }  | {      mode: "custom"      allowedDomains?: string[]      allowedCidrs?: string[]      deniedCidrs?: string[]    }

from typing import Literal, TypedDict, Unionfrom typing_extensions import NotRequiredclass AllowDenyNetworkPolicy(TypedDict):    mode: Literal["allow-all", "deny-all"]class CustomNetworkPolicy(TypedDict):    mode: Literal["custom"]    allowed_domains: NotRequired[list[str]]    allowed_cidrs: NotRequired[list[str]]    denied_cidrs: NotRequired[list[str]]NetworkPolicy = Union[AllowDenyNetworkPolicy, CustomNetworkPolicy]

Create a box with a policy#

Pass networkPolicy when creating a box:

import { Box } from "@upstash/box"const box = await Box.create({  runtime: "node",  networkPolicy: {    mode: "custom",    allowedDomains: ["api.github.com", "registry.npmjs.org"],  },})

from upstash_box import Boxbox = Box.create(    runtime="node",    network_policy={        "mode": "custom",        "allowed_domains": ["api.github.com", "registry.npmjs.org"],    },)

You can also combine domain and CIDR rules:

const box = await Box.create({  runtime: "node",  networkPolicy: {    mode: "custom",    allowedDomains: ["api.github.com", "*.githubusercontent.com"],    allowedCidrs: ["104.16.0.0/12"],  },})

box = Box.create(    runtime="node",    network_policy={        "mode": "custom",        "allowed_domains": ["api.github.com", "*.githubusercontent.com"],        "allowed_cidrs": ["104.16.0.0/12"],    },)

networkPolicy is also supported in Box.fromSnapshot() and EphemeralBox. A box restored from a snapshot does not inherit the source box’s policy, so pass it again on restore.

Read the current policy#

Use the networkPolicy getter:

console.log(box.networkPolicy) // { mode: "allow-all" }

print(box.network_policy)  # {"mode": "allow-all"}

Update a running box#

Update the policy after creation:

await box.updateNetworkPolicy({ mode: "deny-all" })

box.update_network_policy({"mode": "deny-all"})

Switch back to unrestricted outbound access:

await box.updateNetworkPolicy({ mode: "allow-all" })

box.update_network_policy({"mode": "allow-all"})

Changes take effect immediately. You do not need to recreate the box. updateNetworkPolicy() is not available on EphemeralBox.

Matching rules#

custom mode is default-deny: a destination is reachable only if its domain is in allowedDomains or its resolved IP is in allowedCidrs
allowedDomains supports exact matches such as api.github.com and must be lowercase
wildcard domains must use *.suffix form, for example *.githubusercontent.com. *.github.com does not match github.com itself
allowedCidrs and deniedCidrs use standard CIDR notation
deniedCidrs only removes addresses from what is allowed. A resolved IP in a denied range is blocked even when its domain is in allowedDomains. A custom policy with only deniedCidrs blocks everything
private IP ranges are always blocked even if you try to allow them explicitly

Example patterns#

Allow only GitHub and npm:

await box.updateNetworkPolicy({  mode: "custom",  allowedDomains: ["github.com", "*.github.com", "registry.npmjs.org"],})

box.update_network_policy({    "mode": "custom",    "allowed_domains": ["github.com", "*.github.com", "registry.npmjs.org"],})

Block all outbound traffic:

await box.updateNetworkPolicy({ mode: "deny-all" })

box.update_network_policy({"mode": "deny-all"})

Allow a specific public CIDR:

await box.updateNetworkPolicy({  mode: "custom",  allowedCidrs: ["104.16.0.0/12"],})

box.update_network_policy({    "mode": "custom",    "allowed_cidrs": ["104.16.0.0/12"],})

Allow a CIDR range except for a sub-range:

await box.updateNetworkPolicy({  mode: "custom",  allowedCidrs: ["104.16.0.0/12"],  deniedCidrs: ["104.16.120.0/24"],})

box.update_network_policy({    "mode": "custom",    "allowed_cidrs": ["104.16.0.0/12"],    "denied_cidrs": ["104.16.120.0/24"],})