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()发送之前,依次检查:
- 目标地址在精确的
allowed_origins列表里(不在则HTTP_DESTINATION_DENIED)。 - 请求正文没有超过大小上限。
- URL、请求头和正文里不含
forbidden_markers,即受信任的工具服务提供的精确字节串。 - 策略放行这个动作。
然后解析主机名,检查解析出的每一个地址,只连接检查过的地址,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 原样转发流,不检查流的内容。