# CubeEgress Architecture for Domain Allowlisting and Credential Injection

> Discover CubeEgress architecture for L7 egress firewalling. Learn how CubeEgress filters traffic with domain allowlisting and injects credentials via HTTP header manipulation before forwarding requests.

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

---

**CubeEgress implements a first-match-wins L7 egress firewall that filters traffic via domain allowlisting and injects credentials through HTTP header manipulation before forwarding requests.**

CubeEgress is the Layer 7 egress firewall integrated into the TencentCloud CubeSandbox network stack. Its architecture enables secure outbound communication by combining domain-based access control with dynamic credential injection. Understanding the internal data model and policy propagation flow is essential for operators configuring egress rules in production environments.

## Core Components of the CubeEgress Architecture

The CubeEgress engine is built around four interconnected data structures defined in [`network-agent/internal/service/types.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/internal/service/types.go).

### EgressRule – The Policy Container

The `EgressRule` struct (line 130) serves as the user-facing rule object that expresses *what* to allow or modify. Each rule contains:

- An `EgressRuleMatch` clause defining trigger conditions
- An `EgressRuleAction` clause defining the resulting operation

The network-agent evaluates rules in order, implementing **first-match-wins** semantics. Once a request satisfies a match condition, the corresponding action executes and evaluation stops.

### EgressRuleMatch – Domain Allowlisting Logic

Domain allowlisting lives inside the `EgressRuleMatch` struct (line 138). This component supports matching on:

- **SNI** (Server Name Indication)
- **Host** (IP addresses, CIDR ranges, exact domains, or wildcards like `*.example.com`)
- **Path** and **Method** for HTTP-specific filtering

The helper function `extractL7AllowOutTargetsFromRules` in [`service.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/service.go) walks the rule slice to collect all allowed destinations for bookkeeping and validation purposes.

### EgressRuleAction and EgressRuleInject – Credential Injection

When a match succeeds, the `EgressRuleAction` struct (line 148) determines the outcome. The action can:

- Allow the request (`Allow: true`)
- Inject credentials via the `Inject` field containing a slice of `EgressRuleInject` objects

The `EgressRuleInject` struct (line 155) defines the credential-injection descriptor with fields for the header name, value, and optional secret references (e.g., `${TOKEN}`). The embedded Lua bootstrap in CubeEgress expands these values into HTTP request headers before forwarding to the downstream service.

## How Domain Allowlisting Works

When a request enters the CubeSandbox network stack, CubeEgress evaluates the rule list against the connection attributes:

1. The **Host** field of `EgressRuleMatch` accepts plain domains (`api.example.com`), CIDR notation (`10.0.0.0/8`), or wildcard patterns (`*.internal.com`)
2. The engine performs string matching against the SNI or HTTP Host header
3. The first matching rule determines the fate of the connection

This approach allows administrators to implement strict egress controls, permitting connections only to explicitly enumerated external APIs or internal services.

## How Credential Injection Works

Credential injection operates as a modifier on allowed requests:

1. If a rule's `action.inject` slice is non-empty, CubeEgress prepares header injection
2. Each `EgressRuleInject` specifies the **header name** and **value**, which can contain interpolation syntax for dynamic secrets
3. The network-agent expands these templates (e.g., `"Bearer ${TOKEN}"`) before the policy reaches CubeEgress
4. CubeEgress attaches the resolved headers to the HTTP request before forwarding

This mechanism enables secure authentication to external APIs without exposing credentials to the sandboxed workload.

## Policy Lifecycle and Push Mechanism

The network-agent manages the transition from configuration to active enforcement through a resilient push mechanism.

### Configuration Conversion

The `CubeNetworkConfig` struct converts to the CubeEgress admin API format via `toEgressInput`. This conversion:

- Clones rule slices to prevent mutability bugs
- Drops nil fields to minimize payload size
- Validates rule consistency before transmission

The unit test `TestToEgressInputDropsNilFields` verifies this sanitization logic.

### Best-Effort Push and Retry

The `pushEgressForState` function issues a **PUT** request to the CubeEgress admin endpoint at `/policy/<sandbox-ip>`. This operation is **best-effort**:

- Transient failures set the `pendingEgressPush` flag
- The lifecycle loop invokes `retryPendingEgressPushes` (defined in [`tap_lifecycle.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/tap_lifecycle.go)) to retry failed pushes
- Permanent errors clear the flag to prevent infinite retry loops

The test `TestPushEgressForStateSuccessClearsPending` validates this state machine behavior.

## Code Implementation Examples

### Creating Rule Lists in Go

```go
rules := []*network_agent.EgressRule{
    {
        Match:  &network_agent.EgressRuleMatch{Host: ptr("api.example.com")},
        Action: &network_agent.EgressRuleAction{Allow: true},
    },
    {
        Match:  &network_agent.EgressRuleMatch{Host: ptr("private.internal")},
        Action: &network_agent.EgressRuleAction{
            Allow: true,
            Inject: []*network_agent.EgressRuleInject{
                {Header: "Authorization", Value: "Bearer ${TOKEN}"},
            },
        },
    },
}

cfg := &network_agent.CubeNetworkConfig{
    SandboxID: "sb-01",
    SandboxIP: "10.0.2.3",
    Rules:     rules,
}

```

### Pushing the Policy

```go
svc := network_agent.NewService(cfg) // builds local_service with egress client

if err := svc.PushEgressForState(ctx, state); err != nil {
    log.Fatalf("failed to push egress: %v", err)
}

```

### Policy JSON Structure

```json
{
  "rules": [
    {
      "match": { "host": "api.example.com" },
      "action": { "allow": true }
    },
    {
      "match": { "host": "private.internal" },
      "action": {
        "allow": true,
        "inject": [{ "header": "Authorization", "value": "Bearer ${TOKEN}" }]
      }
    }
  ]
}

```

## Summary

- **CubeEgress** operates as an L7 firewall inside the CubeSandbox network stack, implementing first-match-wins rule evaluation
- **Domain allowlisting** uses `EgressRuleMatch.Host` with support for IPs, CIDRs, domains, and wildcards as defined in [`network-agent/internal/service/types.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/internal/service/types.go)
- **Credential injection** occurs via `EgressRuleInject`, which adds HTTP headers before forwarding requests to external services
- **Policy propagation** follows a best-effort push model with `pendingEgressPush` retry logic managed in [`tap_lifecycle.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/tap_lifecycle.go)
- The conversion layer in [`local_service.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/local_service.go) ensures immutable rule cloning and nil-field sanitization before transmission to the CubeEgress admin API

## Frequently Asked Questions

### How does CubeEgress resolve conflicts between overlapping rules?

CubeEgress evaluates the `EgressRule` slice sequentially, implementing **first-match-wins** semantics. When a request satisfies the `EgressRuleMatch` conditions of multiple rules, only the action of the first matching rule executes. Administrators must order rules from most specific to least specific to ensure correct policy enforcement.

### What credential sources does CubeEgress support for header injection?

The `EgressRuleInject` struct supports static values and dynamic interpolation via the `${VARIABLE}` syntax. The network-agent expands these references from environment variables or secrets before pushing the policy to CubeEgress. The actual header injection occurs within the CubeEgress Lua bootstrap before the request leaves the sandbox network.

### Where is the retry logic implemented for failed policy pushes?

The retry mechanism resides in [`network-agent/internal/service/local_service.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent/internal/service/local_service.go) and [`tap_lifecycle.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/tap_lifecycle.go). The `pushEgressForState` function sets a `pendingEgressPush` flag when transient errors occur, and the lifecycle loop calls `retryPendingEgressPushes` to re-attempt transmission. Permanent errors clear this flag to prevent infinite retries.

### How can I verify which domains are allowed by my current policy?

Use the `DumpEgressPolicies` function or examine the `extractL7AllowOutTargetsFromRules` helper in [`service.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/service.go). This function walks the rule list and extracts all allowed destinations, returning the complete set of domains, IPs, and CIDR ranges that the sandbox can reach through the egress firewall.