Restricting URLs¶
MapLibre Native fetches every URL a style refers to: remote URLs, local files (file://,
mbtiles://, pmtiles://file://), and the URLs of custom schemes. A
style therefore has the same reach as the process that renders it. If your application renders
styles it does not fully control, e.g. styles fetched from a configurable URL, a malicious or
compromised style could:
- draw files from the server into the map image;
- make the server fetch internal URLs;
- read data that a scheme handler serves for other styles.
mapli.restrict_resource_urls() can be used to limit MapLibre Native to the URLs that start with one of a
list of prefixes:
import mapli
mapli.restrict_resource_urls(
allowed_url_prefixes=[
"store://",
"https://fonts.example.org/",
"file:///srv/tiles/",
],
)
pool = mapli.RenderPool()
Requests for any other URL fail with the message "<url>: access denied by URL rules". Rendering
then raises RenderError, or StyleLoadError if the denied URL is the style itself. The denied
URLs are never fetched.
Without a call to restrict_resource_urls(), every URL is allowed.
The untrusted styles example renders styles submitted by users this way.
The list of URL prefixes is process-wide, and can only be set once, before the first RenderPool is created.
After that, restrict_resource_urls() raises UrlRulesClosedError, so that the rules cannot be
loosened while styles are being rendered.
Prefixes¶
A prefix is either:
- a URL, e.g.
https://fonts.example.org/, which allows the URLs that start with it; - a scheme followed by
://, e.g.store://, which allows every URL of that scheme.
URLs and prefixes are compared so that a URL which starts with an allowed prefix cannot reach outside of it:
- Schemes are compared case-insensitively, and remote URLs are normalized first, e.g. host names are lowercased.
- A prefix only matches up to a path boundary:
https://example.org/fontsallowshttps://example.org/fonts/a.pbf, but nothttps://example.org/fontsevilorhttps://example.org.evil.com/. Ending prefixes with/makes this explicit. .and..path segments are resolved before comparing remote URLs, sohttps://example.org/fonts/../privateis denied byhttps://example.org/fonts/.- Some URLs are always denied, as different URL parsers would read them differently: URLs with
credentials (
https://user@host/), whitespace, control characters or backslashes.
Custom schemes are not exempt: their URLs must be allowed like any other, even if the scheme has a handler. Handlers receive the URL as the style wrote it, not its normalized form.
Local files¶
Local files are denied unless a file:// prefix allows them, e.g. file:///srv/tiles/. MapLibre
Native percent-decodes local file URLs before opening the file, so mapli compares the decoded
path. Local file URLs with . or .. path segments, or with a malformed % sequence, are
always denied.
Styles registered with path= are loaded from a file:// URL as well, so they are denied unless
a file:// prefix allows them. To render a style file without allowing its directory, read it
yourself and register it with json=.
MBTiles and PMTiles archives¶
Archive URLs are checked by what they read:
mbtiles:///srv/tiles/a.mbtilesis checked asfile:///srv/tiles/a.mbtiles;pmtiles://https://tiles.example.org/a.pmtilesis checked ashttps://tiles.example.org/a.pmtiles.
So file:///srv/tiles/ allows MBTiles and PMTiles archives in /srv/tiles as well as plain
files there, and https://tiles.example.org/ allows PMTiles archives on that host.
Limitations¶
- HTTP redirects are followed by MapLibre Native's HTTP client, so their targets are not checked. Only allow servers you trust not to redirect elsewhere.
- For remote URLs, a prefix with a path, e.g.
https://example.org/fonts/, is only as strong as the server's own handling of paths: a server that decodes%2Fin paths may serve something outside of/fonts/for a URL inside it. Prefer allowing whole hosts. - The rules apply to every style in the process, since MapLibre Native's requests do not say which style they come from.
- Data written into the style itself, e.g. inline GeoJSON, is not fetched, so the rules do not apply to it.