Skip to content

armgit / spree

Public Imported from GitHub
0

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.

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.mdx
index 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 Events
Webhooks 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 active
3. Confirm the endpoint actually subscribes to the event you expect
4. 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 Failing
diff --git a/docs/developer/customization/configuration.mdx b/docs/developer/customization/configuration.mdx
index 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). |
## Related
diff --git a/spree/api/app/services/spree/webhooks/deliver_webhook.rb b/spree/api/app/services/spree/webhooks/deliver_webhook.rb
index 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 Spree
http_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.rb
index fb8e668583..d3999becc9 100644
--- a/spree/api/lib/spree/api/configuration.rb
+++ b/spree/api/lib/spree/api/configuration.rb
@@ -27,6 +27,11 @@ module Spree
preference :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'
end
end
end
diff --git a/spree/api/spec/lib/spree/api/configuration_spec.rb b/spree/api/spec/lib/spree/api/configuration_spec.rb
new file mode 100644
index 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
+end
diff --git a/spree/api/spec/services/spree/webhooks/deliver_webhook_spec.rb b/spree/api/spec/services/spree/webhooks/deliver_webhook_spec.rb
index 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 Spree
let(: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' do
context 'when the payload had credentials withheld from the log' do
let(:delivery) do
@@ -293,6 +302,92 @@ module Spree
expect(delivery.request_errors).to include('blocked internal address')
end
end
+
+ 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
+ end
end
end
end
diff --git a/spree/core/app/models/spree/webhook_endpoint.rb b/spree/core/app/models/spree/webhook_endpoint.rb
index 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 Spree
scope :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 Spree
end
def 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_BLACKLIST
addresses = 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.rb
index 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 do
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
+
+ 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
+ end
end
end