Network Safety
The CLI's remote fetches are conservative: fetching remote contract content is off unless you opt in, and the HTTP client the main fetch surfaces share (fluid_build.util.safe_http) checks the address at the connection layer, so DNS rebinding and IPv4-mapped IPv6 tricks cannot sneak past it.
This page describes the user-visible behaviour: which flags opt in, which environment variables allow hosts, where the defaults landed, and which older behaviours changed.
Defaults that changed in v0.8.3
| Surface | Old default | New default | Override |
|---|---|---|---|
fluid forge --seed-from <url> | (did not exist) | Local only; remote http(s) references are rejected | (since 0.31.0, forge-cli #881) Removed; use fluid odps import <path> -o contract.fluid.yaml with --allow-remote, then fluid forge --refine. --seed-allow-remote |
fluid odps import <url> | Followed http(s) contractId references | Local only; remote references are rejected | --allow-remote |
BitolOdpsProvider().import_contract(...) (Python) | allow_remote=True | allow_remote=False | allow_remote=True (keyword) |
ContractResolver(...) (Python) | allow_remote=True | allow_remote=False | allow_remote=True (keyword) |
| Ollama endpoint | Configurable | Localhost only | None, by design. (since 0.29.0, forge-cli #850) Calls now go to OLLAMA_HOST whatever the host. (since 0.29.0, forge-cli #852) So do the probe, model discovery and the interactive setup; see Ollama and OLLAMA_HOST. |
| HTTP redirects on a safe-HTTP client | Followed | Not followed | follow_redirects=True (per client) |
The CLI flags --no-remote and --seed-no-remote remain as hidden aliases that do nothing, so older scripts keep working. (since 0.31.0, forge-cli #881) --seed-no-remote is removed with --seed-from.
What the safe-HTTP client enforces
The client applies these, in order:
- Scheme allowlist. Only
httpandhttps.file://,gopher://and the rest are refused. - Post-DNS private-address filter. Private (RFC 1918), loopback, link-local (
169.254.0.0/16), multicast, reserved and unspecified addresses, plus carrier-grade NAT, 6to4, NAT64, ORCHIDv2, IPv6 segment routing and the RFC test ranges. IPv4-mapped IPv6 addresses are unwrapped before the check, which closes a bypass that Python before 3.12 had. - Reject mixed DNS answers. If a hostname resolves to any non-public address, the fetch is refused, so a public A record cannot hide a private AAAA record.
- Connection-layer DNS pin. The validated IP is the one the connection uses (through httpx's
sni_hostnameextension), so a second lookup cannot send the request to a private address. The hostname is kept for TLS and theHostheader. - No redirects by default.
follow_redirects=False; a client has to opt in. - Size cap.
fetch_bytesreads the body as a stream and stops at 10 MiB.
These surfaces use that client: the ODPS contract resolver, the Kafka Connect and schema-registry clients, the Airbyte runner, the DataHub, OpenMetadata and Data Mesh Manager registrars, the OpenLineage emitter, the federation fetcher, the schema manager's remote fetch, the forge web tools, and an authentication provider's API check. Other outbound calls do not: LLM provider requests go to the provider's endpoint, fluid apply --ensure-opentofu downloads OpenTofu, and the Command Center client and the webhook alerter apply their own host check, described next.
(since 0.31.0, forge-cli #913) A schema registry the contract names is one of these hosts. A Confluent registry's host goes through FLUID_ACQUISITION_DEPLOYMENT_HOST_ALLOWLIST (link-local never, a public host only when listed), and a credential sent to it needs NAME@host in FLUID_ACQUISITION_SECRET_REF_ALLOWLIST: SCHEMA_REGISTRY_API_SECRET@<host> for a produced subject. The plan-time read judges the address each request is pinned to. See Schema registry.
Allowlists for outbound integrations
A few integrations need to call hosts that the private-address filter would refuse, such as an internal webhook receiver or a self-hosted registry. Use the matching allowlist variable:
| Variable | Surface |
|---|---|
FLUID_WEBHOOK_HOST_ALLOWLIST | The build webhook alerter |
FLUID_FEDERATION_HOST_ALLOWLIST | The federation digest fetcher |
FLUID_COMMAND_CENTER_HOST_ALLOWLIST | The Command Center client: detection, the observability reporter and fluid apply run reports. Loopback hosts are always allowed |
FLUID_OPENLINEAGE_ALLOW_PRIVATE | The OpenLineage emitter. It allows private addresses by default because lineage receivers are usually internal; false restores the public-only check. Link-local and metadata addresses stay blocked either way |
The DataHub, OpenMetadata and Data Mesh Manager registrars that fluid publish uses call the guarded client with private addresses allowed, so they do not consult FLUID_WEBHOOK_HOST_ALLOWLIST or any other allowlist above.
The webhook, federation and Command Center variables take comma-separated host suffixes, matched exactly or as a dotted suffix: vpn.internal permits app.vpn.internal but not vpn.internal-evil.example.com. A host on the list skips the address check.
Metadata addresses refused even when listed
(since 0.27.0, forge-cli #823) Three checks allow an internal endpoint but never instance metadata: the guard on an acquisition orchestrator's deployment.server_url (kafka_connect, debezium and airbyte), the OpenLineage emitter and the managed Flink host check. They used to refuse only link-local and unspecified addresses, so a cloud's metadata address in ULA or CGNAT space passed like any private host, even with no allowlist entry. They now refuse these, even when the host is listed:
| Address | What it is |
|---|---|
fd00:ec2::254 | AWS instance metadata over IPv6 |
fd00:ec2::23 | The EKS Pod Identity agent, over IPv6 |
fd20:ce::254 | GCP instance metadata over IPv6 |
fd00:c1::a9fe:a9fe | Oracle Cloud instance metadata over IPv6 |
100.100.100.200 | Alibaba Cloud instance metadata, inside the CGNAT range |
An IPv4-mapped address (::ffff:...) or a NAT64 address (64:ff9b::/96) that carries a link-local or one of these metadata addresses is refused too. The surrounding ranges stay allowed: a Tailscale tailnet (CGNAT, 100.100.100.100 included) and an IPv6 cluster on ULA addresses need no change.
(since 0.28.0, forge-cli #828) A fourth check, the catalogAuth host check of the Kafka Connect and embedded Debezium Iceberg sink, refuses the same addresses, even when the host is listed. See Operator allowlists.
Cloud metadata and the credential resolver
FLUID_ALLOW_METADATA_SERVICE=1 lets the metadata-source credential resolver fall back to cloud workload identity. It is off by default, and it is not an SSRF switch: it does not relax the checks above.
As of 0.18.1, nothing in the CLI reads FLUID_SAFE_MODE or acts on the global --safe-mode flag to refuse network calls.
Ollama and OLLAMA_HOST
(since 0.29.0, forge-cli #850) Forge's Ollama calls go to --llm-endpoint or FLUID_LLM_ENDPOINT, else to OLLAMA_HOST whatever its host, else to http://localhost:11434; see The Ollama endpoint. A project's .env cannot set OLLAMA_HOST (Project dotenv trust).
(since 0.29.0, forge-cli #852) No Ollama read is held to localhost any more. The probe that finds a running Ollama, model discovery and the interactive Ollama setup follow OLLAMA_HOST too, and fluid ai test --endpoint takes an Ollama address on any host, over http or https; it still refuses a user:password@ in the URL. Through 0.28.0 those three looked only at localhost and ignored a non-local OLLAMA_HOST with a warning, and fluid ai test refused an Ollama endpoint that was not http on localhost. One address for every Ollama read also covers a user:password@ in forge's own Ollama address.
Through 0.28.0 the calls went to a litellm://ollama/<model> label unless an endpoint was stated, so no OLLAMA_HOST, local or remote, reached a daemon.
Contract SQL and $ref
Two 0.18.0 changes close network and file reads that a contract could previously trigger:
- SQL in a contract runs in a DuckDB sandbox: it cannot read
http(s)://,gs://or Azure URLs, and reaches only declareds3://locations. See DuckDB sandbox. - A
$refmay only name a file inside the contract's directory tree. URL refs,file://refs and absolute paths are refused. See Composing a contract with$ref.
How a denied fetch surfaces
A refusal by the safe-HTTP client is an UnsafeURLError, a ValueError subclass. Its message says why, and each address refusal also logs a ssrf_guard_blocked warning with the host and address:
refusing non-http(s) scheme: 'file'refusing fetch from non-public address <address> (hostname '<host>'): the DNS answer is private, loopback, link-local or reserved, including the mixed-answer case.cannot resolve hostname '<host>'response from '<url>' exceeds <n> bytes: the body cap.
A redirect is not an error: the client returns the 3xx response and does not follow it. The webhook alerter raises WebhookSsrfError and the federation fetcher raises FederationSsrfError for the same address refusals, and each message names its allowlist variable.
Import contracts
pyproject.toml declares import-linter contracts that keep this layer reusable: the observability package must not import the build runners, and fluid_build._net, which holds the shared address check, must not import other fluid_build packages. They are checked in development with lint-imports, not at run time.
pip install import-linter
lint-imports
See also
- Environment variables: the variables above in one place
fluid forge: where--seed-allow-remoteappliesfluid odps import: where--allow-remoteapplies- Catalog overview: the publish-side registrars