Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Allow operator-trusted internal hosts for webhook endpoints (#14769)
Matthew Kennedy9c0ee20ef972
diff --git a/docs/developer/core-concepts/webhooks.mdx b/docs/developer/core-concepts/webhooks.mdxindex d45f36dca1..aba60d7cce 100644--- a/docs/developer/core-concepts/webhooks.mdx+++ b/docs/developer/core-concepts/webhooks.mdx@@ -376,6 +376,19 @@ Webhooks are on by default and can be switched off installation-wide.SSL certificates are verified in production, and not in development — so you can point an endpoint at a local tunnel with a self-signed certificate while building. Both are configurable if your environment needs something different.+### Internal endpoints++Outside development, Spree refuses webhook URLs that resolve to a private or internal address — both when the endpoint is saved and when each delivery is sent — so an endpoint can't be used to reach your internal network.++If the receiver is a service you run on a private network, such as a storefront in the same Kubernetes cluster, allow its host with `SPREE_WEBHOOKS_ALLOWED_INTERNAL_HOSTS`:++```bash+# One exact host, and every host under .svc.cluster.local+SPREE_WEBHOOKS_ALLOWED_INTERNAL_HOSTS=storefront.internal,.svc.cluster.local+```++An entry matches that exact host; an entry with a leading dot matches any host under it (`.svc.cluster.local` matches `storefront.shop.svc.cluster.local`, not `evil-svc.cluster.local`). Matching is case-insensitive. The list is installation config only — store admins can't change it — and every host not on it stays behind the guard.+## Available EventsWebhooks can subscribe to any event in Spree's event system. See [Webhook Events & Payloads](/api-reference/webhooks-events) for the complete list, or [list them through the Admin API](#event-subscriptions) to include the events your extensions add.@@ -466,6 +479,7 @@ curl -X POST 'https://api.mystore.com/api/v3/admin/webhook_endpoints' \2. Verify the endpoint is marked active3. Confirm the endpoint actually subscribes to the event you expect4. Check the event belongs to the same store as the endpoint+5. If the endpoint is on a private network, check its host is in `SPREE_WEBHOOKS_ALLOWED_INTERNAL_HOSTS` — otherwise every delivery fails with `has no public ip addresses`### Signature Verification Failingdiff --git a/docs/developer/customization/configuration.mdx b/docs/developer/customization/configuration.mdxindex f9a6e5646d..ce72403b9b 100644--- a/docs/developer/customization/configuration.mdx+++ b/docs/developer/customization/configuration.mdx@@ -121,6 +121,7 @@ boot rather than silently reverting to the default.|---|---|---|| `SPREE_WEBHOOKS_ENABLED` | `true` | Whether webhooks fire at all. || `SPREE_WEBHOOKS_VERIFY_SSL` | `true` | Verifies SSL certificates on webhook endpoints. Off in development. |+| `SPREE_WEBHOOKS_ALLOWED_INTERNAL_HOSTS` | — | Comma-separated hosts webhooks may reach even though they resolve to a private address, e.g. `storefront.internal,.svc.cluster.local`. A leading dot matches any host under it. See [internal endpoints](/developer/core-concepts/webhooks#internal-endpoints). |## Relateddiff --git a/spree/api/app/services/spree/webhooks/deliver_webhook.rb b/spree/api/app/services/spree/webhooks/deliver_webhook.rbindex d94052e347..99cda2dbc3 100644--- a/spree/api/app/services/spree/webhooks/deliver_webhook.rb+++ b/spree/api/app/services/spree/webhooks/deliver_webhook.rb@@ -90,10 +90,14 @@ module Spreehttp_options = { open_timeout: TIMEOUT, read_timeout: TIMEOUT, verify_mode: ssl_verify_mode }# SSRF protection is disabled in development so webhooks can reach- # localhost / host.docker.internal (the storefront running on the host).- if Rails.env.development?+ # localhost / host.docker.internal (the storefront running on the host),+ # and for hosts the operator explicitly trusts+ # (Spree::Api::Config.webhooks_allowed_internal_hosts).+ if Rails.env.development? || Spree::WebhookEndpoint.allowed_internal_host?(@delivery.url)uri = URI.parse(@delivery.url)- http = Net::HTTP.new(uri.host, uri.port)+ # No proxy, as SsrfFilter: an egress proxy from the environment would+ # carry this in-cluster (or localhost) request out of the network.+ http = Net::HTTP.new(uri.hostname, uri.port, nil)http.use_ssl = uri.scheme == 'https'http_options.each { |k, v| http.send(:"#{k}=", v) }diff --git a/spree/api/lib/spree/api/configuration.rb b/spree/api/lib/spree/api/configuration.rbindex fb8e668583..d3999becc9 100644--- a/spree/api/lib/spree/api/configuration.rb+++ b/spree/api/lib/spree/api/configuration.rb@@ -27,6 +27,11 @@ module Spreepreference :webhooks_enabled, :boolean, default: true, env: 'SPREE_WEBHOOKS_ENABLED'preference :webhooks_verify_ssl, :boolean, default: !Rails.env.development?, env: 'SPREE_WEBHOOKS_VERIFY_SSL'+ # Hosts a webhook may reach even though they resolve to a private+ # address (the SSRF guard otherwise refuses them). "host" matches that+ # host; ".suffix" matches any host under it. See+ # Spree::WebhookEndpoint.allowed_internal_host?.+ preference :webhooks_allowed_internal_hosts, :array, default: [], env: 'SPREE_WEBHOOKS_ALLOWED_INTERNAL_HOSTS'endendenddiff --git a/spree/api/spec/lib/spree/api/configuration_spec.rb b/spree/api/spec/lib/spree/api/configuration_spec.rbnew file mode 100644index 0000000000..6fb062b119--- /dev/null+++ b/spree/api/spec/lib/spree/api/configuration_spec.rb@@ -0,0 +1,19 @@+# frozen_string_literal: true++require 'spec_helper'++describe Spree::Api::Configuration do+ describe '#webhooks_allowed_internal_hosts' do+ it 'allows no internal hosts by default' do+ stub_const('ENV', ENV.to_h.except('SPREE_WEBHOOKS_ALLOWED_INTERNAL_HOSTS'))++ expect(described_class.new.webhooks_allowed_internal_hosts).to eq([])+ end++ it 'reads a comma-separated list from the environment' do+ stub_const('ENV', ENV.to_h.merge('SPREE_WEBHOOKS_ALLOWED_INTERNAL_HOSTS' => 'storefront.internal, .svc.cluster.local'))++ expect(described_class.new.webhooks_allowed_internal_hosts).to eq(['storefront.internal', '.svc.cluster.local'])+ end+ end+enddiff --git a/spree/api/spec/services/spree/webhooks/deliver_webhook_spec.rb b/spree/api/spec/services/spree/webhooks/deliver_webhook_spec.rbindex 008b2a00c6..a6f636f5dd 100644--- a/spree/api/spec/services/spree/webhooks/deliver_webhook_spec.rb+++ b/spree/api/spec/services/spree/webhooks/deliver_webhook_spec.rb@@ -10,6 +10,15 @@ module Spreelet(:delivery) { create(:webhook_delivery, :pending, webhook_endpoint: webhook_endpoint) }let(:secret_key) { webhook_endpoint.secret_key }+ # The Net::HTTP connections a delivery opens on its direct path.+ def capture_http_connections+ connections = []+ allow(Net::HTTP).to receive(:new).and_wrap_original do |original, *args|+ original.call(*args).tap { |http| connections << http }+ end+ connections+ end+describe '.call' docontext 'when the payload had credentials withheld from the log' dolet(:delivery) do@@ -293,6 +302,92 @@ module Spreeexpect(delivery.request_errors).to include('blocked internal address')endend++ context 'when the endpoint host is an allowed internal host' do+ let(:webhook_endpoint) do+ create(:webhook_endpoint, store: store, url: 'http://storefront.shop.svc.cluster.local/api/webhooks/spree')+ end++ before do+ allow(Spree::Api::Config).to receive(:webhooks_allowed_internal_hosts).and_return(['.svc.cluster.local'])+ allow(SsrfFilter).to receive(:post)+ stub_request(:post, delivery.url).to_return(status: 200, body: '{}')+ end++ after { described_class.header_decorators.clear }++ it 'delivers directly instead of through SsrfFilter' do+ described_class.call(delivery: delivery, secret_key: secret_key)++ expect(SsrfFilter).not_to have_received(:post)+ expect(delivery.reload.success).to be true+ end++ it 'signs the body that was actually sent' do+ Timecop.freeze do+ described_class.call(delivery: delivery, secret_key: secret_key)++ expect(WebMock).to have_requested(:post, delivery.url).with { |req|+ expected = OpenSSL::HMAC.hexdigest('SHA256', secret_key, "#{Time.current.to_i}.#{req.body}")+ req.headers['X-Spree-Webhook-Signature'] == expected+ }+ end+ end++ it 'applies registered header decorators' do+ described_class.header_decorators << ->(headers, _delivery) { headers['traceparent'] = '00-trace-01' }++ described_class.call(delivery: delivery, secret_key: secret_key)++ expect(WebMock).to have_requested(:post, delivery.url).with(headers: { 'traceparent' => '00-trace-01' })+ end++ # SsrfFilter connects without a proxy; the direct path must too, or an+ # egress proxy from the environment would carry in-cluster traffic.+ it 'ignores a proxy configured in the environment' do+ stub_const('ENV', ENV.to_h.merge('http_proxy' => 'http://proxy.example:3128').except('no_proxy', 'NO_PROXY'))+ connections = capture_http_connections++ described_class.call(delivery: delivery, secret_key: secret_key)++ expect(connections.sole.proxy?).to be false+ end+ end++ context 'when the endpoint is an allowed IPv6 address' do+ let(:webhook_endpoint) do+ create(:webhook_endpoint, store: store, url: 'http://[::1]/api/webhooks/spree')+ end++ before do+ allow(Spree::Api::Config).to receive(:webhooks_allowed_internal_hosts).and_return(['::1'])+ stub_request(:post, delivery.url).to_return(status: 200, body: '{}')+ end++ it 'connects to the address without its URL brackets' do+ connections = capture_http_connections++ described_class.call(delivery: delivery, secret_key: secret_key)++ expect(connections.sole.address).to eq('::1')+ end+ end++ context 'when other internal hosts are allowed but not this one' do+ before do+ delivery+ allow(Spree::Api::Config).to receive(:webhooks_allowed_internal_hosts).and_return(['.svc.cluster.local'])+ allow(SsrfFilter).to receive(:post).and_raise(SsrfFilter::PrivateIPAddress, 'URL resolves to a blocked internal address')+ allow(Rails.error).to receive(:report)+ end++ it 'still delivers through SsrfFilter' do+ described_class.call(delivery: delivery, secret_key: secret_key)++ expect(SsrfFilter).to have_received(:post)+ expect(delivery.reload.error_type).to eq('connection_error')+ end+ endendendenddiff --git a/spree/core/app/models/spree/webhook_endpoint.rb b/spree/core/app/models/spree/webhook_endpoint.rbindex 41cd78f267..6975cbe7b5 100644--- a/spree/core/app/models/spree/webhook_endpoint.rb+++ b/spree/core/app/models/spree/webhook_endpoint.rb@@ -36,6 +36,39 @@ module Spreescope :inactive, -> { where(active: false) }scope :enabled, -> { active.where(disabled_at: nil) }+ # Whether +url+ targets a host the operator trusts despite it resolving to+ # a private address — e.g. a storefront Service in the same Kubernetes+ # cluster. Set via +Spree::Api::Config.webhooks_allowed_internal_hosts++ # (SPREE_WEBHOOKS_ALLOWED_INTERNAL_HOSTS): an entry matches that exact+ # host, or with a leading dot (".svc.cluster.local") any host under it.+ # Matching is case-insensitive. Operator config only, so a store admin+ # can never point a webhook at an internal address.+ #+ # @param url [String]+ # @return [Boolean]+ def self.allowed_internal_host?(url)+ host = URI.parse(url.to_s).hostname&.downcase+ return false if host.blank?++ allowed_internal_hosts.any? do |entry|+ entry.start_with?('.') ? host.end_with?(entry) : host == entry+ end+ rescue URI::InvalidURIError+ false+ end++ # Spree::Api::Config only exists when spree_api is loaded; without it no+ # webhook is ever delivered, so there is nothing to allow.+ def self.allowed_internal_hosts+ return [] unless defined?(Spree::Api::Config)++ Array(Spree::Api::Config.webhooks_allowed_internal_hosts).filter_map do |entry|+ entry = entry.to_s.strip.downcase+ entry if entry.present? && entry != '.'+ end+ end+ private_class_method :allowed_internal_hosts+# Returns the plaintext `secret_key` only on the create response.## `@reveal_secret_in_response` is set by the `after_create` callback above@@ -166,6 +199,8 @@ module Spreeenddef url_must_not_resolve_to_private_ip+ return if self.class.allowed_internal_host?(url)+uri = URI.parse(url)blacklist = SsrfFilter::IPV4_BLACKLIST + SsrfFilter::IPV6_BLACKLISTaddresses = Resolv.getaddresses(uri.host)diff --git a/spree/core/spec/models/spree/webhook_endpoint_spec.rb b/spree/core/spec/models/spree/webhook_endpoint_spec.rbindex 7d38b97812..511ad0480d 100644--- a/spree/core/spec/models/spree/webhook_endpoint_spec.rb+++ b/spree/core/spec/models/spree/webhook_endpoint_spec.rb@@ -43,6 +43,46 @@ describe Spree::WebhookEndpoint, type: :model doexpect(webhook_endpoint).not_to be_validexpect(webhook_endpoint.errors[:url]).to include('must not point to an internal or private network address')end++ context 'with allowed internal hosts configured' do+ before do+ stub_const('Spree::Api::Config', double(webhooks_allowed_internal_hosts: ['storefront.internal', '.svc.cluster.local']))+ allow(Resolv).to receive(:getaddresses).and_return(['10.43.0.15'])+ end++ it 'accepts an exactly matching host' do+ webhook_endpoint.url = 'http://storefront.internal/api/webhooks/spree'+ expect(webhook_endpoint).to be_valid+ end++ it 'matches hosts case-insensitively' do+ webhook_endpoint.url = 'http://Storefront.Internal/api/webhooks/spree'+ expect(webhook_endpoint).to be_valid+ end++ it 'accepts a host under a leading-dot suffix' do+ webhook_endpoint.url = 'http://storefront.shop.svc.cluster.local/api/webhooks/spree'+ expect(webhook_endpoint).to be_valid+ end++ it 'matches an IPv6 address without its URL brackets' do+ stub_const('Spree::Api::Config', double(webhooks_allowed_internal_hosts: ['::1']))+ webhook_endpoint.url = 'http://[::1]/api/webhooks/spree'+ expect(webhook_endpoint).to be_valid+ end++ it 'rejects a host that only ends with the suffix text' do+ webhook_endpoint.url = 'http://evil-svc.cluster.local/api/webhooks/spree'+ expect(webhook_endpoint).not_to be_valid+ expect(webhook_endpoint.errors[:url]).to include('must not point to an internal or private network address')+ end++ it 'still rejects a private host that is not allowed' do+ webhook_endpoint.url = 'http://other.internal/api/webhooks/spree'+ expect(webhook_endpoint).not_to be_valid+ expect(webhook_endpoint.errors[:url]).to include('must not point to an internal or private network address')+ end+ endendend