Saltar a contenido

Tarea 6 min de lectura

Restrict access with an IP allowlist

An IP allowlist limits the networks that can use your organisation. When it is enabled, Ostorlab refuses every request that acts on your organisation from an IP address outside the list, whoever sends it: a signed-in user or an API key. Shared links are not restricted by the allowlist.

The IP allowlist is available on enterprise plans.

What the allowlist covers

The allowlist applies to every way into your organisation:

Entry point What is checked
Web application Every request a signed-in user makes on your organisation, including the copilot.
GraphQL API Requests signed in with a user token and requests made with an X-Api-Key header.
API keys Every key of your organisation, whatever its role, including keys used by the ostorlab command line, CI pipelines and on-prem scanners.
MCP server Requests to https://api.ostorlab.co/apis/mcp/<key>/ are refused before any tool runs.
Other organisations Operations a user runs on your organisation from another one: managing its members, archiving it, adding a child organisation under it, transferring a plan, and reading its plans and token wallet.

Not covered: shared links. A link you share stays reachable from any network, even with the allowlist enabled.

The check is on the organisation a request acts on. A user who belongs to several organisations can still use the others from anywhere; only your organisation is restricted.

Before you start

  • An enterprise plan. Without it, enabling the allowlist is refused with "The IP allowlist is available on enterprise plans only." After a downgrade from an enterprise plan, you can still edit or disable an existing list.
  • The Admin role in the organisation. Only admins can read and change the allowlist.
  • A signed-in session. The allowlist cannot be read or changed with an API key, so a leaked key cannot loosen it.
  • The public IP addresses or ranges your teams and tools connect from: offices, VPN egress, CI runners, on-prem scanners and any server that calls the API.

Accepted entries

Rule Detail
Format A single IP address or a CIDR range, IPv4 or IPv6. For example 203.0.113.7, 203.0.113.0/24 or 2001:db8:1234::/48.
Single addresses Saved as a /32 (IPv4) or /128 (IPv6) range.
Host bits Cleared when the entry is saved: 203.0.113.7/24 is saved as 203.0.113.0/24.
Public ranges only Private, loopback, link-local and other non-public ranges, such as 10.0.0.0/8 or 192.168.1.0/24, are refused. List the public IP your network connects from.
No catch-all A /0 range, such as 0.0.0.0/0 or ::/0, is refused.
Duplicates A network listed twice is refused.
Description Optional, up to 255 characters. Use it to say what the range is, for example "Paris office".
Limit At most 100 entries per organisation.

Lockout protection

Ostorlab will not let you lock yourself out:

  • An enabled list must contain at least one entry.
  • An enabled list must contain the IP you are saving it from, or a range that includes it. Otherwise the change is refused with a message naming the IP Ostorlab saw, for example "Your current IP 203.0.113.7 is not in the list; add it, or a range containing it, first."
  • Disabling the allowlist is always possible.

The ipAllowlist query returns currentIp, the IP Ostorlab sees for your connection, and currentIpAllowed, whether the saved list accepts it. Check both before you enable the list.

If your network changes and every admin is locked out, contact Ostorlab support.

Turn on the allowlist

The allowlist is managed through the GraphQL API, from a signed-in admin session.

  1. Open the API sandbox. Sign in at report.ostorlab.co as an organisation admin, then open https://api.ostorlab.co/apis/graphql. See Sandbox.
  2. Check your current IP and plan. Run the ipAllowlist query below. isAvailable must be true to enable the list.
  3. Save the list and enable it. Run the updateIpAllowlist mutation with isEnabled: true and the complete list of entries, including the range you connect from.
  4. Check the result. The mutation returns the saved list. isEnabled is true and currentIpAllowed is true.

Read the current allowlist:

query {
  ipAllowlist {
    isEnabled
    isAvailable
    currentIp
    currentIpAllowed
    entries {
      network
      description
      createdTime
    }
  }
}

{
  "data": {
    "ipAllowlist": {
      "isEnabled": false,
      "isAvailable": true,
      "currentIp": "203.0.113.7",
      "currentIpAllowed": false,
      "entries": []
    }
  }
}

Save the list and enable it:

mutation {
  updateIpAllowlist(
    isEnabled: true
    entries: [
      { network: "203.0.113.0/24", description: "Paris office" }
      { network: "198.51.100.10", description: "CI runner" }
      { network: "2001:db8:1234::/48", description: "VPN egress" }
    ]
  ) {
    ipAllowlist {
      isEnabled
      currentIp
      currentIpAllowed
      entries {
        network
        description
      }
    }
  }
}

{
  "data": {
    "updateIpAllowlist": {
      "ipAllowlist": {
        "isEnabled": true,
        "currentIp": "203.0.113.7",
        "currentIpAllowed": true,
        "entries": [
          { "network": "203.0.113.0/24", "description": "Paris office" },
          { "network": "198.51.100.10/32", "description": "CI runner" },
          { "network": "2001:db8:1234::/48", "description": "VPN egress" }
        ]
      }
    }
  }
}

updateIpAllowlist replaces the whole list. An entry you leave out is removed, so always send every entry you want to keep. The change is saved all at once: if one entry is invalid, nothing is saved and the error says which entry and why.

To disable the allowlist, run the mutation with isEnabled: false. The entries you send are kept for later.

Every change is written to the organisation's audit log: one event per entry added, removed or re-described, and one when the allowlist is enabled or disabled.

What a blocked request looks like

A request from an IP outside the list gets an HTTP 403 response with the code ip_not_allowed and the IP Ostorlab saw:

{
  "detail": "Access from 198.51.100.23 is not allowed by your organisation's IP allowlist.",
  "code": "ip_not_allowed",
  "ip": "198.51.100.23"
}

Operations on your organisation run from another organisation are refused with a GraphQL error carrying the same code and IP:

{
  "errors": [
    {
      "message": "Access from 198.51.100.23 is not allowed by your organisation's IP allowlist.",
      "extensions": {
        "code": "ip_not_allowed",
        "ip": "198.51.100.23"
      }
    }
  ]
}

If a tool you expect to work is refused, add the ip from the response to the list, or the range it belongs to.

Next steps