Service Egress Policy¶
Every outbound connection that the OpenMed service opens goes through one fail-closed policy in openmed.service.egress. The policy authorizes the operation before the adapter serializes a request body or opens a transport. An operation with no decision does not run.
The policy covers webhook callbacks, KServe remote inference, SMART backend services and FHIR Bulk Data, the OpenHIM mediator, the privacy gateway, the OTLP trace exporter, and MCP OAuth metadata discovery. It runs inside the process. It does not replace an OS-level or network-level egress control.
Modes¶
| Mode | Default for | Behaviour |
|---|---|---|
deny | none (opt-in) | Refuses every outbound operation. |
enforce | OPENMED_PROFILE=prod, unset, or any other profile | Allows only operations that match a rule. |
permissive | OPENMED_PROFILE=dev and test | Also allows HTTPS or gRPCS to public addresses without a rule. |
Set the mode explicitly with OPENMED_EGRESS_MODE=deny|enforce|permissive. OPENMED_OFFLINE (or a policy built with local_only=True) overrides every mode and rule. Offline mode is checked again on every attempt, redirect, and resolution, so switching it on also stops retries that are already running.
Rules¶
Rules come from OPENMED_EGRESS_RULES (a JSON array) and from the JSON file named by OPENMED_EGRESS_RULES_FILE (an array or {"rules": [...]}). When both are set, the rules from both are combined. An invalid rule stops service startup with a reason code. The error never repeats the rule's values.
[
{"purposes": ["webhook"], "destination": "https://hooks.example.org"},
{
"purposes": ["smart_token", "fhir_bulk"],
"destination": "https://fhir.example.org",
"allow_credentials": true
},
{
"purposes": ["openhim"],
"destination": "http://openhim-core:8080",
"cidrs": ["10.20.0.0/16"],
"allow_credentials": true
}
]
| Field | Meaning |
|---|---|
purposes | Required. One or more of webhook, remote_inference, smart_token, fhir_bulk, openhim, privacy_gateway, trace_export, connector_metadata. |
destination | Required. One exact origin: scheme, host, and optional port. Paths, queries, wildcards, and user info are rejected. Schemes are http and https, plus grpc and grpcs for remote inference. |
cidrs | Networks the resolved addresses must fall within. These networks may be private or loopback. Without cidrs, a hostname must resolve to public addresses only, and an IP-literal destination allows exactly that address. |
allow_credentials | Allows bearer tokens, basic auth, client assertions, and credential headers to reach this destination. Webhook HMAC signatures are not counted as credentials. |
allow_redirects | Allows a redirect back to this origin. Each hop is authorized again. |
max_request_bytes | Request-body budget for this rule. The default is 16 MiB. |
max_timeout_seconds | Highest per-request deadline allowed for this rule. The default is 300 seconds. |
A rule covers only the purposes it lists. A webhook rule does not authorize privacy-gateway traffic to the same host. Plain http and grpc need a rule that names that scheme.
Destination checks¶
The policy resolves the host right before the connection opens. It rejects loopback, private, link-local, multicast, reserved, unspecified, and cloud metadata addresses unless a rule's cidrs include them. A cloud metadata address must be listed as a single-address network, for example 169.254.169.254/32. If any resolved address is refused, the whole connection is refused.
The HTTP clients built by the policy connect only to the addresses that passed the check, while TLS still verifies the configured host name. A DNS answer that changes between the check and the connection cannot move the socket. These clients never follow redirects. They also ignore proxy and .netrc environment settings. gRPC channels for remote inference dial the checked addresses and keep the original name for TLS and :authority.
Each logical operation is bound to its destinations and to the first credential class it used. A retry, redirect, or later attempt cannot reach a new destination or switch to a different credential class.
Adapter coverage¶
| Adapter | Purposes | Decision point | Socket pinning |
|---|---|---|---|
webhooks | webhook | Job submission, then every delivery attempt before the payload is serialized | Pinned client |
remote_inference | remote_inference | Transport creation and every inference call; tensor bytes are checked against the budget | Pinned client; gRPC dials checked addresses |
smart_backend (incl. FHIR Bulk) | smart_token, fhir_bulk | Job submission, then the token, kickoff, status, and file requests | Pinned client |
openhim | openhim | Every authentication, registration, and heartbeat request | Pinned client |
privacy_gateway | privacy_gateway | Every forwarded prompt, before serialization, with a byte budget | Pinned client |
tracing | trace_export | Exporter creation and every export batch | Resolution checked before each batch; the OTLP exporter owns the socket |
mcp_metadata | connector_metadata | Every metadata fetch and every redirect hop | Pinned connection |
tests/unit/service/test_egress_adapter_coverage.py scans the service source for outbound call sites. It fails when a new site does not use the egress guard and is not listed as reviewed. Caller-side SDKs (openmed.service.client, openmed.service.workflow_client) and the inbound gRPC server are reviewed exemptions.
Denials and receipts¶
A refusal raises EgressDenied, which is a PermissionError with a stable reason_code. REST routes that receive a refused destination, such as a job webhook URL or SMART endpoints, return HTTP 403:
When a webhook delivery is refused, it stops with webhook_delivery.error set to egress_denied and is not retried. When privacy-gateway forwarding is refused, the request fails with privacy_gateway_transport_error and reason egress_denied.
Every decision produces a value-free receipt. It holds the policy version and digest, mode, stage, decision, reason code, adapter, purpose, data and credential classes, an opaque destination digest, the destination class, the rule identifier, the operation identifier, the attempt number, the request bytes, and the timing. Receipts are logged on the openmed.service.egress logger: denials at WARNING and allowed decisions at DEBUG. URLs, hosts, queries, headers, credentials, and payloads are never recorded. EgressPolicy.to_safe_dict() returns a posture summary for deployment checks. The summary holds the mode, digest, and rule counts per purpose.
OS-enforced no-egress gate¶
The policy runs inside the process, so it cannot stop a native library, a child process, or a raw resolver call. scripts/security/no_egress_gate.py checks the boundary outside the process. It runs a synthetic service workflow inside a Linux network namespace (unshare --user --map-root-user --net) or a container started with --network none. Only loopback exists inside either one.
python scripts/security/no_egress_gate.py --output no-egress-attestation.json
python scripts/security/no_egress_gate.py --boundary container \
--container-image openmed-service:local --output no-egress-attestation.json
python scripts/security/no_egress_gate.py --verify no-egress-attestation.json
Inside the boundary the gate starts the REST app, with GraphQL mounted, and the gRPC server on loopback. A deterministic fixture loader built from tests/fixtures/security/no_egress_service_workflow.json stands in for a cached checkpoint, so the gate downloads no model. The gate then runs these steps:
- analyze, extract, and de-identify over REST, GraphQL, and gRPC;
- an async job, and a webhook that this policy must refuse with
egress_denied; - client cancellation of a REST stream and a gRPC stream;
- a Journey store write, a graceful restart, a reopen check, and a shutdown.
Twelve negative controls try to leave the host. They cover IPv4 and IPv6 TCP and UDP, the system resolver, a raw DNS query, a child interpreter, and raw libc sockets through ctypes. They target documentation addresses (RFC 5737 and RFC 3849) and a .invalid name. A control counts as blocked only when the kernel reports that no route or address exists. A timeout counts as inconclusive. Loopback positive controls show that each probe works when a route exists. The gate also counts the interfaces and routes inside the boundary.
Container mode needs a local image with Python 3.11 or later and the service extra. The gate bind-mounts the checkout read-only and never pulls an image. You can also set the image with OPENMED_NO_EGRESS_IMAGE.
The attestation validates against openmed/core/schemas/json/no_egress_attestation.schema.json. It contains only case identifiers, statuses, reason codes, counts, digests, the commit, and the declared generated_at timestamp. Its repro_hash excludes the fields listed in volatile_fields. The exit codes are:
| Exit | Status | Meaning |
|---|---|---|
0 | passed | Every negative control was blocked and every workflow case passed. |
1 | failed | A control was not blocked, the boundary was not isolated, or the workflow or runner failed. |
2 | — | Invalid arguments or an unreadable fixture. |
3 | skipped | The host has no supported mechanism, for example macOS without container mode. This is never a pass. |
The service-no-egress job in .github/workflows/release-gates.yml runs the gate in network-namespace mode before the release gates. It uploads the attestation.
Migrating¶
The policy is deny-by-default for the production profile. To keep a webhook, remote-inference endpoint, SMART server, OpenHIM core, privacy-gateway endpoint, OTLP collector, or MCP authorization server working, add a rule for its origin and purpose. Add allow_credentials where the adapter sends credentials. Add cidrs where the destination resolves to private addresses. Webhook URLs and SMART endpoints that no rule allows are rejected when the job is submitted.