Skip to content

A continuation of HomeBox the inventory and organization system built for the Home User

chore: stronger notifier HTTP protections

Matthew Kilgore52eb6f3511bf
diff --git a/backend/app/api/main.go b/backend/app/api/main.go
index 202e2a8e..0576816b 100644
--- a/backend/app/api/main.go
+++ b/backend/app/api/main.go
@@ -19,6 +19,7 @@ import (
"github.com/sysadminsmedia/homebox/backend/internal/sys/analytics"
"github.com/sysadminsmedia/homebox/backend/internal/sys/config"
"github.com/sysadminsmedia/homebox/backend/internal/sys/otel"
+ "github.com/sysadminsmedia/homebox/backend/internal/sys/validate"
"github.com/sysadminsmedia/homebox/backend/internal/web/mid"
"github.com/sysadminsmedia/homebox/backend/pkgs/hasher"
@@ -122,6 +123,13 @@ func run(cfg *config.Config) error {
}
hasher.SetAPIKeyPepper([]byte(cfg.Auth.APIKeyPepper))
+ // Harden http.DefaultClient so notifier redirects are re-validated against the
+ // SSRF policy on every hop. shoutrrr's generic service delivers via
+ // http.DefaultClient with no CheckRedirect, so without this a notifier that
+ // passes the initial URL gate could be 30x-redirected to localhost / cloud
+ // metadata / other blocked destinations. Installed before any notifier can fire.
+ validate.InstallNotifierRedirectGuard(&cfg.Notifier)
+
// =========================================================================
// Initialize OpenTelemetry
otelProvider, err := otel.NewProvider(context.Background(), &cfg.Otel, version)
diff --git a/backend/internal/sys/validate/notifier_http.go b/backend/internal/sys/validate/notifier_http.go
new file mode 100644
index 00000000..7459095c
--- /dev/null
+++ b/backend/internal/sys/validate/notifier_http.go
@@ -0,0 +1,53 @@
+package validate
+
+import (
+ "fmt"
+ "net/http"
+
+ "github.com/sysadminsmedia/homebox/backend/internal/sys/config"
+)
+
+// maxNotifierRedirects caps redirect hops for outbound delivery, matching net/http's
+// default so behavior is unchanged for legitimate redirect chains.
+const maxNotifierRedirects = 10
+
+// InstallNotifierRedirectGuard hardens http.DefaultClient so redirects are
+// re-validated against the notifier SSRF policy on every hop.
+//
+// shoutrrr's generic service performs its HTTP request with http.DefaultClient and
+// no CheckRedirect hook, so a host that passes the initial ValidateNotifierURL gate
+// can respond with a 30x redirect to localhost / link-local / cloud-metadata / any
+// other blocked destination, and the follow-up hop is delivered without re-checking
+// the policy — bypassing the SSRF guards. Re-validating each hop closes that hole.
+//
+// This affects every http.DefaultClient consumer in the process, but in Homebox
+// that is only shoutrrr: all other outbound HTTP clients (labelmaker, analytics,
+// otel, product search, the GitHub release check) are constructed explicitly. The
+// guard only rejects redirects whose target is blocked by policy; ordinary
+// redirects to permitted hosts continue to be followed.
+func InstallNotifierRedirectGuard(cfg *config.NotifierConf) {
+ http.DefaultClient.CheckRedirect = NotifierRedirectGuard(cfg)
+}
+
+// NotifierRedirectGuard returns an http.Client CheckRedirect hook that refuses any
+// redirect whose target resolves to an address blocked by cfg, and caps the number
+// of hops. Returning a non-nil error aborts the request with that error rather than
+// following the redirect, so a blocked hop surfaces as a delivery failure.
+func NotifierRedirectGuard(cfg *config.NotifierConf) func(req *http.Request, via []*http.Request) error {
+ return func(req *http.Request, via []*http.Request) error {
+ if len(via) >= maxNotifierRedirects {
+ return fmt.Errorf("stopped after %d redirects", maxNotifierRedirects)
+ }
+
+ // Defensive: with no policy configured, preserve default behavior (only the
+ // hop cap above applies) rather than blocking every redirect.
+ if cfg == nil {
+ return nil
+ }
+
+ if err := validateHostAgainstPolicy(req.URL.Hostname(), cfg); err != nil {
+ return fmt.Errorf("redirect to %s blocked by notifier SSRF policy: %w", req.URL.Redacted(), err)
+ }
+ return nil
+ }
+}
diff --git a/backend/internal/sys/validate/notifier_http_test.go b/backend/internal/sys/validate/notifier_http_test.go
new file mode 100644
index 00000000..2fcd9e4f
--- /dev/null
+++ b/backend/internal/sys/validate/notifier_http_test.go
@@ -0,0 +1,65 @@
+package validate
+
+import (
+ "net/http"
+ "net/url"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+ "github.com/sysadminsmedia/homebox/backend/internal/sys/config"
+)
+
+// redirectTo builds an http.Request for a redirect target so the guard can be
+// exercised without a live server. IP-literal targets resolve via net.LookupIP
+// without touching DNS, keeping these cases deterministic.
+func redirectTo(rawURL string) *http.Request {
+ u, _ := url.Parse(rawURL)
+ return &http.Request{URL: u}
+}
+
+func TestNotifierRedirectGuard_BlocksByPolicy(t *testing.T) {
+ tests := []struct {
+ name string
+ cfg *config.NotifierConf
+ target string
+ blocked bool
+ }{
+ {"loopback blocked", &config.NotifierConf{BlockLocalhost: true}, "http://127.0.0.1/x", true},
+ {"loopback allowed when flag off", &config.NotifierConf{}, "http://127.0.0.1/x", false},
+ {"cloud metadata blocked", &config.NotifierConf{BlockCloudMetadata: true}, "http://169.254.169.254/latest/meta-data", true},
+ {"rfc1918 blocked", &config.NotifierConf{BlockLocalNets: true}, "http://10.1.2.3/x", true},
+ {"bogon link-local blocked", &config.NotifierConf{BlockBogonNets: true}, "http://169.254.1.1/x", true},
+ {"blocknet CIDR blocked", &config.NotifierConf{BlockNets: []string{"203.0.113.0/24"}}, "http://203.0.113.7/x", true},
+ {"public address allowed", &config.NotifierConf{BlockLocalhost: true, BlockLocalNets: true, BlockBogonNets: true, BlockCloudMetadata: true}, "http://8.8.8.8/x", false},
+ {"allowlist rejects outside", &config.NotifierConf{AllowNets: []string{"8.8.8.0/24"}}, "http://127.0.0.1/x", true},
+ {"allowlist permits inside", &config.NotifierConf{AllowNets: []string{"8.8.8.0/24"}}, "http://8.8.8.8/x", false},
+ }
+
+ for _, tc := range tests {
+ t.Run(tc.name, func(t *testing.T) {
+ guard := NotifierRedirectGuard(tc.cfg)
+ err := guard(redirectTo(tc.target), nil)
+ if tc.blocked {
+ require.Error(t, err, "target should be refused")
+ } else {
+ require.NoError(t, err, "target should be allowed")
+ }
+ })
+ }
+}
+
+func TestNotifierRedirectGuard_CapsHops(t *testing.T) {
+ guard := NotifierRedirectGuard(&config.NotifierConf{})
+ via := make([]*http.Request, maxNotifierRedirects)
+ err := guard(redirectTo("http://8.8.8.8/x"), via)
+ assert.Error(t, err, "should stop once the redirect cap is reached")
+}
+
+func TestNotifierRedirectGuard_NilConfigOnlyCaps(t *testing.T) {
+ guard := NotifierRedirectGuard(nil)
+ // With no policy, a normal hop is allowed...
+ require.NoError(t, guard(redirectTo("http://127.0.0.1/x"), nil))
+ // ...but the hop cap still applies.
+ assert.Error(t, guard(redirectTo("http://127.0.0.1/x"), make([]*http.Request, maxNotifierRedirects)))
+}
diff --git a/backend/internal/sys/validate/notifier_ssrf_redirect_test.go b/backend/internal/sys/validate/notifier_ssrf_redirect_test.go
new file mode 100644
index 00000000..b2b31c4f
--- /dev/null
+++ b/backend/internal/sys/validate/notifier_ssrf_redirect_test.go
@@ -0,0 +1,70 @@
+package validate_test
+
+import (
+ "net/http"
+ "net/http/httptest"
+ "sync/atomic"
+ "testing"
+
+ "github.com/nicholas-fedor/shoutrrr"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+ "github.com/sysadminsmedia/homebox/backend/internal/sys/config"
+ "github.com/sysadminsmedia/homebox/backend/internal/sys/validate"
+)
+
+// startVictimAndRedirector spins up two loopback servers: a "victim" that records
+// whether it was reached, and a "redirector" that 307-redirects any request to the
+// victim. It returns the generic+ notifier URL pointing at the redirector and a
+// function reporting how many times the victim was hit.
+func startVictimAndRedirector(t *testing.T) (notifierURL string, victimHits func() int32) {
+ t.Helper()
+
+ var hits int32
+ victim := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ atomic.AddInt32(&hits, 1)
+ w.WriteHeader(http.StatusOK)
+ }))
+ t.Cleanup(victim.Close)
+
+ redirector := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+ w.Header().Set("Location", victim.URL)
+ w.WriteHeader(http.StatusTemporaryRedirect)
+ }))
+ t.Cleanup(redirector.Close)
+
+ // shoutrrr's generic service wraps a plain http(s) URL as generic+http(s)://...
+ return "generic+" + redirector.URL, func() int32 { return atomic.LoadInt32(&hits) }
+}
+
+// TestNotifierRedirectSSRF_Unguarded documents the vulnerability: shoutrrr's generic
+// service delivers via http.DefaultClient, which follows redirects with no policy
+// re-check. A host that passes the initial SSRF gate can 307-redirect to a blocked
+// destination (here loopback) and the follow-up hop is delivered.
+func TestNotifierRedirectSSRF_Unguarded(t *testing.T) {
+ // Ensure default redirect-following behavior for this case.
+ saved := http.DefaultClient.CheckRedirect
+ http.DefaultClient.CheckRedirect = nil
+ t.Cleanup(func() { http.DefaultClient.CheckRedirect = saved })
+
+ notifierURL, victimHits := startVictimAndRedirector(t)
+
+ err := shoutrrr.Send(notifierURL, "Test message from Homebox")
+ require.NoError(t, err)
+ assert.Equal(t, int32(1), victimHits(), "unguarded: redirect to loopback victim IS followed (SSRF)")
+}
+
+// TestNotifierRedirectSSRF_Guarded verifies the fix: with the redirect guard
+// installed on http.DefaultClient, a 307 to a blocked (loopback) destination is
+// refused, the send fails, and the victim is never reached.
+func TestNotifierRedirectSSRF_Guarded(t *testing.T) {
+ saved := http.DefaultClient.CheckRedirect
+ http.DefaultClient.CheckRedirect = validate.NotifierRedirectGuard(&config.NotifierConf{BlockLocalhost: true})
+ t.Cleanup(func() { http.DefaultClient.CheckRedirect = saved })
+
+ notifierURL, victimHits := startVictimAndRedirector(t)
+
+ err := shoutrrr.Send(notifierURL, "Test message from Homebox")
+ require.Error(t, err, "guarded: redirect to loopback must be refused and the send must fail")
+ assert.Equal(t, int32(0), victimHits(), "guarded: the blocked redirect target must never be reached")
+}
diff --git a/backend/internal/sys/validate/notifier_url.go b/backend/internal/sys/validate/notifier_url.go
index 846f5ed5..7014c1f5 100644
--- a/backend/internal/sys/validate/notifier_url.go
+++ b/backend/internal/sys/validate/notifier_url.go
@@ -35,7 +35,19 @@ func ValidateNotifierURL(notifierURL string, cfg *config.NotifierConf) error {
return fmt.Errorf("invalid URL in generic notifier: %w", err)
}
- host := parsedURL.Hostname()
+ return validateHostAgainstPolicy(parsedURL.Hostname(), cfg)
+}
+
+// validateHostAgainstPolicy resolves host and checks every resolved IP (plus any
+// DNS64-embedded IPv4) against the configured allow/block policy. It is shared by
+// ValidateNotifierURL (the initial notifier URL) and NotifierRedirectGuard (each
+// redirect hop at delivery time) so both enforce identical rules — the redirect
+// path previously escaped these checks entirely, which was the SSRF bypass.
+func validateHostAgainstPolicy(host string, cfg *config.NotifierConf) error {
+ if cfg == nil {
+ return fmt.Errorf("notifier configuration is nil, cannot validate URL")
+ }
+
if host == "" {
return fmt.Errorf("no hostname found in URL")
}