Skip to content
DashboardWebsite

Network Access

Just want to do it in the dashboard? See the guide: Restrict access by IP address.

Network access rules decide which source addresses may reach the API, dashboard and docs. A typical setup keeps the whole instance on the office network and opens one path, a code host’s webhook, to that host’s published addresses only.

In the dashboard: Platform Admin → Security → Firewall. Only platform admins can access it.

These rules run inside the API. A request they refuse has already crossed the internet, reached the proxy and been parsed by the application. Every flaw in front of the filter — the proxy, TLS, the HTTP parser — stays exposed to the whole internet.

Filter at the network edge first: an AWS security group, an Azure network security group, a GCP firewall rule, or the firewall in front of your server. Open only the HTTPS port, and only to the sources that need it: your office or VPN, and your code host’s webhook ranges. If nobody outside your network needs the instance, keep it off the public internet.

Then use these rules as a second layer, for what an edge firewall cannot express: a rule per service and path, lists that refresh from a URL, report mode, and the refused requests on the Traffic tab.

Two filters run in order. A request must pass both.

  1. Network rules, before authentication. The rule for the request’s service whose path prefix is the longest match decides. If no rule matches, the request is allowed. A matching rule allows the addresses in its lists and CIDRs and refuses everything else with 403 Access denied from this network.
  2. The API key’s own IP allowlist, if the request carries a key that has one. An org admin sets it on Service accounts, and it can only narrow what the rules allow.

The caller’s address is resolved through network.trusted_proxies. Set it before you write a rule, or every caller has your proxy’s address.

Example rulesEffect
api / → office-vpnThe API answers the office only
api /integrations/github/webhook → github-hooks…except that path, which answers GitHub’s webhook senders only
dashboard / → office-vpnThe dashboard pages load from the office only

/health is never filtered, so load balancers and probes keep working.

An api rule names the path the API serves: /v1/admin, not /admin. Webhooks, callbacks, SCIM and OAuth stay at the root (see Versioning). Rules written before the /v1 prefix move under it once, at the first start of a version that has it. A rule whose path also covers a root route, such as /auth, stays and gets a copy under /v1.

A browser denied access to a dashboard or docs page gets a page, not a bare 403. The page says the network is not allowed and shows the address the rules saw, the page, and the time. A Copy details button copies them to the clipboard for an administrator. If the API cannot answer the check, the page says so and retries every 30 seconds.

A new rule starts in report mode: it counts the requests it would refuse and lets them through. Check the counts on the Rules tab, then switch the rule to enforce.

A list is a named set of entries of one type:

  • ip — IPs and CIDRs. Rules use these.
  • host — host names and *.suffix patterns. Egress policies use these (see below).

Its entries come from one source:

SourceEntriesRefreshed
statictyped in—
urlfetched over HTTPS from a public addresson creation, on Refresh now, then every refresh_hours (default 24)
fileread from a file under network.list_sources_dirsame as url

A source is plain text, one entry per line with # comments, or JSON. For JSON, selector names the keys whose strings are collected at any depth: https://api.github.com/meta with selector: ["hooks"] gives GitHub’s webhook ranges.

Presets. A product can offer ready-made lists for the services it integrates with. Pick one with Add list → From preset.

Default rules. A preset can be marked as a default. At first start, each default becomes its list and a rule on the preset’s path in report mode: it counts what it would refuse and blocks nothing. OpenTremor ships one, github-hooks on /integrations/github/webhook. Each default is created once per deployment: delete it, and it stays deleted. Switch it to enforce once its Traffic looks right.

File lists are off until the operator sets network.list_sources_dir (env NETWORK_LIST_SOURCES_DIR) and mounts the directory. A list names a path relative to it; a path that leaves it is refused. Use a file list for a source on your own network: url lists reach public addresses only.

Each egress policy (notifications.egress, and the ones a product adds) takes allowed_lists next to allowed_hosts. A host is allowed if it is in allowed_hosts or in a named host list. Naming a list turns the restriction on even while the list is empty: an empty list allows nothing.

A list that a rule or an egress policy names cannot be deleted. The error names what uses it.

The API decides for the dashboard and docs too. Their servers ask GET /network-access/verdict before serving a page:

  • the dashboard, through its request proxy, when NETWORK_ACCESS_VERDICT_URL is set on its container;
  • the docs, through nginx auth_request, when the same variable is set on the docs container.

The verdict endpoint answers only a peer listed in network.trusted_proxies and returns 404 to anyone else. Both servers fail closed: if the API is down, they answer 503. Leave the docs container without the variable if your docs must stay up during an API outage.

  • A change that would block your own address from the rules API or the firewall page is refused with 409. The message names the rule.
  • New rules start in report mode.
  • If you are locked out anyway, set NETWORK_FILTER_ENABLED=false on the API and restart. Every rule stops applying, and the firewall page says the operator turned the filter off. The switch is file/env only on purpose: turning the filter off needs access to the deployment.

Every refusal by a rule, in either mode, or by a key’s allowlist is recorded as an event: time, service, path, client address, hop chain, rule or key, request ID. One event per rule or key and address per minute, with a count. The Traffic tab lists them and the most-refused addresses.

Events hold client IP addresses. They are kept for retention.network_events_days (default 7, up to 90) and deleted with their organization. Change the window on Platform Admin → System → Data Lifecycle. Prometheus gets network_access_denied_total{layer,service,mode}.

All endpoints are platform-admin only, except the verdict.

EndpointPurpose
GET /v1/admin/network-accessOverview: your address and hop chain, rules, lists, key allowlists
POST /v1/admin/network-access/checkTrace a request: {service, ip, path, api_key_id?} → verdict per layer
GET/POST /v1/admin/network-access/listsList, create
GET /v1/admin/network-access/lists/presetsRegistered presets
GET/PATCH/DELETE /v1/admin/network-access/lists/{list_id}Read, change, delete (409 while used)
POST /v1/admin/network-access/lists/{list_id}/refreshFetch the source now
GET/POST /v1/admin/network-access/rulesList (evaluation order), create
PATCH/DELETE /v1/admin/network-access/rules/{rule_id}Change, delete (409 on lockout)
GET /v1/admin/network-access/eventsDenial events, newest first; filter by service, layer, ip, ref_id, since
GET /v1/admin/network-access/events/top-sourcesMost-refused addresses
GET /network-access/verdict204 or 403 for a dashboard or docs request; trusted proxies only

Service and path prefix of a rule, and name, type and source of a list, are fixed once created.