DNS Rebinding Security Check Too Strict for Internal Homelab Networks

[robmcd527]

Webhook notifications to internal services are blocked with the error:
webhook URL resolves to private IP [INTERNAL_IP] - private networks are not allowed for security

This occurs even when:

• The webhook is intentionally configured for an internal service
• The user is aware of and accepts the security trade-off
• DNS resolution is working correctly (testing via WebUI succeeds)

Root Cause

The SSRF protection added in commit 6a48c75 ("Fix critical notification system bugs and security issues") blocks all webhook URLs that resolve to private IP
ranges (10/8, 172.16/12, 192.168/16, 127/8, 169.254/16), regardless of user intent.

While this is an excellent security hardening measure for multi-tenant or public deployments, it's overly restrictive for homelab/internal-only environments
where:

• All services are on a trusted private network
• Users intentionally route through internal IPs/hostnames
• DNS rebinding attacks are not a realistic threat

Use Case

A typical homelab setup with Traefik reverse proxy:
Local DNS: internal-service.local → [INTERNAL_IP]
↓
Traefik (reverse proxy on internal VM)
↓
Service (Docker container)

Pulse can't send webhooks to internal-service.local because it resolves to a private IP, even though:

• The domain name correctly routes through the reverse proxy
• WebUI testing works fine (browser makes the request directly)
• This is the standard routing pattern for self-hosted setups

Proposed Solutions

Option 1: Configuration Flag (Recommended)
Add an environment variable to explicitly allow private IP webhooks for homelab deployments:
PULSE_ALLOW_PRIVATE_WEBHOOKS=true

This keeps the default secure (blocks private IPs) while giving homelab users an explicit opt-in.

Option 2: Warning Instead of Error
Log a warning but allow the webhook to proceed:
Warning: Webhook URL resolves to private IP. This is allowed but may indicate a DNS rebinding vulnerability in public deployments.

Option 3: Allowlist Configuration
Let users explicitly allowlist trusted private IP ranges:
{
"webhookAllowedPrivateRanges": ["10.0.0.0/8", "172.16.0.0/12"]
}

Additional Context

• Error message indicates this is working as designed (good security practice for default)
• No documentation about this restriction in WEBHOOKS.md or CONFIGURATION.md
• Security audit was thorough (commit message shows comprehensive SSRF hardening)
• Would benefit from mention in docs for users hitting this issue

[rcourtman]

Commit 413ef73 from September 2025 added the private-address block to stop webhook configs from reaching back into the network after a past security review. That change worked but it ignores the fact that most Pulse installs run entirely inside trusted homelab environments.

Pulse will follow option three from your proposal. The next release will introduce a setting under System Settings (available in the UI, REST API, and persisted config) that lets admins enter trusted network ranges such as 192.168.1.0/24 or 10.0.0.0/8. The default remains the current behavior, so nothing changes unless someone explicitly adds entries.

Even when the allow list is in place, addresses for localhost 127.0.0.1, link-local 169.254.0.0/16, and cloud metadata services stay blocked permanently. Pulse will also check the target address both when saving the webhook configuration and again right before each delivery to ensure the webhook still points at an allowed system.

This work is scheduled for the upcoming release so homelab deployments can keep their current protections while still targeting internal services when needed.

[robmcd527]

Awesome, thanks for the quick response!

[robmcd527]

Interesting finding - I installed the new host agent on one of my VMs, and then I did get a Gotify notification for that VM being down some time later (I think that was a false alarm - investigating that separately). Digging into it I think there may be a bug where 'grouped' notifications are somehow bypassing the DNS rebinding check. Other alerts are still failing but those are getting through, and the only difference I can find is that Pulse grouped a batch of alerts into a single message.

[rcourtman]

Live notifications, grouped or not, always ran the DNS rebinding check, so the Gotify alert didn't come from that path.

The issue was only in the UI Test button, which sent requests without re-validating the URL. That endpoint now uses the same validation and the fix will be in the next release.

Thanks for flagging.

[robmcd527]

I think you're right - I looked at the code for a bit and can't figure out for the life of me how a notification got through. I only have the one example though so must be missing something on my end. Either way the new config you added works great! Notifications are all working again and my system is in good shape. Thanks again. Resolving this one.