Harbor 环境网络策略 allowlist 模式实战:从 e-allowlist 任务到 egress 控制侧车
Harbor 环境网络策略 allowlist 模式实战:从 e-allowlist 任务到 egress 控制侧车
导读
本篇文章围绕 Harbor 仓库中 network-policy-matrix/static/e-allowlist 任务展开,深入讲解 Harbor 任务配置中 [environment].network_mode = "allowlist" 与 allowed_hosts 的完整语义:如何在 Agent 与 Verifier 两个阶段同时生效、如何通过 egress 控制侧车(sidecar)在底层落地、以及如何编写与验证允许列表网络策略。读完本文,你将掌握 Harbor 网络策略的三态模型、allowed_hosts 的六类合法条目与校验规则、透明代理 + nftables 的实现原理,并能独立编写和验证属于自己的 allowlist 网络任务。
一、任务全景:e-allowlist 在验证什么
1.1 任务定位
e-allowlist 是 network-policy-matrix(网络策略矩阵)中 static/(静态)分组下的一个基础用例。它的核心目标是验证:
环境基线(baseline)的 allowlist 网络策略会被 Agent 阶段和 Verifier 阶段同时继承,且无需任何动态策略切换。
从矩阵速记法来看,e 代表 <a href="https://link.gitcode.com/i/9ebc433a440227ffcced23a3723caa16" target="_blank">environment].network_mode,该任务只有 e 这一个维度被显式设置,没有 [agent]、[verifier]、[steps.*] 等任何阶段的覆盖项,因此 Harbor 在 agent.run() 与 verify() 期间都不应调用 set_network_policy(参见 [矩阵 README)。
1.2 任务指令原文解读
instruction.md 给出了 Agent 需要完成的四步探测,全部围绕"允许列表内外"的连通性对比展开:
- 正向域名用例:抓取
https://example.com/响应体,保存到/logs/artifacts/example.html——example.com在允许列表内,必须成功。 - 负向域名用例:尝试抓取
https://github.com/,失败则写blocked,成功则写reachable到/logs/artifacts/github-status.txt——github.com不在允许列表内,预期blocked。 - 正向 IP 用例:向
1.1.1.1:443发起 TLS 连接,成功写reachable,失败写blocked到/logs/artifacts/cloudflare-ip-status.txt——1.1.1.1在允许列表内,预期reachable。 - 负向 IP 用例:向
8.8.8.8:443发起 TLS 连接,失败写blocked,成功写reachable到/logs/artifacts/google-ip-status.txt——8.8.8.8不在允许列表内,预期blocked。
任务元数据将其归类为 difficulty = "easy"、category = "infrastructure",关键词为 ["network", "environment", "allowlist"],是理解 Harbor 网络策略的最简入口。
1.3 任务配置文件:task.toml
任务的全部网络策略都定义在 task.toml 中,核心字段如下:
schema_version = "1.3"
[task]
name = "harbor/network-policy-static-e-allowlist"
description = "Verifies an environment baseline allowlist inherited by both agent and verifier phases."
[environment]
network_mode = "allowlist"
allowed_hosts = ["example.com", "1.1.1.1"]
build_timeout_sec = 600.0
cpus = 1
memory_mb = 2048
storage_mb = 10240
gpus = 0
mcp_servers = []
[agent]
timeout_sec = 120.0
[verifier]
timeout_sec = 60.0
各字段含义:
| 字段 | 值 | 说明 |
|---|---|---|
[environment].network_mode |
"allowlist" |
环境基线网络策略:仅允许访问 allowed_hosts 列出的目标 |
[environment].allowed_hosts |
["example.com", "1.1.1.1"] |
允许列表,同时包含域名与 IP 地址字面量两种类型 |
[environment].build_timeout_sec |
600.0 |
环境构建超时(默认 10 分钟) |
[agent].timeout_sec |
120.0 |
Agent 阶段运行超时 |
[verifier].timeout_sec |
60.0 |
Verifier 阶段运行超时 |
环境镜像本身极为精简(Dockerfile 只有一行 FROM python:3.12-slim),说明该任务刻意不依赖任何预装工具,探测逻辑全部由 Agent 在运行时用 Python 标准库完成——这恰好证明"allowlist 网络策略是任务环境的基础属性,与镜像内容无关"。
二、Harbor 网络策略模型:network_mode 与 allowed_hosts
2.1 三态网络模式枚举
Harbor 将网络访问策略抽象为三种模式,定义在 src/harbor/models/task/config.py 的 NetworkMode 枚举中:
no-network:完全禁止出站网络访问;public:不做任何限制(也是环境基线的默认值);allowlist:仅允许访问allowed_hosts中列出的目标,其余 TCP 出站一律被拒绝。
从源码结构看,no-network 与 allowlist 在实现层面都走同一套 egress 控制路径,只是允许列表分别为"空"与"非空";而 public 则完全旁路侧车。
2.2 allowed_hosts 的六类合法条目
NetworkAllowlistEntryType(config.py)将允许列表条目细分为六种类型,classify_network_allowlist_entry(config.py)负责在运行时识别它们:
| 条目类型 | 示例 | 说明 |
|---|---|---|
hostname |
example.com |
精确主机名 |
wildcard-hostname |
*.example.com |
前导通配主机名 |
ipv4-address |
1.1.1.1 |
IPv4 地址字面量 |
ipv6-address |
2001:db8::1 |
IPv6 地址字面量 |
ipv4-cidr |
192.0.2.0/24 |
IPv4 CIDR 网段 |
ipv6-cidr |
2001:db8::/32 |
IPv6 CIDR 网段 |
NetworkPolicy 模型(config.py)内置了一条关键校验规则:allowed_hosts 只有在 network_mode = "allowlist" 时才合法,其余模式下声明该字段会直接触发 ValidationError("allowed_hosts is only valid when network_mode='allowlist'.")。
2.3 条目的规范化与校验规则
_validate_allowed_host_names(config.py)在解析 task.toml 时对每条目的做严格清洗与校验:
- 大小写与小尾巴:统一转小写、去掉末尾的
.("PyPI.org"→pypi.org、"ubuntu.com."→ubuntu.com),单元测试 test_task_config_network.py 对此有专门覆盖; - CIDR 严格模式:
ip_network(host, strict=True)解析,192.0.2.1/24(带主机位)会被拒绝; - IPv6 压缩:
2001:0DB8:0000:...:0001会被压缩为2001:db8::1;带作用域(%eth0)的地址被拒绝; - 通配符规则:只允许前导
*.形式(如*.iana.org),*、pypi.*、api.*.pypi.org、*.1.1.1.1(对 IP 字面量做通配)等非法形态全部被拒; - 禁止 URL / 端口 / 路径:
https://pypi.org/simple、pypi.org:443这类写法会报 "allowed_hosts entries must be hostnames, IP addresses, or IP CIDR ranges, not URLs, ports, or paths."
上述校验行为在 tests/unit/models/test_task_config_network.py 中有成体系的参数化测试佐证。
2.4 基线继承:Agent 与 Verifier 如何共享 allowlist
e-allowlist 任务未设置任何阶段覆盖,其生效链路由 src/harbor/trial/network_policy.py 中的 resolve_trial_network_plan(network_policy.py)统一求解:
resolve_agent_env_baseline从[environment]求出 Agent 阶段的环境基线(含运行期extra_allowed_hosts合并);resolve_agent_phase_policy检查[agent]/[steps.agent]是否有显式覆盖,没有则回退到环境基线——e-allowlist 的 Agent 阶段策略就等于环境基线;- Verifier 阶段默认共享 Agent 环境(
shared模式),verifier_phase_baseline = agent_env_baseline; resolve_verifier_phase_policy同样先查[verifier]显式覆盖,无覆盖则使用基线——Verifier 阶段策略同样等于环境基线。
最终 TrialNetworkPlan 中 agent_phase == agent_env_baseline == verifier_phase,这就是"allowlist 对两个阶段同时生效"的模型级保证。静态分组(无阶段切换)时,Harbor 不应调用 set_network_policy,这一点由 矩阵 README 明确说明。
三、Agent 侧实战:用 Python 标准库完成四项探测
参考实现(solution/solve.sh,供 Oracle Agent 使用)清晰地示范了如何在受限环境下完成探测。核心逻辑是一个内嵌的 Python 脚本,只依赖 socket、ssl、urllib.request、pathlib 四个标准库:
#!/bin/bash
set -euo pipefail
mkdir -p /logs/artifacts
python3 - <<'PY'
import socket
import ssl
from pathlib import Path
from urllib.request import Request, urlopen
def fetch(url: str, timeout: float = 15) -> bytes:
request = Request(
url,
headers={"User-Agent": "harbor-network-policy-environment-allowlist"},
)
with urlopen(request, timeout=timeout) as response:
return response.read()
def tls_status(host: str, timeout: float = 5) -> str:
try:
raw = socket.create_connection((host, 443), timeout=timeout)
context = ssl.create_default_context()
context.check_hostname = False
context.verify_mode = ssl.CERT_NONE
with context.wrap_socket(raw, server_hostname=None):
return "reachable"
except Exception:
return "blocked"
其中两个小技巧值得留意:
- TLS 探测:
tls_status显式关闭证书校验(check_hostname=False、verify_mode=CERT_NONE)且不传server_hostname,目的是只测网络层连通性,而非 TLS 握手完整性——这正是"探测策略是否放行"的正确姿势; - 探测超时:正向请求给 15 秒,负向请求收紧到 5 秒,避免被策略拒绝时陷入长时间阻塞。
随后按任务指令依次产出四个工件文件:
Path("/logs/artifacts/example.html").write_bytes(fetch("https://example.com/"))
try:
fetch("https://github.com/", timeout=5)
github_status = "reachable"
except Exception:
github_status = "blocked"
Path("/logs/artifacts/github-status.txt").write_text(github_status)
Path("/logs/artifacts/cloudflare-ip-status.txt").write_text(tls_status("1.1.1.1"))
Path("/logs/artifacts/google-ip-status.txt").write_text(tls_status("8.8.8.8"))
注意一个细节:github.com 与 8.8.8.8 的探测必须失败。在 Harbor 的 allowlist 实现中,非白名单 TCP 出站会被透明代理直接断开连接,因此 urlopen/socket.create_connection 抛出异常、写入 blocked,而不是"成功但内容为空"。
四、Verifier 侧深入:如何证明 allowlist 对两个阶段都生效
test.sh 是这份任务真正的"考试卷",它从四个维度验证策略完整性,远不止核对工件文本。
4.1 维度一:Agent 工件的内容级校验
Verifier 先检查四个工件都存在且非空,然后不止校验状态字符串,还校验了内容语义:
example.html必须包含"example domain"字样(说明 Agent 确实拿到了 example.com 的真实页面,而非一个被策略拦截后的错误页);github-status.txt必须等于blocked;cloudflare-ip-status.txt必须等于reachable;google-ip-status.txt必须等于blocked。
任何一项不符都会通过 fail() 将 reward 置 0。
4.2 维度二:Verifier 自身的连通性(防止"只在 Agent 阶段放行"的假实现)
Verifier 在自己的进程内重新发起正向探测:抓取 example.com 并校验内容、对 1.1.1.1:443 做 TLS 探测。这证明 allowlist 策略在 Verifier 阶段同样生效,而不是仅仅放行了 Agent 的出口。随后再以负向用例确认:github.com 与 8.8.8.8:443 在 Verifier 阶段同样被拦截。
4.3 维度三:本地 IPC 不得被误代理
test.sh 包含一个容易被忽略的回归断言:容器内进程到自身可路由 IP 的本地 TCP 连接(如 torch/gloo 的 rendezvous)属于内网通信,不是出站,必须绕过 egress 代理。脚本通过 UDP connect 探测自身非回环 IP,然后建立本地 listen/accept 连接并收发 ping 载荷验证。相关注释指出,历史上 NAT 链在没有匹配 fib daddr type local 时会把这种自连接也重定向进 gost 代理从而导致关闭(test.sh)。
4.4 维度四:DNS 解析不得被策略误伤
最微妙的是 DNS 断言:即使 allowlist 不包含解析器地址,容器的 DNS 查询(UDP/TCP 53)也必须正常工作。脚本手工构造了一条极简的 example.com A 记录查询(事务 ID 0x4242),同时验证 UDP 与 TCP 两条路径都能收到匹配事务 ID 的响应(test.sh)。这一断言直接对应底层实现中"DNS 必须按 resolv.conf 里的 nameserver 放行"的规则。
五、底层实现:Docker egress 控制侧车
allowlist 之所以能在 Linux Docker 容器中落地,靠的是 Harbor 的 egress-control sidecar(相关代码位于 src/harbor/environments/docker/harbor-docker-egress-control-sidecar)。
5.1 控制脚本 network-policy
侧车内提供 network-policy 命令(bin/network-policy),支持五个子命令:
network-policy show
network-policy allow-all
network-policy deny-all
network-policy allow [TARGET...]
network-policy rules
其中 allow <a href="https://link.gitcode.com/i/c8219db520e2796526f0650d6b95fd8b" target="_blank">TARGET...] 是 e-allowlist 任务实际使用的路径:TARGET 支持域名、通配域名、IP、CIDR 或 IP 范围,不带参数时表示拒绝所有受控 TCP 出站。Docker 环境驱动在启动侧车时会根据解析出的网络策略调用它(见 [src/harbor/environments/docker/docker.py 的策略分发逻辑,其中 PUBLIC 对应 allow-all,ALLOWLIST 对应 allow + 全部 allowed_hosts,NO_NETWORK 对应 deny-all)。
5.2 双层强制:nftables + gost 透明代理
侧车的强制机制是"按目标类型分流的双层方案":
- 域名 / 通配域名:无法在 nftables 中直接表达,交给 gost.yaml 中运行的 gost 透明代理按 SNI 嗅探做域名级 allowlist 匹配(
sniffing: true),放行名单文件为/opt/egress-sidecar/allowlist.txt,reload: 1s热加载; - IP / CIDR:由 nftables 规则集
gost_egress直接放行或拒绝。
协作流程是:nftables 的 output 链(NAT hook)把所有 TCP 出站 redirect to :12345 送入 gost,但命中 meta mark 114514(gost 已处理过的流量标记)或 fib daddr type local(本地目标)的流量直接 return 绕过;egress 链(filter hook)则负责拒绝非 TCP(ICMP 放行、其余 reject)。侧车在 allow 命令里会先写白名单文件并等待 RELOAD_WAIT=2 秒(确保 gost 已加载新名单),再启用 nftables 规则,避免出现"名单未就绪先封网"的窗口。
5.3 两个特殊的放行例外
脚本中有两处刻意的例外,正是上一节两个回归断言的实现依据:
- 本地目标放行:
fib daddr type local return/accept。Docker 将容器resolv.conf指向网络网关,再通过 DNAT 把网关:53转发到内嵌解析器,只有fib daddr type local(在 DNAT 后重新评估)能识别这种"目标在重定向后变为本地"的流量,否则任何不含解析器地址的 allowlist 都会导致 DNS 断裂(bin/network-policy 与 test.sh 互为印证); - resolv.conf 中的 nameserver 放行:
nft_dns_rules从/etc/resolv.conf提取 nameserver,为 UDP/TCP 53 生成放行规则——对 Docker 是兜底,对 Podman(无 DNAT 的内嵌解析器)则是必需。
5.4 内核与平台前提
侧车规则依赖 Linux 内核的 nft_fib 支持。矩阵 README(examples/tasks/network-policy-matrix/README.md)明确提示:
- Docker Windows 容器不支持
no-network、allowlist与动态切换,这些用例需要 Docker Linux 容器; - Docker Desktop for macOS 的 LinuxKit VM 内核可能缺少该模块,
nft会拒绝fib daddr type local规则导致侧车启动失败;此时应改用 OrbStack 等自带完整 nftables 内核支持的 Linux 运行时,或直接在 Linux Docker 主机上运行; - 运行时测试通过
DockerEnvironment._egress_control_kernel_support()探测守护进程内核能力,不满足则自动 skip(tests/runtime/test_network_policy_matrix_docker.py)。
六、运行与自动化验证
6.1 通过 Harbor CLI 运行
在仓库根目录下,可以用 Harbor CLI 运行整个网络策略矩阵(需要 E2B 环境与 oracle Agent):
harbor run --path examples/tasks/network-policy-matrix -e e2b -a oracle --n-concurrent 20 -y
只运行静态分组(本任务所在分组):
harbor run --path examples/tasks/network-policy-matrix/static -e e2b -a oracle --n-concurrent 20 -y
运行动态分组(需要 set_network_policy 运行时切换,仅 E2B 等支持 dynamic_network_policy 的 provider):
harbor run --path examples/tasks/network-policy-matrix/dynamic -e e2b -a oracle --n-concurrent 20 -y
6.2 运行时测试矩阵
仓库把该任务纳入自动化测试:NETWORK_POLICY_MATRIX_TASKS 列表包含 static/e-allowlist 与 static/e-allowlist-ipv4-cidr,测试以 oracle Agent 在 Docker 上真实跑通全部 22 个任务,断言 exception_info is None 且 reward 为 1.0(tests/runtime/test_network_policy_matrix_docker.py)。同一目录还提供 Podman 版本 test_network_policy_matrix_podman.py。此外 tests/unit/trial/test_network_policy.py 在单元层面断言静态用例的 phase == baseline 等式,以及动态用例的 set_network_policy 调用模式(见 矩阵 README)。
七、延伸阅读:矩阵中的相邻用例
理解 e-allowlist 后,可以对照矩阵中的其他用例巩固知识:
static/e-allowlist-ipv4-cidr:同一继承语义,但allowed_hosts = <a href="https://link.gitcode.com/i/4cfc371211f5dc1ec795505dcd0afb43" target="_blank">"1.1.1.0/24"],验证 CIDR 条目(网段内1.1.1.1可达、网段外8.8.8.8被阻断),见 [其 task.toml;dynamic/分组:任一阶段策略与基线不同,需要动态切换,如e-a-diff(no-network→ Agentpublic)、shared-allowlist(共享环境、Agent 与 Verifier 使用不同 allowlist);extra-allowed-hosts/分组:通过运行期标志(如--allow-agent-host=www.iana.org)临时合并放行主机而不改动任务配置,默认得分 0、带标志得分 1,相关实现见 src/harbor/trial/network_policy.py 的merge_extra_allowlists,运行时测试见 test_network_policy_matrix_docker.py。
总结
e-allowlist 是 Harbor 网络策略体系中最精简也最完整的一块拼图:task.toml 声明基线策略,instruction.md 用正反用例定义行为契约,solve.sh 展示受限环境下的探测写法,test.sh 从工件内容、双阶段连通性、本地 IPC、DNS 四个维度堵住实现漏洞,而 egress 侧车则用"nftables 管 IP、gost 管域名"的双层方案把策略落成真实约束。理解了这条链路,你就能自信地在 Harbor 中设计"既隔离又受控"的 Agent 评测环境——无论是精确域名、IP 字面量还是 CIDR 网段,allowlist 都能以一致、可验证的方式施加到 Agent 与 Verifier 的每一行代码上。