# How CubeEgress Implements Domain Allowlisting and Egress Traffic Inspection in TencentCloud/CubeSandbox

> Learn how CubeEgress implements robust domain allowlisting and egress traffic inspection in TencentCloud CubeSandbox using a first-match-wins rule engine for secure outbound connections.

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

---

**CubeEgress enforces application-layer egress policies through a first-match-wins rule engine where domain allowlists are implemented by placing permitted hosts before a deny-all rule, while L7 inspection is achieved via configurable actions including header injection and detailed audit logging.**

CubeEgress is the security component within TencentCloud/CubeSandbox that governs outbound application-layer traffic for sandboxed workloads. By transforming sandbox configurations into deterministic policy rules, it enables fine-grained control over which external domains are accessible and provides deep packet inspection capabilities. Understanding how CubeEgress implements domain allowlisting and egress traffic inspection requires examining the policy structures in [`network-agent/internal/service/types.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/internal/service/types.go) and the translation logic in [`network-agent/internal/service/cubeegress_push.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/internal/service/cubeegress_push.go).

## Policy Architecture and First-Match-Wins Semantics

The foundation of CubeEgress security lies in its **rule-based policy engine**. According to the source code in [`network-agent/internal/service/types.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/internal/service/types.go), each **EgressRule** consists of a **Match** condition and an **Action** directive. The engine evaluates rules sequentially against outbound connections until the first match succeeds, making order-critical for security posture.

### Domain Allowlisting Implementation

Domain allowlisting leverages this first-match-wins behavior to create explicit permit lists. When a sandbox configuration specifies permitted hosts in the `Host` field of an **EgressRuleMatch**, the policy generator creates a rule containing a `Hosts` array. As explicitly noted in [`sdk/go/policy.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/policy.go), "allowing specific domains is meaningful only when all all other egress is denied."

To implement a functional allowlist, administrators must structure the **Rules** array with explicit allow entries enumerating trusted domains, followed by a terminal deny-all rule. This configuration ensures that only traffic matching the enumerated hosts passes through, while all other egress attempts trigger the final denial rule.

```go
// Build a policy that only allows example.com and api.myservice.com
cfg := &CubeNetworkConfig{
    Rules: []EgressRule{
        {
            Match: EgressRuleMatch{
                Host: []string{"example.com", "api.myservice.com"},
            },
            Action: EgressRuleAction{
                Allow: true,
            },
            Name: "allow-list-domains",
        },
        {
            // Fallback rule – deny everything else
            Action: EgressRuleAction{
                Deny: true,
            },
            Name: "deny-all-others",
        },
    },
}
pol := toEgressInput(cfg)               // internal conversion, see cubeegress_push.go
err := egClient.PutPolicy(ctx, sandboxIP, pol)

```

## L7 Traffic Inspection and Audit Mechanisms

Beyond access control, CubeEgress performs deep L7 inspection through the **ActionInput** type defined in [`network-agent/internal/cubeegress/wire.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/internal/cubeegress/wire.go). The `Inject` action enables request modification in-flight, allowing the system to append custom HTTP headers for authentication, tracing, or audit marking.

Each rule carries a mandatory human-readable `Name` field that propagates into audit logs. This creates an immutable attribution trail, identifying exactly which policy rule authorized or denied specific egress traffic. The combination of injection capabilities and named rules provides comprehensive visibility into sandbox network behavior.

```go
// Inspect HTTP traffic: inject a header for audit
cfg.Rules[0].Action.Inject = []Inject{
    {Header: "X-Cube-Audit", Value: "sandbox-123"},
}

```

## Network-Agent Integration and Policy Lifecycle

The network-agent serves as the control plane for CubeEgress policy distribution, handling translation, delivery, and lifecycle management.

### Policy Translation and Push Logic

In [`network-agent/internal/service/cubeegress_push.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/internal/service/cubeegress_push.go), the conversion pipeline begins with `toEgressInput`, which transforms internal **CubeNetworkConfig** structures into the `cubeegress.PolicyInput` wire format. This function delegates to `toMatchInput` and `toActionInput` to serialize match conditions and actions respectively. The agent then invokes `egress.PutPolicy` to push the constructed policy to the CubeEgress admin API endpoint.

### Error Handling and Retry Semantics

The push mechanism implements discriminating retry logic with a **2-second timeout** defined by the `egressRetryCallTimeout` constant. Transient network failures trigger automatic retry attempts, while permanent errors—such as malformed rule specifications—are logged immediately without retry to prevent infinite loops. This distinction ensures policy eventual consistency without masking configuration errors.

```go
// Network-agent pushes the policy (simplified)
if s.egress != nil && s.egress.Configured() {
    in := toEgressInput(cfg)
    if err := s.egress.PutPolicy(ctx, state.SandboxIP, in); err != nil {
        // retry logic handled inside cubeegress_push.go
    }
}

```

### Policy Deletion on Teardown

When sandboxes terminate, [`network-agent/internal/service/local_service.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/internal/service/local_service.go) invokes `egress.DeletePolicy` to ensure immediate cleanup of egress rules. This prevents stale policies from persisting after workload completion, maintaining the integrity of the network security boundary.

## Summary

- **First-match-wins evaluation** in [`network-agent/internal/service/types.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/internal/service/types.go) enables deterministic domain allowlisting by ordering explicit permits before deny-all rules.
- **L7 inspection** is achieved through the `Inject` action in `ActionInput`, supporting header modification for audit and tracing.
- **Policy lifecycle management** in [`cubeegress_push.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubeegress_push.go) converts configurations using `toEgressInput` and handles delivery with 2-second timeout retries.
- **Cleanup guarantees** are enforced via `DeletePolicy` calls when sandboxes terminate, preventing policy leakage.

## Frequently Asked Questions

### How does CubeEgress determine which rule applies when multiple rules match a connection?

CubeEgress evaluates rules in the order they appear in the **Rules** array, stopping at the first match. This first-match-wins semantics means you must place specific allow rules before broad deny rules to implement effective allowlisting, as implemented in the policy engine from [`network-agent/internal/service/types.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/internal/service/types.go).

### What happens if the CubeEgress admin API is unavailable when the network-agent pushes a policy?

The network-agent implements retry logic with a 2-second timeout (`egressRetryCallTimeout`) for transient failures, as defined in [`cubeegress_push.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubeegress_push.go). However, permanent errors such as malformed rules are logged and not retried, ensuring the system does not indefinitely attempt to push invalid configurations.

### Can CubeEgress modify HTTP headers for security auditing?

Yes. The **ActionInput** struct supports an `Inject` field that allows injecting custom HTTP headers into outbound requests. This capability enables audit trails by adding identifying headers—such as `X-Cube-Audit` with sandbox identifiers—before traffic leaves the sandbox environment.

### Where is the domain allowlist logic documented in the CubeSandbox SDK?

The semantic requirement for domain allowlisting—specifically that allowing specific domains is only meaningful when all other egress is denied—is documented in [`sdk/go/policy.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/sdk/go/policy.go). This file contains the high-level SDK comments explaining how host-based rules interact with default-deny policies.