Harbor 环境网络策略 allowlist 模式实战:从 e-allowlist 任务到 egress 控制侧车

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

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 需要完成的四步探测,全部围绕"允许列表内外"的连通性对比展开:

  1. 正向域名用例:抓取 https://example.com/ 响应体,保存到 /logs/artifacts/example.html —— example.com 在允许列表内,必须成功。
  2. 负向域名用例:尝试抓取 https://github.com/,失败则写 blocked,成功则写 reachable 到 /logs/artifacts/github-status.txt —— github.com 不在允许列表内,预期 blocked。
  3. 正向 IP 用例:向 1.1.1.1:443 发起 TLS 连接,成功写 reachable,失败写 blocked 到 /logs/artifacts/cloudflare-ip-status.txt —— 1.1.1.1 在允许列表内,预期 reachable。
  4. 负向 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)统一求解:

  1. resolve_agent_env_baseline 从 [environment] 求出 Agent 阶段的环境基线(含运行期 extra_allowed_hosts 合并);
  2. resolve_agent_phase_policy 检查 [agent] / [steps.agent] 是否有显式覆盖,没有则回退到环境基线——e-allowlist 的 Agent 阶段策略就等于环境基线;
  3. Verifier 阶段默认共享 Agent 环境(shared 模式),verifier_phase_baseline = agent_env_baseline;
  4. 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 两个特殊的放行例外

脚本中有两处刻意的例外,正是上一节两个回归断言的实现依据:

  1. 本地目标放行:fib daddr type local return / accept。Docker 将容器 resolv.conf 指向网络网关,再通过 DNAT 把 网关:53 转发到内嵌解析器,只有 fib daddr type local(在 DNAT 后重新评估)能识别这种"目标在重定向后变为本地"的流量,否则任何不含解析器地址的 allowlist 都会导致 DNS 断裂(bin/network-policy 与 test.sh 互为印证);
  2. 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 → Agent public)、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 的每一行代码上。

登录后查看全文
harbor