Skip to content

HTTP 出站 ​

有两种方式把 Guard 放在出站 HTTP 前面:

  • GuardedHTTPClient:在受信任的工具服务里使用的 Python 客户端。每个请求发出前都先检查。
  • HTTP broker(python -m preworld_guard.gateway):一个独立的服务,路由固定,用于模型 API 和业务 API。Agent 调 broker,上游凭据只在 broker 手里。

两者产生的动作类型都是 network.http,也都只保护经过它们的请求。

GuardedHTTPClient ​

python
from preworld_guard import GuardClient
from preworld_guard.egress import GuardedHTTPClient

guard = GuardClient(endpoint, executor_token, project_id, agent_id="expense-tool-broker")
with GuardedHTTPClient(
    guard,
    allowed_origins=["https://finance.example.com"],
    forbidden_markers=[protected_marker],
) as outbound:
    response = outbound.request(
        "finance:submit", "POST", "https://finance.example.com/v1/expenses",
        json_body={"amount": "20.00"},
        data_labels=("finance",),
    )
guard.close()

发送之前,依次检查:

  1. 目标地址在精确的 allowed_origins 列表里(不在则 HTTP_DESTINATION_DENIED)。
  2. 请求正文没有超过大小上限。
  3. URL、请求头和正文里不含 forbidden_markers,即受信任的工具服务提供的精确字节串。
  4. 策略放行这个动作。

然后解析主机名,检查解析出的每一个地址,只连接检查过的地址,TLS 仍按原主机名校验。内网、回环、链路本地等地址默认拒绝,除非为这个来源写明允许的地址段:

python
with GuardedHTTPClient(
    guard,
    allowed_origins=["https://finance.internal:443"],
    allowed_networks={"https://finance.internal:443": ["10.20.0.8/32"]},
) as outbound:
    response = outbound.request("finance.submit", "POST", "https://finance.internal/api/expenses", json_body=payload)
  • 跨主机必须用 HTTPS。明文 HTTP 只允许连本机回环 IP。
  • 不跟随重定向。不带正文的 GET 或 HEAD 可以显式开启(follow_redirects=True,最多 5 跳)。每一跳重新检查,并去掉 Authorization 和 Cookie。
  • 忽略环境变量里的代理设置,地址检查不会被绕过。

怎么写策略 ​

匹配 action_type: network.http、逻辑 resource(上例的 finance:submit)、带端口的 destination,以及方法。客户端把方法作为参数 method 传入:

yaml
  - rule_id: allow-expense-submit
    effect: allow
    risk: normal
    match:
      action_type: network.http
      resource: "finance:submit"
      destination: "https://finance.example.com:443"
      argument_equals: {method: POST}

记录什么 ​

事件里有逻辑资源、目标地址、数据标签和判定。方法、正文大小、URL / 正文 / 请求头的哈希和响应状态码,是作为动作的参数和结果传入的,所以事件里只有它们的参数名,以及包含它们的 SHA-256 摘要。URL、正文、请求头和响应内容都留在你们的进程里。

HTTP broker ​

broker(gateway extra)提供固定的路由。Agent 用自己的 bearer 令牌调 broker。broker 判定策略后,用只有它能读的凭据文件去调上游。调用者的令牌从不转发。

sh
PREWORLD_GUARD_ENDPOINT=https://guard.example.com \
PREWORLD_GUARD_PROJECT_ID=<project-id> \
PREWORLD_GUARD_TOKEN_FILE=/run/secrets/executor-token \
PREWORLD_GUARD_CACHE=/state/policy.json \
python -m preworld_guard.gateway --config /config/enterprise-broker.json

配置把模型 API 的路径映射到路由,并为每个路由指定上游:

json
{
  "jwt": {
    "issuer": "https://id.example.com/realms/company",
    "audience": "https://guard.example.com/tools",
    "jwks_url": "https://id.example.com/realms/company/protocol/openid-connect/certs",
    "required_scope": "guard:tools",
    "subjects": {"IDP_USER_SUBJECT": "employee-001"}
  },
  "model_routes": {
    "/v1/chat/completions": "model-chat",
    "/v1/responses": "model-responses"
  },
  "routes": {
    "model-chat": {
      "resource": "model.chat", "url": "https://api.example.com/v1/chat/completions",
      "authorization_file": "/run/secrets/model-authorization", "allow_stream": true
    },
    "model-responses": {
      "resource": "model.responses", "url": "https://api.example.com/v1/responses",
      "authorization_file": "/run/secrets/model-authorization", "allow_stream": true
    },
    "expense-submit": {
      "resource": "finance.submit", "url": "https://finance.example.com/api/expenses",
      "user_authorization_files": {"employee-001": "/run/secrets/employee-001-authorization"},
      "allowed_subjects": ["employee-001"]
    }
  }
}
  • 模型路由:/v1/chat/completions、/v1/responses 和 /v1/embeddings。设了 allow_stream 时支持流式(SSE)。只支持由你们的应用自己执行的 function tools,不支持模型厂商托管的工具和后台任务。
  • 逐用户凭据:user_authorization_files 把可信主体映射到各自的凭据文件。没有配置的用户直接拒绝,不会退回到共享凭据。
  • 默认上限:并发 16,单个请求 120 秒,上游空闲 30 秒,请求 1 MB,响应 3 MB。容量用完返回 429。
  • 不支持:文件上传、实时(Realtime)接口。

限制 ​

  • 这些检查只覆盖经过客户端或 broker 的请求。Agent 如果能自己开 socket 或执行命令,就能绕过去。要配合网络规则(Agent 只能访问 broker)或沙箱,并用一个本应失败的请求实测。
  • 标记匹配是精确的字节匹配,不是数据防泄漏,也不追踪数据来源。
  • broker 原样转发流,不检查流的内容。