Allow configurable IP allowlist for _is_safe_url() to support private network access

[fpertl]

Problem

The _is_safe_url() function in docling_core/utils/file.py (introduced in PR #591) blocks all private, loopback, and link-local IP addresses as SSRF protection. While this is a sensible default for public-facing deployments, it breaks legitimate use cases where documents are fetched from internal/private network hosts, including:

• Local development and testing (http://localhost, http://127.0.0.1)
• Corporate intranet document servers (http://192.168.x.x, http://10.x.x.x)
• Container-to-container communication in Docker/Kubernetes
• On-premise document repositories

There is currently no way to opt out of or customize this behavior.

Potential Solution

Add an allowed_private_ips setting to CoreSettings in docling_core/utils/settings.py that accepts a list of IP addresses and/or CIDR ranges. These would bypass the SSRF check in _is_safe_url(), while keeping the default behavior secure (empty list = full SSRF protection).

Configuration via environment variable:

DOCLINGCORE_ALLOWED_PRIVATE_IPS='["192.168.1.0/24", "10.0.0.5", "127.0.0.1"]'

Implementation outline:

• Add allowed_private_ips: list[str] = [] to CoreSettings
• In _is_safe_url(), check the resolved IP against the allowlist before applying the default block — if the IP falls within any allowed network/address, return True
• Support both individual IPs and CIDR notation via ipaddress.ip_network(..., strict=False)

This follows the existing CoreSettings / pydantic-settings pattern already used for allow_image_file_uri and max_image_decoded_size.

Defaults

The default remains secure — an empty allowlist means the current SSRF protection is unchanged. Users must explicitly opt in to allowing private IPs.

[dolfim-ibm]

@fpertl thanks for the proposal. I confirm that we would support such a PR.

[JViktoRArtola]

Is there a planned release window for this? I’d be happy to help test or contribute if that would be useful.