HTTP egress
Two ways to put Guard in front of outbound HTTP:
GuardedHTTPClient, a Python client you use inside a trusted tool service. Every request is checked before it is sent.- The HTTP broker (
python -m preworld_guard.gateway), a separate service with fixed routes, for model APIs and business APIs. The agent calls the broker. The broker holds the upstream credentials.
Both raise the network.http action type. Both protect only the requests that go through them.
GuardedHTTPClient
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()Before sending, in this order, it checks:
- The destination is on the exact
allowed_originslist (HTTP_DESTINATION_DENIEDif not). - The body is within its size limit.
- The URL, headers and body don't contain any of the
forbidden_markers, exact byte strings your trusted tool service provides. - The policy allows the action.
Then it resolves the host name, checks every address it resolves to, and connects only to a checked address, keeping the original name for TLS. Private, loopback, link-local and similar addresses are refused unless you list a range for that origin:
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)- Across hosts, HTTPS is required. Plain HTTP is allowed only to a loopback IP address.
- Redirects are not followed. A
GETorHEADwithout a body can opt in (follow_redirects=True, at most 5 hops). Each hop is checked again andAuthorizationandCookieare dropped. - Environment proxy settings are ignored, so the address checks can't be bypassed.
Writing the policy
Match action_type: network.http, the logical resource (finance:submit above), the destination with its port, and the method, which the client passes as the argument method:
- 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}What is recorded
The event holds the logical resource, the destination, data labels and the decision. The method, the body size, hashes of the URL, body and headers, and the response status code are passed as the action's arguments and result, so the event carries them only as argument names and inside SHA-256 digests. The URL, the body, the headers and the response stay in your process.
The HTTP broker
The broker (gateway extra) serves fixed routes. The agent calls the broker with its own bearer token. The broker checks the policy and calls the upstream with the credential from a file only the broker can read. The caller's token is never forwarded.
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.jsonA configuration maps model API paths to routes and names each route's upstream:
{
"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"]
}
}
}- Model routes:
/v1/chat/completions,/v1/responsesand/v1/embeddings, with streaming (SSE) whenallow_streamis set. Only function tools that your application runs are supported, not provider-hosted tools or background responses. - Per-user credentials:
user_authorization_filesmaps a trusted subject to its own credential file. A user without one is refused. There is no shared fallback. - Limits by default: 16 concurrent requests, 120 seconds per request, 30 seconds idle upstream, 1 MB request and 3 MB response. Over capacity returns 429.
- Not supported: file uploads, realtime APIs.
Limits
- These checks cover only requests made through the client or the broker. An agent that can open its own sockets or run commands can go around them. Pair them with network rules (the agent reaches only the broker) or a sandbox, and test with a request that should fail.
- Marker matching is an exact byte match. It is not data loss prevention and doesn't track where data came from.
- The broker forwards streams as they are. It doesn't inspect their content.