Agent Runtime 网络策略（NetworkPolicy

能力概述
沙箱里的程序通常需要访问模型 API、代码仓库、软件源或企业内网。全部放开会扩大数据外传和凭证滥用的风险，完全断网又会让程序无法正常工作。
NetworkPolicy 是沙箱实例的出口网络策略。您可以通过一份 JSON 策略声明哪些目标可以访问、哪些请求必须拒绝，以及哪些流量需要经过上游代理或 Webhook。策略可在实例运行期间更新，无需重启。
适用场景
需要访问模型 API、代码仓库、软件源或企业内网，同时缩小允许访问范围，避免完全放开带来的数据外传和凭证滥用风险。
需要完全拒绝或完全允许外部访问时，通过 DefaultDecision 与空 Rules 组合实现。
需要将 HTTP 流量强制经过企业代理，或对请求进行审计、修改、凭证注入时，使用 upstream、Hooks 和 Transform。
工作方式
策略模型
一份策略由默认决策、规则列表和可选的 Hook 组成：
组成
作用
DefaultDecision
没有 Rule 命中时执行 allow 或 deny，省略时默认为 deny
Rules
按数组顺序匹配流量；第一条命中的 Rule 决定处理结果
Hooks
在 HTTP 请求转发前执行异步通知或同步修改
CredentialProviders
为高级 Transform 提供可引用的凭证
每条 Rule 可以组合 Resource、HTTP 方法和 CEL 表达式。Resource 负责匹配 Host、Port 和 PathPrefix；CEL 用于 Header、Body、IP/CIDR、时间等动态条件。
三种处理结果
Decision
行为
allow
放行，请求连接原目标。
deny
阻断；HTTP/HTTPS 请求返回 403，Raw TCP 连接被拒绝。
upstream
不直连原目标，将 HTTP 流量转发到指定上游。
Raw TCP 只支持 allow 和 deny。upstream、Hook、Rewrite 和 Transform 都属于 HTTP 层能力。
可以控制到什么程度
需求
配置方式
只允许特定域名或 IP
Resources[].Hosts
限制端口或端口范围
Resources[].Ports
限制 HTTP 路径和方法
PathPrefix + Methods
按 Header、Body、CIDR 或时间判断
Expression
审计允许或拒绝的请求
notify Hook
注入或删除请求 Header
mutating Hook
从托管凭证注入 Header 或 JSON Body
CredentialProviders + Transform
强制流量经过企业代理
Decision=upstream
运行中替换策略
UpdateSandboxInstance 或 E2B Update
HTTPS 的路径、Header 和 Body 匹配依赖 MITM 及客户端对代理 CA 的信任。Raw TCP 管控还需要运行环境启用透明 TCP 拦截。
策略匹配规则
Rule 顺序
Rule 没有 Priority 字段，按 Rules 数组顺序执行 first-match：
请求
  → Rule[0] 是否匹配？是 → 执行该 Rule 的 Decision
  → Rule[1] 是否匹配？是 → 执行该 Rule 的 Decision
  → ...
  → 没有 Rule 命中 → 执行 DefaultDecision
如果多条 Rule 都能匹配同一请求，只有最前面的 Rule 生效。因此，范围更窄的规则应放在范围更宽的规则前面。例如，先拒绝敏感路径，再放行同一域名的其他路径。
Rule 内的条件
一条 Rule 的匹配结果由以下条件共同决定：
Resources 与 Expression 之间是 AND。
多个 Resource 之间是 OR。
单个 Resource 内，非空的 Hosts、Ports、PathPrefix 之间是 AND。
Hosts、Ports、PathPrefix 各自数组内的值是 OR。
Methods 为空时不限制 HTTP 方法。
Resources 为空时不限制目标资源。
Expression 为空时不增加额外条件。
例如：
{
  "Resources": [
    {
      "Hosts": ["api.example.com"],
      "Ports": ["443"],
      "PathPrefix": ["/v1", "/v2"]
    }
  ],
  "Methods": ["GET", "POST"],
  "Expression": "request.headers[\\"x-tenant\\"] == \\"tenant-a\\""
}
该条件要求主机、端口、路径前缀、HTTP 方法和 CEL 表达式同时匹配。
Host 匹配
写法
匹配范围
api.example.com
只匹配该主机，大小写不敏感。
*.example.com
匹配 api.example.com、v2.api.example.com 等子域。
*
匹配任意主机。
*.example.com 不匹配 example.com。如果根域和子域都要允许，应同时填写：
{
  "Hosts": ["example.com", "*.example.com"]
}
网段匹配使用 CEL Expression，不要把 CIDR 写入 Hosts。
Port 匹配
Ports 使用字符串，支持：
写法
含义
"443"
单端口。
"http"
端口 80。
"https"
端口 443。
"1000-2000"
包含首尾的端口闭区间。
单端口必须位于 [1, 65535]。一条 Resource 最多填写 20 个 Port 规格，所有范围展开后最多包含 4096 个端口。
HTTP 与 Raw TCP
HTTP/HTTPS 流量可以使用 Host、Port、PathPrefix、Methods、Header、Body 和时间等条件。
基于 HTTP/2 的 gRPC 请求仍按 HTTP 流量处理，可以结合 request.protocol、request.path 和 content-type Header 匹配服务或方法。策略使用归一化后的 HTTP 请求属性，不提供 HTTP/2 帧级条件。
启用透明 Raw TCP 拦截后，MySQL、PostgreSQL、Redis 等非 HTTP TCP 连接也会进入策略判断。Raw TCP 只提供目标地址和端口等连接信息：
可以使用 destination.address、destination.port 和 CIDR 条件。
不提供 HTTP Header、Path、Method 或 Body。
不解析数据库命令。
只支持 allow 和 deny，不执行 HTTP Hook、Rewrite、Transform 或 Upstream。
UDP 不在当前能力范围内。
Raw TCP 管控依赖支持透明 TCP 拦截的运行环境。
CEL 表达式
当 Resource 和 Methods 无法表达条件时，可以使用 CEL Expression。
仅允许带指定 Header 的请求：
"x-test-token" in request.headers
  && request.headers["x-test-token"] == "expected-token"
仅允许 Body 包含指定内容的请求：
has(request.body)
  && request.body.content.contains("approved")
仅允许访问指定网段：
ip_in_cidrs(
  destination.address,
  ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]
)
仅允许北京时间工作日 09:00～18:00。request.time 使用 UTC，因此对应 UTC 01:00～10:00：
day_of_week(request.time) >= 1
  && day_of_week(request.time) <= 5
  && hour(request.time) >= 1
  && hour(request.time) < 10
常用变量和函数：
分类
变量或函数
请求
request.host、request.path、request.method、request.scheme、request.port、request.query、request.protocol、request.size
Header
request.headers["key"]，Header 名按小写访问
Body
request.body.content、encoding、size、truncated、sha256
目标
destination.address、destination.port
连接
connection.tls、connection.tls_version、connection.sni、connection.alpn
时间
request.time、hour()、minute()、day_of_week()、day_of_month()、month()
IP/CIDR
ip()、cidr()、contains()、ip_in_cidrs()
字符串
split()、trim()、startsWith()、endsWith()、contains()
request.body 和 connection.sni 可能不存在，访问前分别使用 has(request.body) 和 has(connection.sni)。CEL 表达式为 false 时继续匹配下一条 Rule；缺失字段访问、类型错误或其他求值错误会拒绝当前请求。
前提条件
Rule 按数组顺序匹配，第一条命中的 Rule 生效。
没有 Rule 命中时执行 DefaultDecision；该字段省略时默认为 deny。
*.example.com 只匹配子域，不匹配根域 example.com。
HTTPS 路径、方法、Header 和 Body 匹配依赖 MITM。
Raw TCP 可以按目标地址、端口和 CEL 条件控制，但不解析 MySQL、Redis 等应用协议。
UpdateSandboxInstance 只允许更新 RUNNING 实例，且每次完整替换策略。
NetworkPolicy 需要先开通，并由支持该能力的运行环境执行。
快速开始
下面的策略可以保存为 network-policy.json。它只允许：
向 api.openai.com:443 的 /v1/chat 和 /v1/embeddings 发起 POST 请求。
访问 GitHub 和 GitHubusercontent 的根域及子域 HTTPS 地址。
其他出口流量全部拒绝。
{
  "DefaultDecision": "deny",
  "Rules": [
    {
      "Name": "allow-openai",
      "Resources": [
        {
          "Hosts": ["api.openai.com"],
          "Ports": ["443"],
          "PathPrefix": ["/v1/chat", "/v1/embeddings"]
        }
      ],
      "Methods": ["POST"],
      "Decision": "allow"
    },
    {
      "Name": "allow-github",
      "Resources": [
        {
          "Hosts": [
            "github.com",
            "*.github.com",
            "githubusercontent.com",
            "*.githubusercontent.com"
          ],
          "Ports": ["443"]
        }
      ],
      "Decision": "allow"
    }
  ]
}
方式一：通过 Cloud API 创建实例
调用 StartSandboxInstance 时，将 network-policy.json 中的整个对象作为 NetworkPolicy 字段值。ToolId 等创建参数照常填写。
方式二：通过 E2B SDK 创建实例
E2B SDK 使用保留的 metadata 键 x-network-policy。它的值是序列化后的策略 JSON 字符串，不是嵌套 JSON 对象。
import json
import os
﻿
from e2b_code_interpreter import Sandbox
﻿
os.environ["E2B_DOMAIN"] = "<your-e2b-domain>"
os.environ["E2B_API_KEY"] = "your_api_key"
﻿
with open("network-policy.json", encoding="utf-8") as policy_file:
    policy = json.load(policy_file)
﻿
sandbox = Sandbox.create(
    template="code-xxx",
    timeout=3600,
    metadata={"x-network-policy": json.dumps(policy)},
)
验证结果
Cloud API 创建后，调用 DescribeSandboxInstance 或列表接口回读实例当前保存的策略。
E2B 创建后，通过 E2B Get/List 返回的 metadata["x-network-policy"] 回读当前策略。
更新成功后，更新接口只返回 RequestId，不回显更新后的策略；请通过 Describe/List 回读确认。
创建、继承与更新
原生 API
接口
行为
CreateSandboxTool
设置 Tool 默认策略。
UpdateSandboxTool
更新 Tool 默认策略。
StartSandboxInstance
创建实例时设置实例级策略；不传时继承 Tool 当时的默认策略。
UpdateSandboxInstance
完整替换运行中实例的策略。
StartSandboxInstanceResponse.Instance
返回创建后实例保存的策略。
DescribeSandboxInstance / List
返回实例当前保存的策略。
实例创建时继承的是 Tool 策略快照。Tool 后续更新不会自动修改已经创建的实例。
null、{} 和空 Rules
输入
StartSandboxInstance
UpdateSandboxInstance
不传或 null
继承 Tool 默认策略
不更新
{}
创建默认拒绝的实例策略
完整替换为默认拒绝
{"DefaultDecision":"deny","Rules":[]}
明确拒绝全部
明确拒绝全部
{"DefaultDecision":"allow","Rules":[]}
明确允许全部
明确允许全部
UpdateSandboxInstance 不支持 Rule 级 Patch。只要传入非 null 的 NetworkPolicy，就会完整替换旧策略。
更新和回读
策略更新只允许用于 RUNNING 实例，不需要重启。UpdateSandboxInstanceResponse 仅返回 RequestId，不回显更新后的策略；需要通过 Describe/List 回读。
策略随实例保存，暂停和恢复不会清除策略。恢复后仍可在实例回到 RUNNING 状态后更新。接口不承诺固定的秒级生效时间。
输入中的默认值可能在响应中被补全，例如：
DefaultDecision 省略后回显为 deny。
Upstream Scheme 省略后回显为 https。
Upstream Port=0 可能按 Scheme 回显为 80 或 443。
Webhook Timeout 省略后回显为 3s。
E2B 兼容入口
E2B Create 和 Update 使用 metadata["x-network-policy"]。该字段解析后进入与原生 API 相同的校验和更新流程，不会作为普通 metadata 保存。
非法 JSON、未知字段或非法策略会返回 400。更新成功后通过 E2B Get/List 返回的 metadata["x-network-policy"] 回读当前策略。
常见配置
完全拒绝或完全允许
完全拒绝：
{
  "DefaultDecision": "deny",
  "Rules": []
}
完全允许：
{
  "DefaultDecision": "allow",
  "Rules": []
}
先拒绝敏感路径，再放行其他路径
{
  "DefaultDecision": "deny",
  "Rules": [
    {
      "Name": "deny-admin",
      "Resources": [
        {
          "Hosts": ["api.example.com"],
          "Ports": ["443"],
          "PathPrefix": ["/admin"]
        }
      ],
      "Decision": "deny"
    },
    {
      "Name": "allow-api",
      "Resources": [
        {
          "Hosts": ["api.example.com"],
          "Ports": ["443"]
        }
      ],
      "Decision": "allow"
    }
  ]
}
deny-admin 必须位于 allow-api 前面，否则请求会先命中范围更宽的 allow Rule。
只允许 MySQL
{
  "DefaultDecision": "deny",
  "Rules": [
    {
      "Name": "allow-mysql",
      "Resources": [
        {
          "Ports": ["3306"]
        }
      ],
      "Decision": "allow"
    }
  ]
}
该规则允许任意目标的 3306 端口。若只允许指定数据库地址，应同时增加目标 IP 条件，或使用 destination.address 的 CEL 表达式。
转发到上游代理
{
  "DefaultDecision": "deny",
  "Rules": [
    {
      "Name": "proxy-api",
      "Resources": [
        {
          "Hosts": ["api.example.com"],
          "Ports": ["443"]
        }
      ],
      "Decision": "upstream",
      "UpstreamConfig": {
        "Host": "corporate-proxy.example.com",
        "Scheme": "https",
        "Port": 8443,
        "ForwardProxy": true
      }
    }
  ]
}
本示例使用 HTTP Forward Proxy：HTTP 使用 absolute-form 请求行，HTTPS 使用 CONNECT 隧道。若目标只是普通上游服务，可以省略 ForwardProxy；固定代理 Header 只能在 ForwardProxy=true 时配置。
deny 时发送审计通知
{
  "DefaultDecision": "deny",
  "Rules": [],
  "Hooks": [
    {
      "Name": "notify-deny",
      "Phase": "pre_upstream",
      "Category": "notify",
      "Priority": 10,
      "NotifyTriggerDecisions": ["deny"],
      "Webhook": {
        "URL": "https://audit.example.com/network-policy",
        "Timeout": "5s",
        "Headers": [
          {
            "Key": "Authorization",
            "Value": "Bearer <token>"
          }
        ]
      }
    }
  ]
}
notify 异步执行，调用失败不影响原请求。
使用 mutating Webhook 修改或拒绝请求
mutating Webhook 在请求转发前同步执行。Webhook 可以返回：
放行且不修改：
{
  "allowed": true,
  "mutations": []
}
设置或删除请求 Header：
{
  "allowed": true,
  "mutations": [
    {
      "target": "request.headers",
      "op": "set",
      "name": "X-Trace",
      "value": "trace-id"
    },
    {
      "target": "request.headers",
      "op": "remove",
      "name": "X-Legacy"
    }
  ]
}
拒绝请求：
{
  "allowed": false,
  "reason": "blocked_by_policy"
}
mutating Webhook 调用失败、超时或响应非法时，请求会被拒绝。
托管凭证注入与请求变换
NetworkPolicy 可以从托管凭证服务读取某个用户的 Secret，并在请求离开沙箱前写入 Header、JSON Body，或用于请求签名。Secret 不进入实例 Metadata、NetworkPolicy 或业务代码。
两类 CredentialProvider
凭证注入涉及两个名称相近、作用不同的对象：
对象
配置位置
作用
托管凭证资源
独立的 AGS CredentialProvider API
使用 Type=SecretMultiUser，按 UserId + Scope 保存 Secret。
NetworkPolicy Provider
NetworkPolicy.CredentialProviders
使用 Type=agentruntime，引用托管凭证资源并定义运行时取值方式。
NetworkPolicy Provider 的 Name 是策略内别名。例如：
{
  "Type": "agentruntime",
  "Name": "managed_secret",
  "ProviderConfig": {
    "ProviderId": "agc-xxxxxxxx",
    "SecretMultiUserParameter": {
      "UserId": "${metadata.user_id}",
      "Scope": "${metadata.scope}"
    }
  }
}
Transform 使用 credential.managed_secret 读取该 Provider 返回的 Secret。实例启动时只在 Metadata 中提供选择凭证所需的索引：
{
  "Metadata": [
    {
      "Name": "user_id",
      "Value": "user-a"
    },
    {
      "Name": "scope",
      "Value": "default"
    }
  ]
}
不要把 Secret 写入 Metadata、NetworkPolicy、Tool 配置或日志。公开 Cloud API 请求应使用 ProviderId；只填写 ProviderName 无法通过 CredentialProvider 资源鉴权。
使用前提
凭证注入依赖 Tool 级 Transform 能力：
Tool 必须使用 VPC 网络。
Tool 级 NetworkPolicy 必须至少有一条 Rule 包含 Transform。
只有 CredentialProviders、Rewrite、Hook 或普通 Upstream，不能启用凭证注入所需的平台能力。
ACTIVE Tool 可以修改已有 Transform 的内容，但不能在“有 Transform”和“无 Transform”之间切换；需要改变能力形态时应创建新 Tool。
实例级策略只有在 Tool 已包含 Transform 时，才能声明 CredentialProviders 或 Transform。
实例不传策略时继承 Tool 当时的策略快照；Tool 后续更新不会修改已创建实例。
请求如何执行
用户仍然请求原始业务地址，不需要填写平台内部地址或额外的 UpstreamConfig。执行链为：
沙箱应用请求原始地址
  → NetworkPolicy 匹配请求
  → 按实例 Metadata 选择托管凭证
  → 执行 Header、JSON Body 或签名 Transform
  → 请求继续访问原始业务地址
若需要先 Rewrite 再 Transform，应使用两条 Rule：前一条改写目标，后一条匹配改写后的目标并执行 Transform。Rewrite 和 Transform 不能配置在同一条 Rule 中。
完整示例
假设已创建 SecretMultiUser Provider，并为 user-a + default 写入测试 Secret。下面的 Tool 级策略只允许向 httpbin.org:443/anything 发起 POST 请求，并在转发前覆盖 Authorization、设置一个审计 Header，同时修改 JSON Body。
httpbin.org 会回显收到的 Header 和 Body。该示例只能使用临时测试 Secret，不能使用生产凭证。
{
  "DefaultDecision": "deny",
  "CredentialProviders": [
    {
      "Type": "agentruntime",
      "Name": "managed_secret",
      "ProviderConfig": {
        "ProviderId": "agc-xxxxxxxx",
        "SecretMultiUserParameter": {
          "UserId": "${metadata.user_id}",
          "Scope": "${metadata.scope}"
        }
      }
    }
  ],
  "Rules": [
    {
      "Name": "inject-managed-secret",
      "Decision": "allow",
      "Methods": ["POST"],
      "Resources": [
        {
          "Hosts": ["httpbin.org"],
          "Ports": ["443"],
          "PathPrefix": ["/anything"]
        }
      ],
      "Transform": {
        "TransformConfigurations": [
          {
            "TransformType": "Header",
            "HeaderTransformConfigurations": [
              {
                "Operation": "Set",
                "Header": "Authorization",
                "ValueExpression": "\\"Bearer \\" + credential.managed_secret"
              },
              {
                "Operation": "Set",
                "Header": "X-Network-Policy",
                "ValueExpression": "\\"managed-secret-injection\\""
              }
            ]
          },
          {
            "TransformType": "JsonBody",
            "JsonBodyTransformConfiguration": {
              "Operations": [
                {
                  "Op": "Set",
                  "Path": "/credential",
                  "ValueExpression": "credential.managed_secret"
                },
                {
                  "Op": "Set",
                  "Path": "/policy",
                  "ValueExpression": "\\"network-policy\\""
                }
              ]
            }
          }
        ]
      }
    }
  ]
}
静态值也必须写成合法的 CEL 字符串字面量，因此 JSON 中需要转义双引号。
Transform 执行语义
Transform 按 TransformConfigurations 数组顺序执行，同一配置块内再按操作数组顺序执行。
Header 操作：
Operation
行为
Set
删除同名 Header 的旧值，再写入新值。
Append
在当前值后追加；普通 Header 使用 ,，Cookie 使用 ;。
Remove
删除同名 Header，不需要 ValueExpression。
JSON Body 当前只支持 Set：
Path 使用 JSON Pointer，例如 /credential、/auth/token。
空 Body 按 {} 处理。
不存在的对象路径会创建。
同一路径多次 Set 时，后执行的值覆盖前面的值。
当前写入值为字符串；未操作的字段保持不变。
Rule 命中后即执行 JSON Body Transform，不以请求的 Content-Type 作为触发条件。
变换成功后，请求 Content-Type 会设置为 application/json。
Body 不是合法 JSON 时，请求会失败。
失败与安全边界
只有命中带 Transform 的 Rule 才会执行凭证注入；没有命中时，请求按其他 Rule 或 DefaultDecision 处理。
命中后，如果 ManagedSecret 获取失败、CEL 求值错误或 JSON Body 非法，请求会被阻断，通常表现为 400 或 502。
NetworkPolicy 仍应使用最小范围的 Host、Port、Path 和 Method 条件。
上游服务必须验证收到的凭证，不能仅凭请求来自沙箱就放行。
日志和错误响应不得输出 Secret、Authorization 或数据面 Token。
更新、就绪与清理
实例 RUNNING 只表示生命周期就绪，不保证凭证注入链路已经可用。若首次注入失败，可以短暂重试，但接口不承诺固定的就绪时间。
更新 Tool 的 Transform 不会自动修改已创建实例；需要更新实例策略或重新创建实例。
删除凭证资源前，应先停止依赖实例并删除或停用对应 Tool。
SecretMultiUser Provider 删除前，应先删除其 ManagedSecret，再将 Provider 置为 DISABLED，最后删除 Provider。
如果 Provider 被其他 Tool 复用，只删除不再使用的 ManagedSecret，不要删除整个 Provider。
字段参考
JSON 字段区分大小写，Cloud API 使用下表中的大驼峰字段名。
NetworkPolicy
字段
类型
必填
说明
DefaultDecision
string
否
allow 或 deny，默认 deny。
CredentialProviders
CredentialProvider[]
否
Transform 可引用的凭证来源，最多 100 个，Name 唯一。
Rules
NetworkPolicyRule[]
否
规则列表，最多 10000 条，Name 唯一。
Hooks
NetworkPolicyHook[]
否
全局 Hook，最多 100 个，Name 唯一。
NetworkPolicyRule
字段
类型
必填
说明
Name
string
是
最长 255 字符，策略内唯一。
Resources
NetworkPolicyResource[]
否
目标资源，最多 1024 个，Resource 之间为 OR。
Methods
string[]
否
HTTP 方法，最多 10 个；无固定枚举，* 表示任意方法，空数组不限制。
Expression
string
否
返回 bool 的 CEL 条件，最长 4096 字符；语法错误导致策略加载失败，求值错误拒绝请求。
Decision
string
是
allow、deny 或 upstream。
UpstreamConfig
NetworkPolicyUpstreamConfig
条件必填
Decision=upstream 时必填，其他 Decision 禁止。
Hooks
NetworkPolicyHook[]
否
规则级 Hook，最多 100 个，Name 在该 Rule 内唯一。
Rewrite
NetworkPolicyRewriteConfig
否
请求目标和路径改写。
Transform
NetworkPolicyTransform
否
Header、JSON Body 变换或请求签名。
Rewrite 与 Transform 不能出现在同一条 Rule 中；Decision=deny 时禁止配置 Transform。
NetworkPolicyResource
字段
类型
必填
说明
Hosts
string[]
否
IP、域名、通配域名、* 或模板，最多 20 个。
Ports
string[]
否
单端口、http、https、闭区间或模板，最多 20 个。
PathPrefix
string[]
否
HTTP 路径前缀，最多 20 个。
NetworkPolicyUpstreamConfig
字段
类型
必填
说明
Host
string
是
上游主机或 IP，最长 255 字符。
Scheme
string
否
http、https、auto 或模板，最长 1024 字符，默认 https。
Port
uint64
否
[0,65535]；0 且无 PortExpression 时按 Scheme 使用默认端口。
PortExpression
string
否
从 metadata URL 提取端口，与 Port 互斥。
ForwardProxy
bool
否
是否按 HTTP Forward Proxy 协议转发。
Headers
KeyValue[]
否
固定代理 Header，最多 100 个，仅允许与 ForwardProxy 一起使用。
Upstream Header 名必须是合法 HTTP Header 名，最长 255 字节；值不能为空，最长 4096 字节，且不能包含 CR 或 LF。
NetworkPolicyHook
字段
类型
必填
说明
Name
string
是
最长 255 字符，同级唯一。
Phase
string
是
当前仅支持 pre_upstream。
Category
string
是
notify 或 mutating。
Priority
uint64
否
有效值最大 2147483647；数值越大越先执行，相同值保持配置顺序。
Webhook
NetworkPolicyWebhook
条件必填
notify 和 mutating Hook 必须提供有效的 Webhook URL。
NotifyTriggerDecisions
string[]
否
allow、deny，最多 2 个且不可重复；省略时观察所有决策。
CaptureBody
bool
否
是否在 Hook 请求中包含捕获的请求 Body。
NetworkPolicyWebhook
字段
类型
必填
说明
URL
string
是
最长 2048 字符，以 http:// 或 https:// 开头，支持相应字段允许的模板。
Timeout
string
否
Go duration，正值且不超过 5m，默认 3s。
Headers
KeyValue[]
否
自定义 Header，最多 100 个。
Webhook Header 名必须是合法 HTTP Header 名，最长 255 字节；值最长 4096 字节且不能包含 CR 或 LF。Upstream Header 的值不能为空，Webhook Header 的值可以为空。
NetworkPolicyRewriteConfig
字段
类型
必填
说明
Scheme
string
是
http、https 或模板。
Host
string
是
改写后的主机，最长 255 字符。
Port
uint64
否
[0,65535]；0 且无 PortExpression 时按 Scheme 使用 80/443。
PortExpression
string
否
从 metadata URL 提取端口，与 Port 互斥。
PreserveHost
bool
否
是否保留原始 Host Header。
Path
NetworkPolicyPathRewriteRule[]
否
路径改写规则，最多 100 条，按数组顺序匹配。
Path Rule 字段：
字段
类型
说明
Match
string
exact、prefix、regex 或模板。
From
string
exact/prefix 必须以 / 开头；regex 必须合法。
To
string
单 / 开头的绝对路径，不能包含 scheme、host 或 query。
NetworkPolicyTransform
Transform 至少配置 TransformConfigurations 或 RequestSignature 之一。
字段
类型
说明
TransformConfigurations
TransformConfiguration[]
Header 或 JSON Body 变换
RequestSignature
RequestSignature
对最终上游请求签名
Transform 配置：
TransformType
配置
Header
HeaderTransformConfigurations 必须非空，支持 Set、Append、Remove
JsonBody
JsonBodyTransformConfiguration 必填，当前 Body Operation 仅支持 Set
Header Set、Append 和 JSON Body Set 必须提供合法的 CEL ValueExpression。JSON Body Path 使用 JSON Pointer。
RequestSignature.Algo 支持 TencentCloud、TencentCOS、Codebuddy_AgentGateway、AgentOSHook、WebhookQueryHMAC。SecretId 和 SecretKey 必填，并支持凭证模板。
CredentialProvider
字段
类型
必填
说明
Type
string
是
agentruntime 或 callback。
Name
string
是
最长 255 字符，策略内唯一。
ProviderConfig
ProviderConfig
条件必填
agentruntime 时必填，callback 时禁止。
CallbackProviderConfig
CallbackProviderConfig
条件必填
callback 时必填，agentruntime 时禁止。
AgentRuntime Provider：
公开 Cloud API 使用 ProviderId 引用托管凭证资源；ProviderName 不能代替 ProviderId 完成资源鉴权，二者最长 255 字符。
SecretMultiUserParameter.UserId 和 Scope 最长 1024 字符，支持 metadata 模板。
Transform 使用 credential.<provider> 引用，不追加 mapping key。
Callback Provider：
Request 和 Response 必填。
Mappings 最多 100 个，Name 唯一，Path 使用 JSON Pointer。
Transform 使用 credential.<provider>.<mapping> 引用。
CachePolicy.TTLSeconds 和 NegativeTTLSeconds 必须大于等于 0。
CallbackSignature.Algo 用于配置回调请求签名，仅支持 ProxyConfigTC3。
Callback Request：
Host 必填，最长 255 字符。
Scheme 为 http 或 https，Format 固定为 json。
Method 必填且最长 32 字符；Path 必须是绝对路径且最长 2048 字符。
Headers 最多 100 个，字段名使用 Header 和 Value；值可以为空，并支持相应字段允许的 metadata 和 credential 模板。
Body 和 CallbackSignature 可选；签名算法仅支持 ProxyConfigTC3。
Callback Response 的 Format 固定为 json；ConfigPath 非空时使用 JSON Pointer，ConfigFormat 为空或 json。CachePolicy.KeyFields[].Source 可取 Host、Scheme、Method、Path、Header、Query、Body 或 Metadata。
模板
部分字段支持：
${metadata.*}
${credential.*}
${url.scheme(...)}
${url.host(...)}
${url.authority(...)}
${url.port(...)}
${url.port_or_default(...)}
${url.path(...)}
${url.path_rel(...)}
每个字段允许使用的模板不同，非法模板会在策略校验时被拒绝。使用 CredentialProviders 或 Transform 前，需要在对应 Tool 上开通 Transform 能力。Tool 必须使用 VPC 网络；ACTIVE Tool 不能改变是否包含 Transform 的能力形态。
使用限制
使用条件
NetworkPolicy 需要先开通，并使用支持该能力的运行环境；未开通时接口会拒绝策略配置。
HTTPS 匹配要求客户端信任代理 CA，独立 TrustStore 可能需要额外配置。
Raw TCP 管控依赖支持透明 TCP 拦截的 Linux 运行环境。
实例策略使用 CredentialProviders 或 Transform 时，对应 Tool 必须具备 Transform 能力，并使用 VPC 网络。
数量限制
项目
上限
CredentialProviders
100
Rules
10000
全局 Hooks
100
单 Rule Hooks
100
单 Rule Resources
1024
单 Resource Hosts
20
单 Resource Ports
20
单 Resource PathPrefix
20
单 Rule Methods
10
CEL Expression
4096 字符
Rule Name、Hook Name
255 字符
Webhook URL
2048 字符
Webhook Headers
100
Webhook Timeout
5 分钟
Hook Priority 有效值
≤ 2147483647
Upstream Scheme
1024 字符
Rewrite Path Rules
100
Callback Mappings
100
Callback Host
255 字符
Callback Method
32 字符
Callback Path
2048 字符
常见错误
现象
原因或处理方式
根域被拒绝，但子域能访问
*.example.com 不匹配根域；同时添加 example.com。
更新成功后响应中没有策略
Update 只返回 RequestId；调用 Describe/List 回读。
E2B 返回 Invalid x-network-policy format
metadata 值不是合法 JSON 字符串，或包含未知字段。
HTTPS Host 能匹配，但 Path/Header/Body 不生效
确认 MITM 和 CA 信任是否生效。
CEL 访问 Body 后请求被拒绝
使用 has(request.body) 检查可选 Body。
MySQL/Redis 规则无法使用 Methods 或 Header
Raw TCP 没有 HTTP 语义，改用目标地址和端口。
配置 E2B network.allowPublicTraffic 后出口策略没有变化
该字段控制入口流量，与 NetworkPolicy 出口策略无关。
Update 在暂停实例上失败
实例恢复到 RUNNING 后再更新。
Forward Proxy Headers 校验失败
设置 ForwardProxy=true，并检查 Header 名和值。
mutating Webhook 异常后请求被拒绝
mutating 为 fail-closed，检查 URL、超时和响应格式。
Hook 配置后策略无法生效
检查 Webhook.URL 是否填写，Priority 是否超过 2147483647。
只填写 ProviderName 后鉴权失败
公开 Cloud API 使用 ProviderId 引用托管凭证资源。
实例配置 Transform 被拒绝
对应 Tool 必须已包含 Transform，并使用 VPC 网络。
端口范围校验失败
检查 [1,65535]，且展开数量不超过 4096。

Operation	行为
`Set`	删除同名 Header 的旧值，再写入新值。
`Append`	在当前值后追加；普通 Header 使用 `,`，Cookie 使用 `;`。
`Remove`	删除同名 Header，不需要 `ValueExpression`。

TransformType	配置
`Header`	`HeaderTransformConfigurations` 必须非空，支持 `Set`、`Append`、`Remove`
`JsonBody`	`JsonBodyTransformConfiguration` 必填，当前 Body Operation 仅支持 `Set`

组成	作用
`DefaultDecision`	没有 Rule 命中时执行 `allow` 或 `deny`，省略时默认为 `deny`
`Rules`	按数组顺序匹配流量；第一条命中的 Rule 决定处理结果
`Hooks`	在 HTTP 请求转发前执行异步通知或同步修改
`CredentialProviders`	为高级 Transform 提供可引用的凭证

Decision	行为
`allow`	放行，请求连接原目标。
`deny`	阻断；HTTP/HTTPS 请求返回 403，Raw TCP 连接被拒绝。
`upstream`	不直连原目标，将 HTTP 流量转发到指定上游。

需求	配置方式
只允许特定域名或 IP	`Resources[].Hosts`
限制端口或端口范围	`Resources[].Ports`
限制 HTTP 路径和方法	`PathPrefix + Methods`
按 Header、Body、CIDR 或时间判断	`Expression`
审计允许或拒绝的请求	`notify` Hook
注入或删除请求 Header	`mutating` Hook
从托管凭证注入 Header 或 JSON Body	`CredentialProviders + Transform`
强制流量经过企业代理	`Decision=upstream`
运行中替换策略	`UpdateSandboxInstance` 或 E2B Update

写法	匹配范围
`api.example.com`	只匹配该主机，大小写不敏感。
`*.example.com`	匹配 `api.example.com`、`v2.api.example.com` 等子域。
`*`	匹配任意主机。

写法	含义
`"443"`	单端口。
`"http"`	端口 80。
`"https"`	端口 443。
`"1000-2000"`	包含首尾的端口闭区间。

分类	变量或函数
请求	`request.host`、`request.path`、`request.method`、`request.scheme`、`request.port`、`request.query`、`request.protocol`、`request.size`
Header	`request.headers["key"]`，Header 名按小写访问
Body	`request.body.content`、`encoding`、`size`、`truncated`、`sha256`
目标	`destination.address`、`destination.port`
连接	`connection.tls`、`connection.tls_version`、`connection.sni`、`connection.alpn`
时间	`request.time`、`hour()`、`minute()`、`day_of_week()`、`day_of_month()`、`month()`
IP/CIDR	`ip()`、`cidr()`、`contains()`、`ip_in_cidrs()`
字符串	`split()`、`trim()`、`startsWith()`、`endsWith()`、`contains()`

接口	行为
`CreateSandboxTool`	设置 Tool 默认策略。
`UpdateSandboxTool`	更新 Tool 默认策略。
`StartSandboxInstance`	创建实例时设置实例级策略；不传时继承 Tool 当时的默认策略。
`UpdateSandboxInstance`	完整替换运行中实例的策略。
`StartSandboxInstanceResponse.Instance`	返回创建后实例保存的策略。
`DescribeSandboxInstance` / List	返回实例当前保存的策略。

输入	`StartSandboxInstance`	`UpdateSandboxInstance`
不传或 `null`	继承 Tool 默认策略	不更新
`{}`	创建默认拒绝的实例策略	完整替换为默认拒绝
`{"DefaultDecision":"deny","Rules":[]}`	明确拒绝全部	明确拒绝全部
`{"DefaultDecision":"allow","Rules":[]}`	明确允许全部	明确允许全部

对象	配置位置	作用
托管凭证资源	独立的 AGS CredentialProvider API	使用 `Type=SecretMultiUser`，按 UserId + Scope 保存 Secret。
NetworkPolicy Provider	`NetworkPolicy.CredentialProviders`	使用 `Type=agentruntime`，引用托管凭证资源并定义运行时取值方式。

字段	类型	必填	说明
`DefaultDecision`	string	否	`allow` 或 `deny`，默认 `deny`。
`CredentialProviders`	CredentialProvider[]	否	Transform 可引用的凭证来源，最多 100 个，Name 唯一。
`Rules`	NetworkPolicyRule[]	否	规则列表，最多 10000 条，Name 唯一。
`Hooks`	NetworkPolicyHook[]	否	全局 Hook，最多 100 个，Name 唯一。

项目	上限
CredentialProviders	100
Rules	10000
全局 Hooks	100
单 Rule Hooks	100
单 Rule Resources	1024
单 Resource Hosts	20
单 Resource Ports	20
单 Resource PathPrefix	20
单 Rule Methods	10
CEL Expression	4096 字符
Rule Name、Hook Name	255 字符
Webhook URL	2048 字符
Webhook Headers	100
Webhook Timeout	5 分钟
Hook Priority 有效值	≤ 2147483647
Upstream Scheme	1024 字符
Rewrite Path Rules	100
Callback Mappings	100
Callback Host	255 字符
Callback Method	32 字符
Callback Path	2048 字符

现象	原因或处理方式
根域被拒绝，但子域能访问	`*.example.com` 不匹配根域；同时添加 `example.com`。
更新成功后响应中没有策略	Update 只返回 `RequestId`；调用 Describe/List 回读。
E2B 返回 `Invalid x-network-policy format`	metadata 值不是合法 JSON 字符串，或包含未知字段。
HTTPS Host 能匹配，但 Path/Header/Body 不生效	确认 MITM 和 CA 信任是否生效。
CEL 访问 Body 后请求被拒绝	使用 `has(request.body)` 检查可选 Body。
MySQL/Redis 规则无法使用 Methods 或 Header	Raw TCP 没有 HTTP 语义，改用目标地址和端口。
配置 E2B `network.allowPublicTraffic` 后出口策略没有变化	该字段控制入口流量，与 NetworkPolicy 出口策略无关。
Update 在暂停实例上失败	实例恢复到 RUNNING 后再更新。
Forward Proxy Headers 校验失败	设置 `ForwardProxy=true`，并检查 Header 名和值。
mutating Webhook 异常后请求被拒绝	mutating 为 fail-closed，检查 URL、超时和响应格式。
Hook 配置后策略无法生效	检查 `Webhook.URL` 是否填写，Priority 是否超过 2147483647。
只填写 `ProviderName` 后鉴权失败	公开 Cloud API 使用 `ProviderId` 引用托管凭证资源。
实例配置 Transform 被拒绝	对应 Tool 必须已包含 Transform，并使用 VPC 网络。
端口范围校验失败	检查 `[1,65535]`，且展开数量不超过 4096。

网络策略（NetworkPolicy）

本页目录：

能力概述

适用场景

工作方式

策略模型

三种处理结果

可以控制到什么程度

策略匹配规则

Rule 顺序

Rule 内的条件

Host 匹配

Port 匹配

HTTP 与 Raw TCP

CEL 表达式

前提条件

快速开始

方式一：通过 Cloud API 创建实例

方式二：通过 E2B SDK 创建实例

验证结果

创建、继承与更新

原生 API

null、{} 和空 Rules

更新和回读

E2B 兼容入口

常见配置

完全拒绝或完全允许

先拒绝敏感路径，再放行其他路径

只允许 MySQL

转发到上游代理

deny 时发送审计通知

使用 mutating Webhook 修改或拒绝请求

托管凭证注入与请求变换

两类 CredentialProvider

使用前提

请求如何执行

完整示例

Transform 执行语义

失败与安全边界

更新、就绪与清理

字段参考

NetworkPolicy

NetworkPolicyRule

NetworkPolicyResource

NetworkPolicyUpstreamConfig

NetworkPolicyHook

NetworkPolicyWebhook

NetworkPolicyRewriteConfig

NetworkPolicyTransform

CredentialProvider

模板

使用限制

使用条件

数量限制

常见错误