diff --git a/api/core/network.py b/api/core/network.py index 40baad2facba..5d6f081403a5 100644 --- a/api/core/network.py +++ b/api/core/network.py @@ -1,9 +1,109 @@ +import errno +import http.client import ipaddress import socket +import ssl +from collections.abc import Iterator + +import requests # RFC 6598 carrier-grade NAT; not caught by ipaddress.is_private. _SHARED_ADDRESS_SPACE = ipaddress.ip_network("100.64.0.0/10") +# OpenSSL 3+ certificate verification results, from `include/openssl/x509_vfy.h`. +# Python exposes the numeric `verify_code`, but not the constant names. +_CERT_VERIFY_ERROR_NAMES = { + 2: "X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT", + 3: "X509_V_ERR_UNABLE_TO_GET_CRL", + 4: "X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE", + 5: "X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE", + 6: "X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY", + 7: "X509_V_ERR_CERT_SIGNATURE_FAILURE", + 8: "X509_V_ERR_CRL_SIGNATURE_FAILURE", + 9: "X509_V_ERR_CERT_NOT_YET_VALID", + 10: "X509_V_ERR_CERT_HAS_EXPIRED", + 11: "X509_V_ERR_CRL_NOT_YET_VALID", + 12: "X509_V_ERR_CRL_HAS_EXPIRED", + 13: "X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD", + 14: "X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD", + 15: "X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD", + 16: "X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD", + 18: "X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT", + 19: "X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN", + 20: "X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY", + 21: "X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE", + 22: "X509_V_ERR_CERT_CHAIN_TOO_LONG", + 23: "X509_V_ERR_CERT_REVOKED", + 24: "X509_V_ERR_NO_ISSUER_PUBLIC_KEY", + 25: "X509_V_ERR_PATH_LENGTH_EXCEEDED", + 26: "X509_V_ERR_INVALID_PURPOSE", + 27: "X509_V_ERR_CERT_UNTRUSTED", + 28: "X509_V_ERR_CERT_REJECTED", + 62: "X509_V_ERR_HOSTNAME_MISMATCH", + 64: "X509_V_ERR_IP_ADDRESS_MISMATCH", + 66: "X509_V_ERR_EE_KEY_TOO_SMALL", + 67: "X509_V_ERR_CA_KEY_TOO_SMALL", + 68: "X509_V_ERR_CA_MD_TOO_WEAK", + 79: "X509_V_ERR_INVALID_CA", +} + +# getaddrinfo() returns EAI_* codes, which don't overlap with errno. +_GETADDRINFO_ERROR_NAMES = { + getattr(socket, name): name for name in dir(socket) if name.startswith("EAI_") +} + + +def get_request_error_code(error: requests.RequestException) -> str | None: + """Return the POSIX error name, or the OpenSSL certificate verification + error name, for a request that failed without an HTTP response.""" + if isinstance(error, requests.exceptions.Timeout): + return "ETIMEDOUT" + for exc in _iter_exception_chain(error): + if code := _get_exception_error_code(exc): + return code + return None + + +def _get_exception_error_code(exc: BaseException) -> str | None: + # SSL errors subclass OSError, with an OpenSSL-specific errno. + if isinstance(exc, ssl.SSLCertVerificationError): + return _CERT_VERIFY_ERROR_NAMES.get(exc.verify_code, "EPROTO") + if isinstance(exc, ssl.SSLError): + return "EPROTO" + if isinstance(exc, socket.gaierror) and exc.errno is not None: + return _GETADDRINFO_ERROR_NAMES.get(exc.errno) + if isinstance(exc, OSError) and exc.errno is not None: + if name := errno.errorcode.get(exc.errno): + return name + # A socket timeout, e.g. connecting to a proxy, without an errno. + if isinstance(exc, TimeoutError): + return "ETIMEDOUT" + # e.g. `RemoteDisconnected`: the peer closed without responding. + if isinstance(exc, ConnectionResetError): + return "ECONNRESET" + # The peer responded with something other than HTTP. + if isinstance(exc, http.client.HTTPException): + return "EPROTO" + return None + + +def _iter_exception_chain(error: BaseException) -> Iterator[BaseException]: + # requests and urllib3 wrap the underlying error in `reason` and + # `original_error` as well as in the standard `__cause__`/`__context__`. + seen: set[int] = set() + pending: list[BaseException] = [error] + while pending: + exc = pending.pop(0) + if id(exc) in seen: + continue + seen.add(id(exc)) + yield exc + for attr in ("reason", "original_error", "__cause__", "__context__"): + linked = getattr(exc, attr, None) + if isinstance(linked, BaseException): + pending.append(linked) + pending.extend(arg for arg in exc.args if isinstance(arg, BaseException)) + def is_internal_address( hostname: str, diff --git a/api/tests/unit/core/test_network.py b/api/tests/unit/core/test_network.py new file mode 100644 index 000000000000..d2be751f9e98 --- /dev/null +++ b/api/tests/unit/core/test_network.py @@ -0,0 +1,225 @@ +import errno +import http.client +import socket +import ssl +from typing import TypeVar + +import pytest +import requests +from urllib3 import HTTPSConnectionPool +from urllib3.connection import HTTPSConnection +from urllib3.exceptions import ( + ConnectTimeoutError, + MaxRetryError, + NameResolutionError, + NewConnectionError, + ProtocolError, +) +from urllib3.exceptions import ProxyError as Urllib3ProxyError +from urllib3.exceptions import SSLError as Urllib3SSLError + +from core.network import get_request_error_code + +_E = TypeVar("_E", bound=BaseException) + +# Constructing these doesn't open a connection. +_POOL = HTTPSConnectionPool("example.com") +_CONN = HTTPSConnection("example.com") + + +def _caused_by(error: _E, cause: BaseException) -> _E: + error.__cause__ = cause + return error + + +def _max_retries(reason: Exception) -> MaxRetryError: + # How requests' HTTPAdapter receives connection failures from urllib3. + return MaxRetryError(_POOL, "/", reason=reason) + + +def _cert_verify_error(verify_code: int) -> ssl.SSLCertVerificationError: + error = ssl.SSLCertVerificationError(1, "certificate verify failed") + error.verify_code = verify_code + return error + + +@pytest.mark.parametrize( + "error, expected_code", + [ + ( + requests.exceptions.ConnectionError( + _max_retries( + _caused_by( + NewConnectionError(_CONN, "Failed to establish a connection"), + ConnectionRefusedError(errno.ECONNREFUSED, "refused"), + ) + ) + ), + "ECONNREFUSED", + ), + ( + requests.exceptions.ConnectionError( + _max_retries( + _caused_by( + NewConnectionError(_CONN, "Failed to establish a connection"), + OSError(errno.EHOSTUNREACH, "no route to host"), + ) + ) + ), + "EHOSTUNREACH", + ), + ( + requests.exceptions.ConnectionError( + _max_retries( + _caused_by( + NameResolutionError( + "example.com", + _CONN, + socket.gaierror(socket.EAI_NONAME, "Name not known"), + ), + socket.gaierror(socket.EAI_NONAME, "Name not known"), + ) + ) + ), + "EAI_NONAME", + ), + ( + requests.exceptions.ConnectionError( + _max_retries( + _caused_by( + NameResolutionError( + "example.com", + _CONN, + socket.gaierror(socket.EAI_AGAIN, "Temporary failure"), + ), + socket.gaierror(socket.EAI_AGAIN, "Temporary failure"), + ) + ) + ), + "EAI_AGAIN", + ), + ( + requests.exceptions.ConnectionError( + _max_retries( + _caused_by( + NameResolutionError( + "example.com", + _CONN, + socket.gaierror(socket.EAI_FAIL, "Non-recoverable"), + ), + socket.gaierror(socket.EAI_FAIL, "Non-recoverable"), + ) + ) + ), + "EAI_FAIL", + ), + ( + requests.exceptions.ConnectionError( + ProtocolError( + "Connection aborted.", + ConnectionResetError(errno.ECONNRESET, "reset by peer"), + ) + ), + "ECONNRESET", + ), + ( + requests.exceptions.ConnectionError( + ProtocolError( + "Connection aborted.", + http.client.RemoteDisconnected("closed without response"), + ) + ), + "ECONNRESET", + ), + ( + requests.exceptions.ConnectionError( + ProtocolError("Connection aborted.", http.client.BadStatusLine("SSH")) + ), + "EPROTO", + ), + ( + requests.exceptions.SSLError( + _max_retries(Urllib3SSLError(_cert_verify_error(20))) + ), + "X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY", + ), + ( + requests.exceptions.SSLError( + _max_retries(Urllib3SSLError(_cert_verify_error(10))) + ), + "X509_V_ERR_CERT_HAS_EXPIRED", + ), + ( + requests.exceptions.SSLError( + _max_retries(Urllib3SSLError(_cert_verify_error(62))) + ), + "X509_V_ERR_HOSTNAME_MISMATCH", + ), + ( + requests.exceptions.SSLError( + _max_retries(Urllib3SSLError(_cert_verify_error(24))) + ), + "X509_V_ERR_NO_ISSUER_PUBLIC_KEY", + ), + ( + requests.exceptions.SSLError( + _max_retries(Urllib3SSLError(_cert_verify_error(79))) + ), + "X509_V_ERR_INVALID_CA", + ), + ( + requests.exceptions.SSLError( + _max_retries(Urllib3SSLError(_cert_verify_error(-1))) + ), + "EPROTO", + ), + ( + requests.exceptions.SSLError( + _max_retries( + Urllib3SSLError(ssl.SSLError(1, "[SSL] wrong version number")) + ) + ), + "EPROTO", + ), + ( + requests.exceptions.ProxyError( + _max_retries( + Urllib3ProxyError( + "Unable to connect to proxy", + _caused_by( + NewConnectionError(_CONN, "Failed to establish"), + ConnectionRefusedError(errno.ECONNREFUSED, "refused"), + ), + ) + ) + ), + "ECONNREFUSED", + ), + ( + requests.exceptions.ProxyError( + _max_retries( + Urllib3ProxyError( + "Unable to connect to proxy", + _caused_by( + ConnectTimeoutError(_CONN, "Connection timed out"), + TimeoutError("timed out"), + ), + ) + ) + ), + "ETIMEDOUT", + ), + (requests.exceptions.ConnectTimeout("timed out"), "ETIMEDOUT"), + (requests.exceptions.ReadTimeout("timed out"), "ETIMEDOUT"), + (requests.exceptions.RequestException("unexpected"), None), + ], +) +def test_get_request_error_code__request_failed__returns_expected_code( + error: requests.RequestException, + expected_code: str | None, +) -> None: + # Given / When + code = get_request_error_code(error) + + # Then + assert code == expected_code diff --git a/api/tests/unit/webhooks/test_unit_webhooks.py b/api/tests/unit/webhooks/test_unit_webhooks.py index 411e629ea4fe..96b5c8dd2b53 100644 --- a/api/tests/unit/webhooks/test_unit_webhooks.py +++ b/api/tests/unit/webhooks/test_unit_webhooks.py @@ -1,3 +1,4 @@ +import errno import hashlib import hmac import json @@ -608,6 +609,43 @@ def test_send_test_webhook__request_exception__returns_error_response( } +def test_send_test_webhook__connection_refused__returns_error_code_without_details( + mocker: MockerFixture, + admin_client: APIClient, + organisation: Organisation, +) -> None: + # Given + mocker.patch( + "core.network.socket.getaddrinfo", + return_value=[(socket.AF_INET, None, None, None, ("93.184.216.34", 0))], + ) + refused = ConnectionRefusedError( + errno.ECONNREFUSED, "Connection refused by 10.1.2.3:7000" + ) + error = ConnectionError("HTTPSConnectionPool(host='example.com', port=7000)") + error.__cause__ = refused + mocker.patch("webhooks.webhooks.requests.post", side_effect=error) + + url = reverse("api-v1:webhooks:webhooks-test") + data = { + "webhook_url": "https://example.com:7000/hook", + "scope": {"type": "organisation", "id": organisation.id}, + } + + # When + response = admin_client.post( + url, data=json.dumps(data), content_type="application/json" + ) + + # Then + assert response.status_code == status.HTTP_400_BAD_REQUEST + assert response.json() == { + "detail": "Could not connect to webhook URL", + "body": "Please check the URL, and ensure it is valid and accessible from the server.", + "code": "ECONNREFUSED", + } + + def test_send_test_webhook__empty_webhook_url__returns_bad_request( admin_client: APIClient, organisation: Organisation, diff --git a/api/webhooks/serializers.py b/api/webhooks/serializers.py index ef8ee518a837..bf04c44c5cf0 100644 --- a/api/webhooks/serializers.py +++ b/api/webhooks/serializers.py @@ -29,5 +29,15 @@ class TestWebhookSuccessResponseSerializer(serializers.Serializer[None]): class TestWebhookErrorResponseSerializer(serializers.Serializer[None]): detail = serializers.CharField() - status = serializers.IntegerField() + status = serializers.IntegerField( + required=False, + help_text="HTTP status returned by the webhook, if it responded.", + ) body = serializers.CharField(required=False, allow_blank=True, allow_null=True) + code = serializers.CharField( + required=False, + help_text=( + "Why the webhook could not be reached, if known: a POSIX error " + "name, or an OpenSSL certificate verification error name." + ), + ) diff --git a/api/webhooks/views.py b/api/webhooks/views.py index bf467c467e90..b1ac3818b6e1 100644 --- a/api/webhooks/views.py +++ b/api/webhooks/views.py @@ -6,6 +6,7 @@ from rest_framework.request import Request from rest_framework.response import Response +from core.network import get_request_error_code from webhooks.webhooks import WebhookType from .permissions import TriggerSampleWebhookPermission @@ -63,11 +64,11 @@ def test(self, request: Request) -> Response: }, status=status.HTTP_200_OK, ) - except requests.exceptions.RequestException: - return Response( - { - "detail": "Could not connect to webhook URL", - "body": "Please check the URL, and ensure it is valid and accessible from the server.", - }, - status=status.HTTP_400_BAD_REQUEST, - ) + except requests.exceptions.RequestException as error: + error_data = { + "detail": "Could not connect to webhook URL", + "body": "Please check the URL, and ensure it is valid and accessible from the server.", + } + if code := get_request_error_code(error): + error_data["code"] = code + return Response(error_data, status=status.HTTP_400_BAD_REQUEST) diff --git a/openapi.yaml b/openapi.yaml index b2ca9cd8e1e5..9b7ff0a0d913 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -29065,14 +29065,17 @@ components: detail: type: string status: + description: 'HTTP status returned by the webhook, if it responded.' type: integer body: type: - string - 'null' + code: + description: 'Why the webhook could not be reached, if known: a POSIX error name, or an OpenSSL certificate verification error name.' + type: string required: - detail - - status TestWebhookSuccessResponse: type: object properties: