# CubeSandbox Network Policies and Route-Aware Egress Configuration Options

> Configure CubeSandbox network policies and route-aware egress using CubeNetworkConfig and CubeRouter. Control sandbox traffic precisely via Go SDK or TOML files.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: how-to-guide
- Published: 2026-07-11

---

**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`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/internal/service/types.go) and [`config.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

```go
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

```toml
[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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/local_service.go) invokes the router setup from [`cube_router.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube_router.go) to add host kernel routes and configure the virtual interface.

## Summary

- **`CubeNetworkConfig`** in [`types.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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.