Class: Microsandbox::NetworkPolicy

Inherits:
Object
  • Object
show all
Defined in:
lib/microsandbox/network.rb

Overview

A sandbox network policy: a preset, or a custom set of allow/deny Rules with per-direction default actions and bulk domain denials.

Pass to Sandbox.create via ‘network:` — either a NetworkPolicy, a preset name (String/Symbol), or a plain Hash with the same keys as NetworkPolicy.custom.

Mirrors ‘NetworkPolicy` / `Network` in the official Python/Node/Go SDKs.

Examples:

presets

Sandbox.create("b", image: "alpine", network: NetworkPolicy.public_only)
Sandbox.create("b", image: "alpine", network: :none)

custom

policy = Microsandbox::NetworkPolicy.custom(
  default_egress: :deny,
  rules: [
    Microsandbox::Rule.allow(destination: "api.openai.com", protocol: :tcp, port: "443"),
  ],
  deny_domain_suffixes: [".ads.example"],
)
Sandbox.create("b", image: "alpine", network: policy)

Constant Summary collapse

PRESET_ALIASES =

Canonical preset names keyed by every accepted alias.

{
  "none" => "none", "disabled" => "none", "disable" => "none", "airgapped" => "none",
  "public" => "public_only", "public_only" => "public_only", "public-only" => "public_only",
  "default" => "public_only",
  "all" => "allow_all", "allow_all" => "allow_all", "allow-all" => "allow_all",
  "non_local" => "non_local", "non-local" => "non_local", "nonlocal" => "non_local"
}.freeze

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(wire) ⇒ NetworkPolicy

Returns a new instance of NetworkPolicy.



287
288
289
 
# File 'lib/microsandbox/network.rb', line 287

def initialize(wire)
  @wire = wire
end

Class Method Details

.allow_all ⇒ NetworkPolicy

Returns permit all traffic.

Returns:



126
 
# File 'lib/microsandbox/network.rb', line 126

def allow_all = preset("allow_all")

.coerce(network) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Coerce a user-facing ‘network:` value into a normalized wire Hash.



163
164
165
166
167
168
169
170
171
172
173
 
# File 'lib/microsandbox/network.rb', line 163

def coerce(network)
  case network
  when NetworkPolicy then network.to_h
  when String, Symbol then { "preset" => canonical_preset(network) }
  when Hash then from_hash(network)
  else
    raise ArgumentError,
          "network: expects a preset name, a Microsandbox::NetworkPolicy, or a Hash " \
          "(got #{network.class})"
  end
end

.custom(default_egress: :deny, default_ingress: :allow, rules: [], deny_domains: [], deny_domain_suffixes: []) ⇒ NetworkPolicy

Build a custom policy — an ordered rule list with per-direction default actions. A custom policy stands on its own (no preset); to start from a preset, use the preset factories (optionally with ‘deny_domains:` via the Hash form passed to Sandbox.create). `preset:` and custom rules/defaults are mutually exclusive, mirroring the official SDKs.

Parameters:

  • default_egress (:deny, :allow, nil) (defaults to: :deny) —

    fall-through for unmatched outbound traffic (default :deny)

  • default_ingress (:deny, :allow, nil) (defaults to: :allow) —

    fall-through for unmatched inbound traffic (default :allow)

  • rules (Array<Hash>) (defaults to: []) —

    ordered Rules (first match wins per direction)

  • deny_domains (Array<String>) (defaults to: []) —

    exact domains to deny egress to (prepended, so they outrank later allow rules)

  • deny_domain_suffixes (Array<String>) (defaults to: []) —

    domain suffixes to deny

Returns:



151
152
153
154
155
156
157
158
159
 
# File 'lib/microsandbox/network.rb', line 151

def custom(default_egress: :deny, default_ingress: :allow, rules: [],
           deny_domains: [], deny_domain_suffixes: [])
  h = {}
  h["default_egress"] = action_str(default_egress) unless default_egress.nil?
  h["default_ingress"] = action_str(default_ingress) unless default_ingress.nil?
  h["rules"] = Array(rules).map { |r| normalize_rule(r) }
  add_deny_lists(h, deny_domains, deny_domain_suffixes)
  new(h)
end

.non_local ⇒ NetworkPolicy

Returns allow public internet plus private/LAN egress.

Returns:

  • (NetworkPolicy) —

    allow public internet plus private/LAN egress



129
 
# File 'lib/microsandbox/network.rb', line 129

def non_local = preset("non_local")

.none ⇒ NetworkPolicy

Returns block all network access.

Returns:



123
 
# File 'lib/microsandbox/network.rb', line 123

def none = preset("none")

.preset(name) ⇒ NetworkPolicy

Returns a bare preset policy.

Returns:



132
133
134
 
# File 'lib/microsandbox/network.rb', line 132

def preset(name)
  new("preset" => canonical_preset(name))
end

.public_only ⇒ NetworkPolicy

Returns allow only public internet (the default).

Returns:



120
 
# File 'lib/microsandbox/network.rb', line 120

def public_only = preset("public_only")

Instance Method Details

#inspect ⇒ Object 



296
297
298
 
# File 'lib/microsandbox/network.rb', line 296

def inspect
  "#<Microsandbox::NetworkPolicy #{@wire.inspect}>"
end

#to_h ⇒ Hash

Returns the normalized wire representation.

Returns:

  • (Hash) —

    the normalized wire representation



292
293
294
 
# File 'lib/microsandbox/network.rb', line 292

def to_h
  @wire
end