SendGrid: Add optional webhook signature verification

Add optional signature verification for SendGrid tracking webhooks

Author: blag

CHANGELOG.rst

@@ -25,6 +25,24 @@ Release history
 ^^^^^^^^^^^^^^^
     ..  This extra heading level keeps the ToC from becoming unmanageably long
 
+vNext
+-----
+
+*unreleased changes*
+
+Features
+~~~~~~~~
+
+* **SendGrid:** Add optional signature verification for tracking webhooks.
+  To support this, Anymail now includes the :pypi:`cryptography` package when
+  installed with the ``django-anymail[sendgrid]`` extra.
+  (Thanks to `@blag`_ for contributing this improvement. Note this was tested
+  against SendGrid's live API by its contributor at the time it was added,
+  but cannot be independently verified by Anymail's maintainers as we
+  `no longer have access <https://github.com/anymail/django-anymail/issues/432>`__
+  to a SendGrid test account.)
+
+
 v13.0.1
 -------
 
@@ -1796,6 +1814,7 @@ Features
 .. _@anstosa: https://github.com/anstosa
 .. _@Arondit: https://github.com/Arondit
 .. _@b0d0nne11: https://github.com/b0d0nne11
+.. _@blag: https://github.com/blag
 .. _@calvin: https://github.com/calvin
 .. _@carrerasrodrigo: https://github.com/carrerasrodrigo
 .. _@chickahoona: https://github.com/chickahoona

anymail/webhooks/base.py

@@ -125,11 +125,10 @@ def __init__(self, **kwargs):
             # no esp_name -- auth is shared between ESPs
             kwargs=kwargs,
         )
-
-        # Allow a single string:
-        if isinstance(self.basic_auth, str):
+        # Allow a single, non-empty string:
+        if isinstance(self.basic_auth, str) and self.basic_auth:
             self.basic_auth = [self.basic_auth]
-        if self.warn_if_no_basic_auth and len(self.basic_auth) < 1:
+        if self.warn_if_no_basic_auth and not self.basic_auth:
             warnings.warn(
                 "Your Anymail webhooks are insecure and open to anyone on the web. "
                 "You should set WEBHOOK_SECRET in your ANYMAIL settings. "

anymail/webhooks/sendgrid.py

@@ -1,10 +1,19 @@
+from __future__ import annotations
+
+import base64
+import binascii
 import json
 import warnings
 from datetime import datetime, timezone
 from email.parser import BytesParser
 from email.policy import default as default_policy
 
-from ..exceptions import AnymailNotSupportedWarning
+from ..exceptions import (
+    AnymailImproperlyInstalled,
+    AnymailNotSupportedWarning,
+    AnymailWebhookValidationFailure,
+    _LazyError,
+)
 from ..inbound import AnymailInboundMessage
 from ..signals import (
     AnymailInboundEvent,
@@ -14,23 +23,122 @@
     inbound,
     tracking,
 )
+from ..utils import get_anymail_setting
 from .base import AnymailBaseWebhookView
 
+try:
+    from cryptography.exceptions import InvalidSignature
+    from cryptography.hazmat.backends import default_backend
+    from cryptography.hazmat.primitives import hashes, serialization
+    from cryptography.hazmat.primitives.asymmetric import ec, types
+except ImportError:
+    # This module gets imported by anymail.urls, so don't complain about cryptography
+    # missing unless one of the SendGrid webhook views is actually used and needs it
+    error = _LazyError(
+        AnymailImproperlyInstalled(
+            missing_package="cryptography", install_extra="sendgrid"
+        )
+    )
+    serialization = error
+    hashes = error
+    default_backend = error
+    ec = error
+    InvalidSignature = Exception
 
-class SendGridTrackingWebhookView(AnymailBaseWebhookView):
-    """Handler for SendGrid delivery and engagement tracking webhooks"""
 
-    esp_name = "SendGrid"
-    signal = tracking
+class SendGridBaseWebhookView(AnymailBaseWebhookView):
+    # Derived classes must set to name of webhook verification key setting
+    # (lowercase, don't include esp_name).
+    key_setting_name: str
+
+    # Loaded from key_setting_name; None -> signature verification is skipped
+    webhook_verification_key: "types.PublicKeyTypes | None" = None
+
+    @classmethod
+    def as_view(cls, **initkwargs):
+        if not hasattr(cls, cls.key_setting_name):
+            # The attribute must exist on the class before View.as_view
+            # will allow overrides via kwarg
+            setattr(cls, cls.key_setting_name, None)
+        return super().as_view(**initkwargs)
 
     def __init__(self, **kwargs):
+        verification_key: str | None = get_anymail_setting(
+            self.key_setting_name,
+            esp_name=self.esp_name,
+            default=None,
+            kwargs=kwargs,
+            allow_bare=True,
+        )
+        if verification_key:
+            self.webhook_verification_key = serialization.load_pem_public_key(
+                (
+                    "-----BEGIN PUBLIC KEY-----\n"
+                    + verification_key
+                    + "\n-----END PUBLIC KEY-----"
+                ).encode("utf-8"),
+                backend=default_backend(),
+            )
+        if self.webhook_verification_key:
+            # If the webhook key is successfully configured, then we don't need to warn about
+            # missing basic auth
+            self.warn_if_no_basic_auth = False
+        else:
+            # Purely defensive programming; should already be set to True
+            self.warn_if_no_basic_auth = True
+
         super().__init__(**kwargs)
         warnings.warn(
             "django-anymail has dropped official support for SendGrid."
             " See https://github.com/anymail/django-anymail/issues/432.",
             AnymailNotSupportedWarning,
         )
 
+    def validate_request(self, request):
+        if self.webhook_verification_key:
+            try:
+                signature = request.headers["X-Twilio-Email-Event-Webhook-Signature"]
+            except KeyError:
+                raise AnymailWebhookValidationFailure(
+                    "X-Twilio-Email-Event-Webhook-Signature header missing from webhook"
+                )
+            try:
+                timestamp = request.headers["X-Twilio-Email-Event-Webhook-Timestamp"]
+            except KeyError:
+                raise AnymailWebhookValidationFailure(
+                    "X-Twilio-Email-Event-Webhook-Timestamp header missing from webhook"
+                )
+
+            timestamped_payload = timestamp.encode("utf-8") + request.body
+
+            try:
+                decoded_signature = base64.b64decode(signature)
+                self.webhook_verification_key.verify(
+                    decoded_signature,
+                    timestamped_payload,
+                    ec.ECDSA(hashes.SHA256()),
+                )
+            # We intentionally respond the same to both of these issues, see below
+            # binascii.Error may come from attempting to base64-decode the signature
+            # InvalidSignature will come from self.webhook_key.verify(...)
+            except (binascii.Error, InvalidSignature):
+                # We intentionally don't give out too much information here, because that would
+                # make it easier used to characterize the issue and workaround the signature
+                # verification
+                setting_name = f"{self.esp_name}_{self.key_setting_name}".upper()
+                raise AnymailWebhookValidationFailure(
+                    "SendGrid webhook called with incorrect signature"
+                    f" (check Anymail {setting_name} setting)"
+                )
+
+
+class SendGridTrackingWebhookView(SendGridBaseWebhookView):
+    """Handler for SendGrid delivery and engagement tracking webhooks"""
+
+    esp_name = "SendGrid"
+    key_setting_name = "tracking_webhook_verification_key"
+    signal = tracking
+
     def parse_events(self, request):
         esp_events = json.loads(request.body.decode("utf-8"))
         return [self.esp_to_anymail_event(esp_event) for esp_event in esp_events]
@@ -146,6 +254,16 @@ class SendGridInboundWebhookView(AnymailBaseWebhookView):
     esp_name = "SendGrid"
     signal = inbound
 
+    # The inbound webhook does not currently implement signature validation
+    # because we don't have access to a SendGrid account that could test it.
+    # It *should* only require changing to SendGridBaseWebhookView and
+    # providing the setting name:
+    #
+    #     class SendGridInboundWebhookView(SendGridBaseWebhookView):
+    #         key_setting_name = "inbound_webhook_verification_key"
+    #
+    # and then setting SENDGRID_INBOUND_WEBHOOK_VERIFICATION_KEY.
+
     def __init__(self, **kwargs):
         super().__init__(**kwargs)
         warnings.warn(

docs/esps/sendgrid.rst

@@ -45,6 +45,31 @@ Anymail integrates with the Twilio `SendGrid`_ email service, using their `Web A
 .. _activity feed: https://app.sendgrid.com/email_activity?events=drops
 
 
+.. _sendgrid-installation:
+
+Installation
+------------
+
+Anymail optionally uses the :pypi:`cryptography` package to validate SendGrid webhook
+signatures. If you will use Anymail's :ref:`status tracking <event-tracking>` webhook
+with SendGrid signature verification, be sure to include the ``[sendgrid]`` option
+when you install Anymail:
+
+    .. code-block:: console
+
+        $ python -m pip install 'django-anymail[sendgrid]'
+
+(Or separately run ``python -m pip install cryptography``.)
+
+If you don't plan to use SendGrid signature verification, cryptography
+is not required. To avoid installing it, omit the ``[sendgrid]`` option.
+See :ref:`sendgrid-webhooks` below for details.
+
+.. versionchanged:: vNext
+
+    Added cryptography to the ``[sendgrid]`` extras.
+
+
 Settings
 --------
 
@@ -82,6 +107,27 @@ nor ``ANYMAIL_SENDGRID_API_KEY`` is set.
 .. _SendGrid API key settings: https://app.sendgrid.com/settings/api_keys
 
 
+.. setting:: ANYMAIL_SENDGRID_TRACKING_WEBHOOK_VERIFICATION_KEY
+
+.. rubric:: SENDGRID_TRACKING_WEBHOOK_VERIFICATION_KEY
+
+Optional additional public-key verification when using status tracking
+webhooks. See :ref:`sendgrid-webhooks` below.
+
+This should be set to the verification key provided in the Event Webhook page
+of SendGrid Mail Settings.
+
+  .. code-block:: python
+
+      ANYMAIL = {
+          ...
+          "SENDGRID_TRACKING_WEBHOOK_VERIFICATION_KEY": "A8f746...9fuVqQ==",
+      }
+
+(Note this works only with SendGrid's cryptographic signature verification,
+*not* their OAuth 2.0 option.)
+
+
 .. setting:: ANYMAIL_SENDGRID_GENERATE_MESSAGE_ID
 
 .. rubric:: SENDGRID_GENERATE_MESSAGE_ID
@@ -407,13 +453,45 @@ in either Anymail settings or esp_extra as described above.)
 Status tracking webhooks
 ------------------------
 
-If you are using Anymail's normalized :ref:`status tracking <event-tracking>`, enter
-the url in your `SendGrid mail settings`_, under "Event Notification":
+Anymail's normalized :ref:`status tracking <event-tracking>` works
+with SendGrid's webhooks.
 
-   :samp:`https://{random}:{random}@{yoursite.example.com}/anymail/sendgrid/tracking/`
+SendGrid optionally provides webhook signature verification. You have three
+choices for securing the status tracking webhook:
 
-     * *random:random* is an :setting:`ANYMAIL_WEBHOOK_SECRET` shared secret
-     * *yoursite.example.com* is your Django site
+* Use SendGrid's signature verification: follow their
+  `Event Webhook Security Features`_ documentation and set
+  :setting:`SENDGRID_TRACKING_WEBHOOK_VERIFICATION_KEY <ANYMAIL_SENDGRID_TRACKING_WEBHOOK_VERIFICATION_KEY>`
+  (requires the :pypi:`cryptography` package---see :ref:`sendgrid-installation`)
+* Use Anymail's shared secret validation, by setting
+  :setting:`WEBHOOK_SECRET <ANYMAIL_WEBHOOK_SECRET>`
+  (does not require cryptography)
+* Use both
+
+Signature verification is recommended, unless you do not want to add
+cryptography to your dependencies.
+
+.. versionchanged:: vNext
+
+    Added support for SendGrid webhook signature verification.
+    (Earlier releases supported only shared secret validation.)
+
+.. _Event Webhook Security Features:
+    https://www.twilio.com/docs/sendgrid/for-developers/tracking-events/getting-started-event-webhook-security-features#the-signed-event-webhook
+
+
+To configure Anymail status tracking for SendGrid, enter one of these urls
+in your `SendGrid mail settings`_ under "Event Notification" (substituting
+your Django site for *yoursite.example.com*):
+
+*   If you are *not* using Anymail's shared webhook secret:
+
+        :samp:`https://{yoursite.example.com}/anymail/sendgrid/tracking/`
+
+*   Or if you *are* using Anymail's :setting:`WEBHOOK_SECRET <ANYMAIL_WEBHOOK_SECRET>`,
+    include the *random:random* shared secret in the URL:
+
+        :samp:`https://{random}:{random}@{yoursite.example.com}/sendgrid/tracking/`
 
 Be sure to check the boxes in the SendGrid settings for the event types you want to receive.
 
@@ -446,6 +524,8 @@ The Destination URL setting will be:
      * *random:random* is an :setting:`ANYMAIL_WEBHOOK_SECRET` shared secret
      * *yoursite.example.com* is your Django site
 
+(Anymail does not currently support signature verification for the inbound parse webhook.)
+
 You should enable SendGrid's "POST the raw, full MIME message" checkbox (see note below).
 And be sure the URL has a trailing slash. (SendGrid's inbound processing won't follow Django's
 :setting:`APPEND_SLASH` redirect.)

pyproject.toml

@@ -79,7 +79,13 @@ mailjet = []
 mandrill = []
 postmark = []
 resend = ["svix"]
-sendgrid = []
+sendgrid = [
+    # SendGrid optionally uses cryptography for verifying webhook signatures.
+    # Cryptography's wheels are broken on darwin-arm64 before Python 3.9,
+    # and unbuildable on PyPy 3.8 due to PyO3 limitations. Since cpython 3.8
+    # has also passed EOL, just require Python 3.9+ with SendGrid.
+    "cryptography; python_version >= '3.9'"
+]
 sendinblue = []
 sparkpost = []
 unisender-go = []