Networking

import { NetworkPolicy, Sandbox } from "microsandbox";

const policy = NetworkPolicy.builder()           // 1. compose a policy
  .defaultDeny()
  .egress((e) => e.tcp().port(443).allowPublic())
  .rule((r) => r.any().deny((d) => d.ip("198.51.100.5")))
  .build();

const sb = await Sandbox.builder("api")
  .image("python")
  .network((n) =>
    n                                            // 2. wire it into the sandbox
      .policy(policy)
      .port(8080, 80)
      .dns((d) => d.rebindProtection(true)),
  )
  .create();

import { NetworkPolicy, Rule, Destination } from "microsandbox";

// Custom policy literal
const custom: NetworkPolicy = {
  defaultEgress: "deny",
  defaultIngress: "allow",
  rules: [
    Rule.allowEgress(Destination.domain("api.example.com")),
    Rule.denyEgress(Destination.group("metadata")),
  ],
};

// Or via the builder
const built = NetworkPolicy.builder()
  .defaultDeny()
  .egress((e) => e.tcp().port(443).allowPublic())
  .build();

const policy: NetworkPolicy = {
  defaultEgress: "deny",
  defaultIngress: "allow",
  rules: [
    Rule.allowEgress(Destination.cidr("10.0.0.0/8")),  // matches everything in 10.x
    Rule.denyEgress(Destination.cidr("10.0.0.5/32")),  // never reached
  ],
};

WARN rule #1 (Egress Cidr(10.0.0.5/32) Deny) is shadowed by rule #0 (Egress Cidr(10.0.0.0/8) Allow); to narrow, place the more specific rule first

builder(): NetworkPolicyBuilder

none(): NetworkPolicy

allowAll(): NetworkPolicy

fromProfiles(profiles: Iterable<NetworkProfile>): NetworkPolicy

allowEgress(destination: Destination): Rule

denyEgress(destination: Destination): Rule

allowIngress(destination: Destination): Rule

denyIngress(destination: Destination): Rule

allowAny(destination: Destination): Rule

denyAny(destination: Destination): Rule

allowDns(): Rule

denyDns(): Rule

any(): Destination

cidr(cidr: string): Destination

domain(domain: string): Destination

domainSuffix(suffix: string): Destination

group(group: DestinationGroup): Destination

single(port: number): PortRange

range(start: number, end: number): PortRange

policy(policy: NetworkPolicy | NetworkPolicyBuilder): this

port(host: number, guest: number): this

portBind(bind: string, host: number, guest: number): this

portUdp(host: number, guest: number): this

portUdpBind(bind: string, host: number, guest: number): this

dns(configure: (b: DnsBuilder) => DnsBuilder): this

tls(configure: (b: TlsBuilder) => TlsBuilder): this

trustHostCAs(enabled: boolean): this

maxConnections(max: number): this

ipv4Pool(pool: string): this

ipv6Pool(pool: string): this

interface(configure: (b: InterfaceOverridesBuilder) => InterfaceOverridesBuilder): this

enabled(enabled: boolean): this

onSecretViolation(configure: (b: ViolationActionBuilder) => ViolationActionBuilder): this

secret(configure: (b: SecretBuilder) => SecretBuilder): this

secretEnv(envVar: string, value: string, placeholder: string, allowedHost: string): this

secretEnvSimple(envVar: string, value: string, allowedHost: string): this

build(): NetworkConfig

import { NetworkPolicy } from "microsandbox";

const policy = NetworkPolicy.builder()
  .defaultDeny()
  .egress((e) => e.tcp().port(443).allowPublic().allowPrivate())
  .rule((r) => r.any().deny((d) => d.ip("198.51.100.5")))
  .build();

defaultDeny(): this

defaultAllow(): this

defaultEgress(action: "allow" | "deny"): this

defaultIngress(action: "allow" | "deny"): this

egress(configure: (rb: RuleBuilder) => RuleBuilder): this

ingress(configure: (rb: RuleBuilder) => RuleBuilder): this

any(configure: (rb: RuleBuilder) => RuleBuilder): this

rule(configure: (rb: RuleBuilder) => RuleBuilder): this

build(): NetworkPolicy

NetworkPolicy.builder()
  .egress((r) =>
    r
      .tcp().port(443).allowPublic()    // rule 1: egress, TCP, 443, allow Public
      .udp().allowPrivate(),            // rule 2: egress, [TCP, UDP], 443, allow Private
  )
  .build();

egress(): this

ingress(): this

any(): this

tcp(): this

udp(): this

icmpv4(): this

icmpv6(): this

port(port: number): this

portRange(lo: number, hi: number): this

ports(ports: number[]): this

allowPublic(): this

denyPublic(): this

allowPrivate(): this

denyPrivate(): this

allowLoopback(): this

denyLoopback(): this

allowLinkLocal(): this

denyLinkLocal(): this

allowMeta(): this

denyMeta(): this

allowMulticast(): this

denyMulticast(): this

allowHost(): this

denyHost(): this

allowLocal(): this

denyLocal(): this

allowDomain(name: string): this

denyDomain(name: string): this

allowDomains(names: string[]): this

denyDomains(names: string[]): this

allowDomainSuffix(suffix: string): this

denyDomainSuffix(suffix: string): this

allowDomainSuffixes(suffixes: string[]): this

denyDomainSuffixes(suffixes: string[]): this

NetworkPolicy.builder()
  .egress((r) =>
    r
      .tcp().port(443).allow((d) => d.domain("api.example.com"))
      .deny((d) => d.cidr("198.51.100.0/24")),
  )
  .build();

allow(configure: (d: RuleDestinationBuilder) => RuleDestinationBuilder): this

deny(configure: (d: RuleDestinationBuilder) => RuleDestinationBuilder): this

ip(ip: string): this

cidr(cidr: string): this

domain(domain: string): this

domainSuffix(suffix: string): this

group(group: string): this

any(): this

rebindProtection(enabled: boolean): this

nameservers(servers: string[]): this

queryTimeoutMs(ms: number): this

bypass(pattern: string): this

verifyUpstream(verify: boolean): this

verifyUpstreamFor(pattern: string, verify: boolean): this

interceptedPorts(ports: number[]): this

blockQuic(block: boolean): this

interceptCaCert(path: string): this

interceptCaKey(path: string): this

upstreamCaCert(path: string): this

upstreamCaCertFor(pattern: string, path: string): this

block(): this

blockAndLog(): this

blockAndTerminate(): this

passthroughHost(host: string): this

passthroughHostPattern(pattern: string): this

passthroughAllHosts(iUnderstand: boolean): this

interface NetworkPolicy {
  readonly defaultEgress: Action;
  readonly defaultIngress: Action;
  readonly rules: readonly Rule[];
}

type NetworkProfile = "public" | "private" | "host";

interface Rule {
  readonly direction: Direction;
  readonly destination: Destination;
  readonly protocols: readonly Protocol[]; // empty = any
  readonly ports: readonly PortRange[];    // empty = any
  readonly action: Action;
}

type Action = "allow" | "deny";

type Direction = "egress" | "ingress" | "any";

type Destination =
  | { kind: "any" }
  | { kind: "cidr"; cidr: string }
  | { kind: "domain"; domain: string }
  | { kind: "domainSuffix"; suffix: string }
  | { kind: "group"; group: DestinationGroup };

type DestinationGroup =
  | "public"
  | "loopback"
  | "private"
  | "link-local"
  | "metadata"
  | "multicast"
  | "host";

type Protocol = "tcp" | "udp" | "icmpv4" | "icmpv6";

interface PortRange {
  readonly start: number;
  readonly end: number;
}

interface PublishedPort {
  readonly hostPort: number;
  readonly guestPort: number;
  readonly protocol: "tcp" | "udp";
  readonly hostBind: string;
}