CubeSandbox Network Policies and Route-Aware Egress Configuration Options

CubeSandbox enables precise control over sandbox network traffic through CubeNetworkConfig for layer-3/4 policies and CubeRouter settings for route-aware egress, configurable via the Go SDK or Cubelet TOML files.

TencentCloud CubeSandbox provides a secure container runtime with fine-grained network controls that operate at both the IP layer and application layer. Administrators can define traditional network policies that filter CIDR blocks alongside advanced route-aware egress rules that integrate directly with the host kernel's routing table. These configuration options are defined in network-agent/internal/service/types.go and config.go, supporting both programmatic SDK usage and declarative TOML configuration.

Network Policy Configuration (CubeNetworkConfig)

The CubeNetworkConfig struct defined in network-agent/internal/service/types.go (line 20) controls per-sandbox network access. This configuration drives the egress policy pushed to the CubeEgress service and supports both layer-3/4 IP filtering and layer-7 application-aware rules.

Layer-3/4 Traffic Controls

Three fields govern basic IP connectivity:

• AllowInternetAccess: A *bool pointer that defaults to allowing public internet access when nil or true. Set to false to block all external egress by default.
• AllowOut: A []string slice of CIDR blocks explicitly permitted when default egress is denied. Use this to whitelist specific destinations like "8.8.8.8/32".
• DenyOut: A []string slice of CIDR blocks always blocked, such as "0.0.0.0/0" to deny all outbound traffic regardless of other settings.

Layer-7 Egress Rules

The Rules field accepts a slice of *EgressRule pointers (defined in types.go lines 27-50) for application-layer filtering. Each rule contains:

• Name: Identifier for the rule
• Match: Criteria including host, path, or method (EgressRuleMatch struct)
• Action: Permit or deny logic with optional audit logging (EgressRuleAction struct)

Go SDK Implementation

Configure these policies programmatically using the SDK client:

import (
    "github.com/tencentcloud/CubeSandbox/sdk/go"
)

func exampleTemplate() (*sdk.TemplateInfo, error) {
    client, _ := sdk.NewClient(sdk.Config{
        // … other fields …
    })

    // Build a template that blocks all egress except 8.8.8.8/32
    tmpl := sdk.CreateTemplateRequest{
        TemplateID:   "tpl-network",
        NetworkType:  "tap",
        Network: &sdk.CubeNetworkConfig{
            AllowInternetAccess:   sdk.Bool(false),
            AllowOut:              []string{"8.8.8.8/32"},
            DenyOut:               []string{"0.0.0.0/0"},
            Rules: []*sdk.EgressRule{
                {
                    Name: "audit‑example",
                    Match: &sdk.EgressRuleMatch{
                        Host: sdk.StringPtr("example.com"),
                    },
                    Action: &sdk.EgressRuleAction{
                        Allow: true,
                        Audit: sdk.StringPtr("log‑example"),
                    },
                },
            },
        },
    }

    return client.CreateTemplate(context.Background(), tmpl)
}

The SDK serializes these fields into the network object of the template request payload in sdk/go/client.go (lines 149-163).

Route-Aware Egress Configuration

For environments requiring custom routing paths, CubeSandbox supports an optional CubeRouter that creates a virtual interface for sandbox egress. This functionality is controlled by the Config struct in network-agent/internal/service/config.go (line 53).

CubeRouter Parameters

When enabled, the network-agent creates a virtual router and injects routes into the host kernel:

• CubeRouterEnable: Boolean flag to activate route-aware egress (maps to TOML key cube_router_enable)
• CubeRouterCIDR: The CIDR block assigned to the virtual router (e.g., "10.254.0.0/24")
• CubeRouterMacAddr: MAC address for the virtual interface (e.g., "22:90:6f:cf:cf:cf")

The implementation in network-agent/internal/service/cube_router.go initializes the virtual interface and configures NAT or masquerading for sandbox traffic.

TOML Configuration

Configure route-aware egress in the Cubelet TOML file:

[plugins."io.cubelet.internal.v1.network"]
eth_name = "eth0"
cidr = "192.168.0.0/18"

# Route‑aware egress options

cube_router_enable = true
cube_router_cidr   = "10.254.0.0/24"
cube_router_mac_addr = "22:90:6f:cf:cf:cf"

These keys map to the Config struct fields described in config.go lines 53-57.

Policy Enforcement Flow

Understanding the runtime path helps troubleshoot connectivity issues. When a sandbox starts, the network-agent processes configuration in two stages:

1. CubeEgress Push: The network-agent/internal/service/cubeegress_push.go file (lines 52-100) converts CubeNetworkConfig into a cubeegress.PolicyInput and transmits it to the CubeEgress admin API via PutPolicy.
2. Router Initialization: If CubeRouterEnable is true, local_service.go invokes the router setup from cube_router.go to add host kernel routes and configure the virtual interface.

Summary

• CubeNetworkConfig in types.go defines per-sandbox network policies with AllowInternetAccess, AllowOut, DenyOut, and Rules fields for layer-3/4 and layer-7 filtering.
• Host-level Config in config.go controls route-aware egress via CubeRouterEnable, CubeRouterCIDR, and CubeRouterMacAddr.
• Layer-7 egress rules are enforced by the CubeEgress service after being converted in cubeegress_push.go.
• The optional CubeRouter provides dedicated routing tables and virtual interfaces when default gateway behavior is insufficient.

Frequently Asked Questions

How do I block all internet access except for specific DNS servers?

Set AllowInternetAccess to false, add the DNS server CIDRs to AllowOut, and include "0.0.0.0/0" in DenyOut. For example, AllowOut: []string{"8.8.8.8/32", "8.8.4.4/32"} permits only Google DNS while blocking all other egress, as enforced by the CubeEgress service.

What is the difference between DenyOut and AllowOut precedence?

DenyOut rules take precedence as explicit blocks regardless of other settings. If a destination matches both DenyOut and AllowOut, the deny rule wins, ensuring that blacklisted CIDRs remain unreachable even when general egress is permitted via AllowInternetAccess.

When should I enable CubeRouter instead of using the default gateway?

Enable CubeRouterEnable when sandbox traffic requires isolation from the host's default routing table, specific NAT configurations, or distinct egress paths for multiple sandboxes. The virtual router implementation in cube_router.go creates a dedicated network namespace and routes traffic independently of the host default gateway.

Where are Layer-7 egress rules processed?

Layer-7 rules defined in the Rules slice are converted to cubeegress.PolicyInput in network-agent/internal/service/cubeegress_push.go (via toEgressInput and toMatchInput) and enforced by the CubeEgress service, which performs application-layer inspection on outbound connections from the sandbox.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}