Harbor 网络策略矩阵实战:共享环境下 Agent 与 Verifier 通配符 Allowlist 动态切换

原创2026-10-11 12:13:142,163 阅读
文章标签:人工智能大模型模型评测Agent 评测AI 评测Agent 沙箱CLI本地部署

Harbor 网络策略矩阵实战:共享环境下 Agent 与 Verifier 通配符 Allowlist 动态切换

本文以 Harbor 仓库中 examples/tasks/network-policy-matrix/dynamic/shared-allowlist 任务为样本,讲解如何在同一个共享环境(shared environment)里为 Agent 与 Verifier 配置互不相同的 allowlist 网络白名单,并由 Harbor 在 agent.run() 与 verify() 两个阶段之间动态切换网络策略。读完本文,你将掌握 task.toml 中 [environment]、[agent]、[verifier] 三段网络策略的语义与优先级、通配符条目(如 *.amazonaws.com)的匹配规则与校验约束,以及底层 set_network_policy 的调用时机与动态切换的 provider 能力要求,可直接复现本任务并用于设计自己的隔离验证任务。

任务背景:为什么需要共享环境下的策略切换

在 Agent 评测中,一个常见诉求是:Agent 阶段允许访问特定站点以完成解题,而Verifier 阶段则要求更严格的网络约束,防止验证脚本借助网络作弊或访问 Agent 曾接触的资源。Harbor 用"阶段化网络策略"(phase-scoped network policy)解决这个问题:[environment] 定义环境启动时的基线策略,[agent] 覆盖 agent.run() 阶段,[verifier] 覆盖 verify() 阶段。

当 Agent 与 Verifier 运行在同一个环境实例(environment_mode = "shared")中时,二者共用一套沙箱,Harbor 就必须在阶段切换时对运行中的环境动态调用 set_network_policy。这正是 shared-allowlist 任务要验证的场景:Agent 阶段放行 example.com 与 *.amazonaws.com,Verifier 阶段却只放行 *.iana.org,且两者都不能触达对方专属的域名。

该任务属于 Harbor 仓库中 Network Policy Matrix 的 dynamic/ 分支——即"至少有一个阶段的策略与基线不同、必须依赖运行时策略切换"的用例族;同一矩阵下还有 static/(无需切换)与 extra-allowed-hosts/(运行时白名单合并)两大类,供对照理解。

复现运行:一条命令拉起任务

在仓库根目录执行:

harbor run --path examples/tasks/network-policy-matrix/dynamic/shared-allowlist -e e2b -a oracle --n-concurrent 1 -y

参数含义:

  • --path:指向任务目录,Harbor 会读取其中的 task.toml、instruction.md、environment/ 与 tests/;
  • -e e2b:指定环境 provider 为 E2B——该 provider 在 E2B 环境实现 中声明了 dynamic_network_policy=True 与 network_allowlist_wildcard_hostnames=True,是动态切换与通配符白名单的必需能力;
  • -a oracle:使用内置 oracle Agent(直接执行任务提供的参考解法);
  • --n-concurrent 1:并发 trial 数设为 1,便于观察单次完整流程;
  • -y:跳过交互式确认。

如果想一次性跑完整个动态用例族(10 个任务),可以改用:

harbor run --path examples/tasks/network-policy-matrix/dynamic -e e2b -a oracle --n-concurrent 20 -y

需要说明:allowlist 与动态切换要求 provider 具备相应能力(见下文"能力契约"一节)。Docker 本地运行同样支持,但 allowlist 依赖 Harbor 的 egress-control sidecar(nftables 规则),要求 Linux 容器与内核 nft_fib 支持,Docker Desktop for macOS 的 LinuxKit VM 可能缺失该模块,此时可用 OrbStack 或在 Linux Docker 主机上运行(见 Network Policy Matrix 说明)。

任务定义解剖:task.toml 的三段网络策略

task.toml 是理解本用例的核心配置(schema 版本 1.3):

schema_version = "1.3"

[task]
name = "harbor/network-policy-dynamic-shared-allowlist"
description = "Demonstrates wildcard allowlist enforcement and shared verifier network policy switching."
keywords = ["network", "allowlist", "wildcard", "verifier"]

[metadata]
difficulty = "easy"
category = "infrastructure"

[environment]
network_mode = "no-network"
build_timeout_sec = 600.0
cpus = 1
memory_mb = 2048
storage_mb = 10240
gpus = 0
mcp_servers = []

[agent]
network_mode = "allowlist"
allowed_hosts = ["example.com", "*.amazonaws.com"]
timeout_sec = 120.0

[verifier]
network_mode = "allowlist"
allowed_hosts = ["*.iana.org"]
environment_mode = "shared"
timeout_sec = 60.0

[verifier.env]

[environment.env]

[solution.env]

四个关键设计点:

  1. 基线策略是 no-network:[environment] 的 network_mode = "no-network" 是环境启动时的默认网络状态,Agent 的 setup() 与环境的预置安装都在此策略下进行;
  2. Agent 阶段切换到 allowlist:[agent] 覆盖 agent.run(),仅放行 example.com(精确主机名)与 *.amazonaws.com(前导通配符);
  3. Verifier 阶段切换到另一个 allowlist:[verifier] 覆盖 verify(),仅放行 *.iana.org,并通过 environment_mode = "shared" 显式声明与 Agent 共享同一环境实例;
  4. 两阶段白名单互不相交:example.com/*.amazonaws.com 与 *.iana.org 无重叠,从而验证"切换必须真实生效"。

这里 <a href="https://link.gitcode.com/i/ae26014de37750f417f005f82715488f" target="_blank">agent]、[verifier] 都属于"阶段覆盖"(phase override)。阶段语义在 [Harbor 官方网络策略文档 中有完整描述:[agent] 只在 agent.run() 期间生效(不覆盖 agent.setup()),[verifier] 只在 verify() 期间生效;若某阶段未配置覆盖,则继承所在沙箱的基线策略。

通配符条目的语法约束

*.amazonaws.com 这类"前导通配符"条目不是随便写的。从 任务配置模型 的 _validate_allowed_host_names 可以看到严格校验:

  • 通配符必须以 *. 前缀开头(* 出现在其他位置会直接报错:"wildcard entries must use a leading '*.' prefix");
  • 通配符后缀必须是合法主机名,不能是 IP 字面量;
  • 条目只能是主机名、IP 地址或 CIDR,不允许携带 URL、端口或路径;
  • 主机名会做小写化、去尾部点号的归一化处理。

校验通过后由 classify_network_allowlist_entry 将条目分类为 hostname / wildcard-hostname / ipv4-address / ipv6-address / ipv4-cidr / ipv6-cidr 六种类型之一。

Agent 侧验证:通配符匹配多个主机名标签

instruction.md 给 Agent 布置了 4 项网络探测任务,参考解法见 solve.sh:

  1. 抓取 https://example.com/ 响应体,存到 /logs/artifacts/example.html;
  2. 对 s3.amazonaws.com:443 做 TLS 连接尝试,成功写 reachable,失败写 blocked 到 s3-status.txt;
  3. 对 noaa-goes16.s3.amazonaws.com:443 做同样的 TLS 探测,结果写入 noaa-s3-status.txt;
  4. 尝试抓取 https://github.com/,失败写 blocked,成功写 reachable 到 github-status.txt。

核心探测逻辑(节选自 solve.sh):

def tls_status(host: str, timeout: float = 5) -> str:
    context = ssl._create_unverified_context()
    try:
        with socket.create_connection((host, 443), timeout=timeout) as sock:
            with context.wrap_socket(sock, server_hostname=host):
                return "reachable"
    except Exception:
        return "blocked"

这里的精妙之处:*.amazonaws.com 既要能匹配单标签子域 s3.amazonaws.com,也要能匹配多标签子域 noaa-goes16.s3.amazonaws.com(s3 与 noaa-goes16 都是 amazonaws.com 的子域)。如果通配符只能匹配一层子域,第二个探测就会返回 blocked,从而暴露实现缺陷。官方文档明确:前导通配符"匹配任意深度的子域,但不匹配 apex 域本身"(wildcard matches subdomains at any depth but not the apex domain)。

Verifier 侧验证:隔离性与 apex 域负例

test.sh 是真正的裁判,它把 reward 拆成多个独立的失败点,任何一项不满足都会让 reward 归零:

正向断言(在 Verifier 白名单内必须可达):

request = Request("https://www.iana.org/domains/example", headers={"User-Agent": "harbor-verifier"})
with urlopen(request, timeout=5) as response:
    body = response.read().decode(errors="ignore").lower()
if "example domains" not in body:
    raise SystemExit(1)

负向断言 1:*.iana.org 不得匹配 apex 域 iana.org

request = Request("https://iana.org/", headers={"User-Agent": "harbor-verifier"})
try:
    with urlopen(request, timeout=3) as response:
        response.read(1)
except Exception:
    raise SystemExit(1)   # 连接失败 → 判为通过

负向断言 2:不得触达 Agent 专属域名

# example.com 与 s3.amazonaws.com 都不在 verifier allowlist 中,
# 任何一条成功连接都会让 test.sh 输出 "verifier unexpectedly reached ..." 并使 reward=0

三个负例合起来证明:动态切换是双向的——不仅 Verifier 不能继承 Agent 的白名单,Agent 的专属域也不能在 Verifier 阶段继续访问,同时通配符不会"越权"匹配到 apex 域。这正是 shared-allowlist 与 e-v-diff(基线/阶段在 public 与 no-network 间切换)等用例的区别:它在同为 allowlist 的两个不同白名单之间切换,检验的是白名单内容而非开关状态。

源码原理:Harbor 如何编排这次切换

网络计划解析

Trial 启动时会调用 resolve_trial_network_plan 计算出四个关键策略:

字段 含义 本任务取值
agent_env_baseline 环境启动基线 no-network
agent_phase agent.run() 期间策略 allowlist: [example.com, *.amazonaws.com]
verifier_env_baseline 独立 verifier 环境的基线(shared 模式为 None) None
verifier_phase verify() 期间策略 allowlist: [*.iana.org]

shared 模式下 verifier_env_baseline 为 None,verifier_phase_baseline 直接取 agent_env_baseline(见 TrialNetworkPlan.verifier_phase_baseline),即:共享环境的 Verifier 策略基线就是 Agent 环境基线,验证器阶段策略与它不同,就必须动态切换。

切换的时机:一个异步上下文管理器

Trial 的核心编排在 trial.py 中。_phase_network_policy 是一个 asynccontextmanager(L341-L357):

if phase_policy == baseline_policy:
    yield
    return

await environment.set_network_policy(phase_policy)
try:
    yield
finally:
    await environment.set_network_policy(baseline_policy)

Agent 阶段(L626-L630)与验证阶段(L888-L892)都包在这个上下文里:

  • agent.run() 前:set_network_policy(agent_phase) → 切到 [example.com, *.amazonaws.com];
  • agent.run() 结束:set_network_policy(baseline) → 回到 no-network;
  • verify() 前:set_network_policy(verifier_phase) → 切到 [*.iana.org];
  • verify() 结束:set_network_policy(baseline) → 再次回到 no-network。

完整调用序列正好对应 test_network_policy.py 中 test_switches_network_policy_around_agent_and_verify 的断言:

assert switched_policies == [
    agent_phase,        # agent.run() 前
    environment_baseline,  # agent.run() 后
    verifier_phase,     # verify() 前
    environment_baseline,  # verify() 后
]

能力契约:provider 必须声明 dynamic_network_policy

动态切换不是所有环境都能做的。BaseEnvironment.set_network_policy(environments/base.py)的实现会先做两件事:

  1. 调用 validate_network_policy_support,校验 provider 是否具备该策略所需能力(no-network 需要 disable_internet,allowlist 需要 network_allowlist,通配符条目还需要 network_allowlist_wildcard_hostnames);
  2. 若目标策略与当前不同但 provider 未声明 dynamic_network_policy,直接抛出 ValueError: ... cannot change network policy after start。

这些能力由 EnvironmentCapabilities 声明。E2B 的实现(e2b.py)完整启用了域名白名单、通配符主机名与运行时切换,并在 _sandbox_network_update 中把策略翻译为 E2B 的 allow_internet_access / allow_out / deny_out 网络参数——这就是为什么任务运行命令强制指定 -e e2b。

如果 provider 不支持动态切换,Trial 创建阶段会直接拒绝任务(shared 模式下 verifier 阶段策略不同即报错),而不是"带病运行"。对应测试见 test_rejects_verifier_phase_without_dynamic_switch。

横向对照:本用例在 Network Policy Matrix 中的位置

要理解 shared-allowlist 的定位,可以把它放进整个矩阵(network-policy-matrix/README.md)里对比:

用例 策略布局 验证要点
static/e-allowlist 仅 [environment] 为 allowlist,无阶段覆盖 基线白名单 + 自 IP 本地 IPC 不被代理
dynamic/e-a-diff e=no-network,agent 阶段 public 开关型动态切换
dynamic/e-v-diff e=public,verifier 阶段 no-network 共享环境关闭网络
dynamic/shared-allowlist e=no-network,agent/verifier 为两个不同的 allowlist 白名单内容级动态切换 + 通配符语义
dynamic/sv-sve-diff 多步任务中 sv != sve step 级独立 verifier 策略
extra-allowed-hosts/a-allow-agent-host 运行期 --allow-agent-host 合并 不改 task.toml 即开放单主机

矩阵 README 还总结了一条规律:静态用例(阶段与基线一致)不触发 set_network_policy,动态用例则要求 provider 支持 dynamic_network_policy。单元测试 tests/unit/trial/test_network_policy.py 同时断言了这两类行为——静态用例断言 phase == baseline,动态用例断言 set_network_policy 的调用模式。

延伸:从共享到独立 Verifier 环境的取舍

本任务使用 environment_mode = "shared"(与 <a href="https://link.gitcode.com/i/ee50976433040c31dc3b8583b1ea14d2" target="_blank">verifier] 同节声明)。Harbor 还支持 "separate" 模式:此时 Verifier 启动独立环境实例,其基线由 [verifier.environment] 段定义(官方文档见 [separate-verifier),verifier_env_baseline 不再是 None,切换发生在 verifier 环境自身的 set_network_policy 上(对应测试 test_separate_verifier_phase_switch)。

两者的取舍:

  • shared:资源开销小、产物天然同环境,但 Agent 与 Verifier 必须共享网络切换序列,任何阶段残留的连通性都可能被另一个阶段利用——这正是本任务负例要堵的漏洞;
  • separate:更强的隔离(环境、网络、文件系统全部分离),适合对 reward hacking 高度敏感的任务,代价是额外启动一个沙箱与产物传输。

小结

shared-allowlist 任务用一套极简的探测脚本,完整覆盖了 Harbor 阶段化网络策略的三项核心承诺:

  1. 策略按阶段隔离:Agent 与 Verifier 在同一沙箱内使用互斥的 allowlist,切换由 set_network_policy 上下文管理严格保证;
  2. 通配符语义精确:*.amazonaws.com 匹配任意深度子域、不匹配 apex 域,且条目须通过 allowed_hosts 的格式校验;
  3. 能力前置校验:不声明 dynamic_network_policy / network_allowlist_wildcard_hostnames 的 provider 会在验证期被拒绝,杜绝"静默降级"。

想深入源码的读者,建议按此顺序阅读:task.toml → solve.sh → test.sh → network_policy.py → trial.py → test_network_policy.py;把 e2b 换成 docker(Linux 主机)也可在本地复现同样的验证逻辑。

登录后查看全文
harbor