Harbor 网络策略矩阵实战:共享环境下 Agent 与 Verifier 通配符 Allowlist 动态切换
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]
四个关键设计点:
- 基线策略是
no-network:[environment]的network_mode = "no-network"是环境启动时的默认网络状态,Agent 的setup()与环境的预置安装都在此策略下进行; - Agent 阶段切换到
allowlist:[agent]覆盖agent.run(),仅放行example.com(精确主机名)与*.amazonaws.com(前导通配符); - Verifier 阶段切换到另一个
allowlist:[verifier]覆盖verify(),仅放行*.iana.org,并通过environment_mode = "shared"显式声明与 Agent 共享同一环境实例; - 两阶段白名单互不相交:
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:
- 抓取
https://example.com/响应体,存到/logs/artifacts/example.html; - 对
s3.amazonaws.com:443做 TLS 连接尝试,成功写reachable,失败写blocked到s3-status.txt; - 对
noaa-goes16.s3.amazonaws.com:443做同样的 TLS 探测,结果写入noaa-s3-status.txt; - 尝试抓取
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)的实现会先做两件事:
- 调用
validate_network_policy_support,校验 provider 是否具备该策略所需能力(no-network需要disable_internet,allowlist需要network_allowlist,通配符条目还需要network_allowlist_wildcard_hostnames); - 若目标策略与当前不同但 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 阶段化网络策略的三项核心承诺:
- 策略按阶段隔离:Agent 与 Verifier 在同一沙箱内使用互斥的 allowlist,切换由
set_network_policy上下文管理严格保证; - 通配符语义精确:
*.amazonaws.com匹配任意深度子域、不匹配 apex 域,且条目须通过allowed_hosts的格式校验; - 能力前置校验:不声明
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 主机)也可在本地复现同样的验证逻辑。