Skip to content

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 ​

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()

Before sending, in this order, it checks:

  1. The destination is on the exact allowed_origins list (HTTP_DESTINATION_DENIED if not).
  2. The body is within its size limit.
  3. The URL, headers and body don't contain any of the forbidden_markers, exact byte strings your trusted tool service provides.
  4. 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:

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)
  • Across hosts, HTTPS is required. Plain HTTP is allowed only to a loopback IP address.
  • Redirects are not followed. A GET or HEAD without a body can opt in (follow_redirects=True, at most 5 hops). Each hop is checked again and Authorization and Cookie are 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:

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}

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.

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

A configuration maps model API paths to routes and names each route's upstream:

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"]
    }
  }
}
  • Model routes: /v1/chat/completions, /v1/responses and /v1/embeddings, with streaming (SSE) when allow_stream is set. Only function tools that your application runs are supported, not provider-hosted tools or background responses.
  • Per-user credentials: user_authorization_files maps 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.