# How CubeEgress Domain Allowlist Filtering Works for Egress Traffic

> Learn how CubeEgress domain allowlist filtering secures egress traffic by enforcing default deny and first match wins rules to permit only specified outbound connections.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: internals
- Published: 2026-07-10

---

**CubeEgress enforces domain-based egress filtering by validating that domain allowlists require a default-deny posture, then applies first-match-wins rules to permit traffic only to specified domains while blocking all other outbound connections.**

In the **TencentCloud/CubeSandbox** repository, **CubeEgress domain allowlist filtering** provides Layer 7 egress control by restricting outbound traffic to specific domain names while denying all other internet access. This security mechanism ensures that sandboxed workloads can only communicate with approved external endpoints, preventing data exfiltration to unauthorized destinations. The implementation spans the SDK validation layer, the network-agent translation service, and the CubeEgress enforcement engine.

## Policy Structure and Domain Allowlisting

When you configure egress rules through the Go, Python, or Node SDK, you construct a `network.rules` object containing `match` criteria (host, SNI, path, method) and `action` directives (`allow`, `inject`, or `audit`). The critical field for domain filtering is **`allowOut`** (or `allow_out` in Python), which accepts an array of domain names or CIDR blocks.

However, domain-based entries in `allowOut` trigger a strict validation requirement. According to the source code in [`sdk/go/policy.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/policy.go), the system mandates that **all other egress traffic must be explicitly denied** when using domain allowlists. This prevents security gaps where domain allowances might coexist with permissive default internet access.

### The Domain Validation Logic

The function `validateAllowOutDomainsRequireDenyAll` in [`sdk/go/policy.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/policy.go) (lines 60-86) enforces this contract. If `isDomainAllowOutTarget` detects at least one domain name in the `allowOut` list, the validation accepts the request only when either:

- **`defaultDenyAll`** is set to `true` (via `allowInternetAccess=false`), or
- **`denyOut`** includes the wildcard CIDR `0.0.0.0/0`.

If neither condition is satisfied, the SDK returns an `APIError` with the message `allowOutDomainRequiresDenyAll` (lines 62-66).

### Domain Detection Algorithm

The helper function `isDomainAllowOutTarget` distinguishes domain names from IP addresses through several checks implemented in [`sdk/go/policy.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/policy.go) (lines 92-144):

- Trims whitespace and rejects empty strings or strings containing "/".
- Rejects any string that successfully parses as an IP address using `net.ParseIP`.
- Rejects dotted-decimal-like strings (e.g., `192.168.1`) via `isDottedDecimalLike`.
- Accepts DNS-style names, including wildcard prefixes like `*.example.com`, through `isValidDNSDomainName`.

This ensures that only valid domain patterns trigger the strict deny-all requirement, while pure CIDR-based policies can operate under different egress postures.

## Policy Translation and Enforcement

Once validated, the network-agent translates your `CubeNetworkConfig` into a `cubeegress.PolicyInput` structure. In [`network-agent/internal/service/cubeegress_push.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/internal/service/cubeegress_push.go) (lines 52-71), the `toEgressInput` function populates the `Rules` slice with `cubeegress.RuleInput` objects, preserving the match and action semantics from your SDK configuration.

The CubeEgress service evaluates these policies using **first-match-wins** semantics, as documented in [`network-agent/internal/service/types.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/internal/service/types.go). When a request's SNI or Host header matches a domain listed in `allowOut`, the corresponding rule with `allow: true` permits the traffic to pass, optionally injecting credential headers. Any request failing to match an explicit allow rule gets blocked by the default deny rule, which is active when `defaultDenyAll` is enabled.

## Implementation Examples

The following examples demonstrate how to configure a sandbox that allows egress only to `api.example.com` while blocking all other outbound traffic.

**Go SDK:**

```go
opts := cubesandbox.SandboxOptions{
    Network: cubesandbox.NetworkOptions{
        AllowOut: []string{"api.example.com"},
        // Deny all other traffic by disabling public egress:
        AllowInternetAccess: false,
    },
}
sandbox, err := client.CreateSandbox(ctx, opts)

```

**Python SDK:**

```python
policy = cubesandbox.Policy(
    allow_out=["api.example.com"],
    allow_internet_access=False,
)
sandbox = client.create_sandbox(policy=policy)

```

**Node SDK:**

```javascript
const policy = {
  allowOut: ["api.example.com"],
  allowInternetAccess: false,
};
await client.createSandbox({ policy });

```

All three examples trigger the validation in `validateAllowOutDomainsRequireDenyAll`. If `allowInternetAccess` were omitted, the SDK would automatically add `denyOut: ["0.0.0.0/0"]` to satisfy the contract that domain allowlisting requires explicit denial of all other traffic.

## Key Source Files

The domain allowlist filtering implementation spans these critical locations in the TencentCloud/CubeSandbox repository:

- **[`sdk/go/policy.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/policy.go)** – Contains the `validateAllowOutDomainsRequireDenyAll` validation function (lines 60-86) and domain detection logic `isDomainAllowOutTarget` (lines 92-144).
- **[`network-agent/internal/service/cubeegress_push.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/internal/service/cubeegress_push.go)** – Implements the `toEgressInput` function (lines 52-71) that translates `CubeNetworkConfig` into `cubeegress.PolicyInput`.
- **[`network-agent/internal/service/types.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/internal/service/types.go)** – Defines the `EgressRule` structure and documents the first-match-wins evaluation semantics.
- **[`sdk/python/_policy.py`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/python/_policy.py)** – Mirrors the Go validation logic for the Python SDK.
- **[`sdk/node/src/policy.ts`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/node/src/policy.ts)** – Implements equivalent domain validation for the Node.js SDK.

## Summary

- **Domain allowlisting** in CubeEgress requires explicit denial of all other egress traffic via `defaultDenyAll` or a `0.0.0.0/0` entry in `denyOut`.
- The **`validateAllowOutDomainsRequireDenyAll`** function in [`sdk/go/policy.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/policy.go) enforces this security contract across all SDKs.
- **Domain detection** distinguishes DNS names from CIDR blocks using `net.ParseIP` and pattern matching against dotted-decimal strings.
- The **network-agent** translates SDK configurations into `cubeegress.PolicyInput` objects and pushes them to the CubeEgress admin API.
- CubeEgress applies **first-match-wins** evaluation, allowing traffic to specified domains while blocking all non-matching outbound requests.

## Frequently Asked Questions

### Why does CubeEgress require denying all other traffic when using domain allowlists?

CubeEgress mandates a default-deny posture for domain allowlists to prevent security bypasses. If you could specify allowed domains while simultaneously permitting general internet access, the domain restrictions would be meaningless. The validation function `validateAllowOutDomainsRequireDenyAll` in [`sdk/go/policy.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/policy.go) enforces this by checking that either `defaultDenyAll` is true or `denyOut` contains `0.0.0.0/0`.

### How does CubeEgress distinguish between a domain name and an IP address in the allowOut list?

The SDK uses the `isDomainAllowOutTarget` function, which attempts to parse the string as an IP using `net.ParseIP`, rejects dotted-decimal patterns like `192.168.1`, and validates DNS syntax including wildcards such as `*.example.com`. Strings containing "/" are immediately rejected as CIDR blocks rather than domains.

### What happens if a request matches multiple egress rules?

CubeEgress evaluates rules using **first-match-wins** semantics as implemented in the enforcement engine. The first rule in the policy whose match criteria (host, SNI, path, method) satisfies the request determines the action—whether to allow, inject credentials, or audit the traffic. Subsequent rules are ignored for that specific request.

### Can I use wildcard domains in the allowOut list?

Yes, the domain validation supports wildcard prefixes like `*.example.com`. The `isValidDNSDomainName` function in [`sdk/go/policy.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/policy.go) accepts these patterns, allowing you to authorize entire subdomains while maintaining the strict deny-all requirement for other egress traffic.