snapshot of https://github.com/zulip/zulip.git @ 48c69911c7dd4e03b20552eb3bd77ad8151c1357 (2026-09-15)

zerver/webhooks/harbor/doc.md

@@ -0,0 +1,32 @@
+# Zulip Harbor integration
+
+Get Zulip notifications for your [Harbor](https://goharbor.io/) projects!
+
+Harbor's webhooks feature is available in version 1.9 and later.
+
+{start_tabs}
+
+1. {!create-an-incoming-webhook.md!}
+
+1. {!generate-webhook-url-basic.md!}
+
+1. Go to your Harbor **Projects** page, open a project, and click on the
+   **Webhooks** tab.
+
+1. Set **Endpoint URL** to the URL generated above, and click on **Continue**.
+
+{end_tabs}
+
+{!congrats.md!}
+
+![](/static/images/integrations/harbor/001.png)
+
+{% if all_event_types is defined %}
+
+{!event-filtering-additional-feature.md!}
+
+{% endif %}
+
+### Related documentation
+
+{!webhooks-url-specification.md!}

zerver/webhooks/harbor/fixtures/delete_image.json

@@ -0,0 +1,21 @@
+{
+    "type": "DELETE_ARTIFACT",
+    "occur_at": 1571334977,
+    "event_data": {
+        "resources": [
+            {
+                "digest": "sha256:59856107563b1e1b2e48c8635e5cb44fa9b194f6a425e0b668917602213bb5b4",
+                "tag": "latest",
+                "resource_url": "harbor.example.com/example/test:latest"
+            }
+        ],
+        "repository": {
+            "date_created": 1571333978,
+            "name": "test",
+            "namespace": "example",
+            "repo_full_name": "example/test",
+            "repo_type": "private"
+        }
+    },
+    "operator": "admin"
+}

zerver/webhooks/harbor/fixtures/push_image.json

@@ -0,0 +1,21 @@
+{
+    "type": "PUSH_ARTIFACT",
+    "occur_at": 1571334632,
+    "event_data": {
+        "resources": [
+            {
+                "digest": "sha256:d72f37f783ed6a8d58ac70b4db052707d1ec9d4ea010ef5ccd84652faf9ed844",
+                "tag": "latest",
+                "resource_url": "harbor.example.com/example/test:latest"
+            }
+        ],
+        "repository": {
+            "date_created": 1571334632,
+            "name": "test",
+            "namespace": "example",
+            "repo_full_name": "example/test",
+            "repo_type": "private"
+        }
+    },
+    "operator": "admin"
+}

zerver/webhooks/harbor/fixtures/scanning_completed.json

@@ -0,0 +1,44 @@
+{
+    "type": "SCANNING_COMPLETED",
+    "occur_at": 1648715576,
+    "operator": "auto",
+    "event_data": {
+      "resources": [
+        {
+          "digest": "sha256:b50334049354ed01330403212605dce2f4676a4e787ed113506861d9cf3c5424",
+          "tag": "3.8.1",
+          "resource_url": "harbor.xxx.xxxx.com/test/alpine/helm:3.8.1",
+          "scan_overview": {
+            "application/vnd.security.vulnerability.report; version=1.1": {
+              "report_id": "65e8a295-749c-44e2-93fe-2ebb49b9e51a",
+              "scan_status": "Success",
+              "severity": "High",
+              "duration": 3,
+              "summary": {
+                "total": 5,
+                "fixable": 5,
+                "summary": {
+                  "High": 4,
+                  "Unknown": 1
+                }
+              },
+              "start_time": "2022-03-31T08:32:53Z",
+              "end_time": "2022-03-31T08:32:56Z",
+              "scanner": {
+                "name": "Trivy",
+                "vendor": "Aqua Security",
+                "version": "v0.20.1"
+              },
+              "complete_percent": 100
+            }
+          }
+        }
+      ],
+      "repository": {
+        "name": "alpine/helm",
+        "namespace": "test",
+        "repo_full_name": "test/alpine/helm",
+        "repo_type": "private"
+      }
+    }
+}

zerver/webhooks/harbor/fixtures/scanning_completed_no_tag.json

@@ -0,0 +1,43 @@
+{
+    "type": "SCANNING_COMPLETED",
+    "occur_at": 1648715576,
+    "operator": "auto",
+    "event_data": {
+      "resources": [
+        {
+          "digest": "sha256:b50334049354ed01330403212605dce2f4676a4e787ed113506861d9cf3c5424",
+          "resource_url": "harbor.xxx.xxxx.com/test/alpine/helm:3.8.1",
+            "scan_overview": {
+                "application/vnd.security.vulnerability.report; version=1.1": {
+                    "report_id": "65e8a295-749c-44e2-93fe-2ebb49b9e51a",
+                    "scan_status": "Success",
+                    "severity": "High",
+                    "duration": 3,
+                    "summary": {
+                        "total": 5,
+                        "fixable": 5,
+                        "summary": {
+                            "High": 4,
+                            "Unknown": 1
+                        }
+                    },
+                    "start_time": "2022-03-31T08:32:53Z",
+                    "end_time": "2022-03-31T08:32:56Z",
+                    "scanner": {
+                        "name": "Trivy",
+                        "vendor": "Aqua Security",
+                        "version": "v0.20.1"
+                    },
+                    "complete_percent": 100
+                }
+            }
+        }
+      ],
+      "repository": {
+        "name": "alpine/helm",
+        "namespace": "test",
+        "repo_full_name": "test/alpine/helm",
+        "repo_type": "private"
+      }
+    }
+}

zerver/webhooks/harbor/fixtures/scanning_completed_no_vulnerability.json

@@ -0,0 +1,41 @@
+{
+    "type": "SCANNING_COMPLETED",
+    "occur_at": 1655522951,
+    "operator": "auto",
+    "event_data": {
+        "resources": [
+            {
+                "digest": "sha256:59856107563b1e1b2e48c8635e5cb44fa9b194f6a425e0b668917602213bb5b4",
+                "tag": "latest",
+                "resource_url": "demo.goharbor.io/test123/test-image:latest",
+                "scan_overview": {
+                    "application/vnd.security.vulnerability.report; version=1.1": {
+                        "report_id": "f316b072-38e4-41b1-a1da-91ec0b2e7767",
+                        "scan_status": "Success",
+                        "severity": "None",
+                        "duration": 8,
+                        "summary": {
+                            "total": 0,
+                            "fixable": 0,
+                            "summary": {}
+                        },
+                        "start_time": "2022-06-18T03:29:03Z",
+                        "end_time": "2022-06-18T03:29:11Z",
+                        "scanner": {
+                            "name": "Trivy",
+                            "vendor": "Aqua Security",
+                            "version": "v0.24.2"
+                        },
+                        "complete_percent": 100
+                    }
+                }
+            }
+        ],
+        "repository": {
+            "name": "test-image",
+            "namespace": "test123",
+            "repo_full_name": "test123/test-image",
+            "repo_type": "public"
+        }
+    }
+}

zerver/webhooks/harbor/tests.py

@@ -0,0 +1,55 @@
+from unittest.mock import MagicMock, patch
+
+from zerver.lib.test_classes import WebhookTestCase
+
+
+class HarborHookTests(WebhookTestCase):
+    def test_push_image(self) -> None:
+        expected_topic_name = "example/test"
+        expected_message = """**admin** pushed image `example/test:latest`."""
+        self.check_webhook("push_image", expected_topic_name, expected_message)
+
+    @patch("zerver.lib.webhooks.common.check_send_webhook_message")
+    def test_delete_image_ignored(self, check_send_webhook_message_mock: MagicMock) -> None:
+        self.url = self.build_webhook_url()
+        payload = self.get_body("delete_image")
+        result = self.client_post(self.url, payload, content_type="application/json")
+        self.assertFalse(check_send_webhook_message_mock.called)
+        self.assert_json_success(result)
+
+    def test_scanning_completed(self) -> None:
+        expected_topic_name = "test/alpine/helm"
+
+        expected_message = """
+Image scan completed for `test/alpine/helm:3.8.1`. Vulnerabilities by severity:
+
+* High: **4**
+* Unknown: **1**
+        """.strip()
+
+        self.check_webhook("scanning_completed", expected_topic_name, expected_message)
+
+    def test_scanning_completed_no_vulnerability(self) -> None:
+        expected_topic_name = "test123/test-image"
+
+        expected_message = """
+Image scan completed for `test123/test-image:latest`. Vulnerabilities by severity:
+
+None
+        """.strip()
+
+        self.check_webhook(
+            "scanning_completed_no_vulnerability", expected_topic_name, expected_message
+        )
+
+    def test_scanning_completed_no_tag(self) -> None:
+        expected_topic_name = "test/alpine/helm"
+
+        expected_message = """
+Image scan completed for `test/alpine/helm@sha256:b50334049354ed01330403212605dce2f4676a4e787ed113506861d9cf3c5424`. Vulnerabilities by severity:
+
+* High: **4**
+* Unknown: **1**
+        """.strip()
+
+        self.check_webhook("scanning_completed_no_tag", expected_topic_name, expected_message)

zerver/webhooks/harbor/view.py

@@ -0,0 +1,132 @@
+# Webhooks for external integrations.
+
+from django.db.models import Q
+from django.http import HttpRequest, HttpResponse
+
+from zerver.decorator import webhook_view
+from zerver.lib.exceptions import UnsupportedWebhookEventTypeError
+from zerver.lib.response import json_success
+from zerver.lib.typed_endpoint import JsonBodyPayload, typed_endpoint
+from zerver.lib.validator import WildValue, check_int, check_string
+from zerver.lib.webhooks.common import check_send_webhook_message
+from zerver.models import Realm, UserProfile
+
+IGNORED_EVENTS = [
+    "DOWNLOAD_CHART",
+    "DELETE_CHART",
+    "UPLOAD_CHART",
+    "PULL_ARTIFACT",
+    "DELETE_ARTIFACT",
+    "SCANNING_FAILED",
+]
+
+
+def guess_zulip_user_from_harbor(harbor_username: str, realm: Realm) -> UserProfile | None:
+    try:
+        # Try to find a matching user in Zulip
+        # We search a user's full name, short name,
+        # and beginning of email address
+        user = UserProfile.objects.filter(
+            Q(full_name__iexact=harbor_username) | Q(email__istartswith=harbor_username),
+            is_active=True,
+            realm=realm,
+        ).order_by("id")[0]
+        return user  # nocoverage
+    except IndexError:
+        return None
+
+
+def image_id(payload: WildValue) -> str:
+    image_name = payload["event_data"]["repository"]["repo_full_name"].tame(check_string)
+    resource = payload["event_data"]["resources"][0]
+    if "tag" in resource:
+        return image_name + ":" + resource["tag"].tame(check_string)
+    else:
+        return image_name + "@" + resource["digest"].tame(check_string)
+
+
+IMAGE_PUSHED_TEMPLATE_WITH_OPERATOR = "{operator} pushed image `{image_id}`."
+IMAGE_PUSHED_TEMPLATE = "Image `{image_id}` was pushed."
+
+
+def handle_push_image_event(payload: WildValue, operator_username: str | None = None) -> str:
+    if operator_username:
+        return IMAGE_PUSHED_TEMPLATE_WITH_OPERATOR.format(
+            operator=operator_username,
+            image_id=image_id(payload),
+        )
+    return IMAGE_PUSHED_TEMPLATE.format(image_id=image_id(payload))  # nocoverage
+
+
+SCANNING_COMPLETED_TEMPLATE = """
+Image scan completed for `{image_id}`. Vulnerabilities by severity:
+
+{scan_results}
+""".strip()
+
+
+def handle_scanning_completed_event(
+    payload: WildValue, operator_username: str | None = None
+) -> str:
+    scan_results = ""
+    scan_overview = payload["event_data"]["resources"][0]["scan_overview"]
+    if "application/vnd.security.vulnerability.report; version=1.1" not in scan_overview:
+        raise UnsupportedWebhookEventTypeError(str(list(scan_overview.keys())))
+    scan_summaries = scan_overview["application/vnd.security.vulnerability.report; version=1.1"][
+        "summary"
+    ]["summary"]
+    if len(scan_summaries) > 0:
+        for severity, count in scan_summaries.items():
+            scan_results += f"* {severity}: **{count.tame(check_int)}**\n"
+    else:
+        scan_results += "None\n"
+
+    return SCANNING_COMPLETED_TEMPLATE.format(
+        image_id=image_id(payload),
+        scan_results=scan_results,
+    )
+
+
+EVENT_FUNCTION_MAPPER = {
+    "PUSH_ARTIFACT": handle_push_image_event,
+    "SCANNING_COMPLETED": handle_scanning_completed_event,
+}
+
+ALL_EVENT_TYPES = list(EVENT_FUNCTION_MAPPER.keys())
+
+
+@webhook_view("Harbor", all_event_types=ALL_EVENT_TYPES)
+@typed_endpoint
+def api_harbor_webhook(
+    request: HttpRequest,
+    user_profile: UserProfile,
+    *,
+    payload: JsonBodyPayload[WildValue],
+) -> HttpResponse:
+    event = payload["type"].tame(check_string)
+    topic_name = payload["event_data"]["repository"]["repo_full_name"].tame(check_string)
+
+    if event in IGNORED_EVENTS:
+        return json_success(request)
+
+    content_func = EVENT_FUNCTION_MAPPER.get(event)
+
+    if content_func is None:
+        raise UnsupportedWebhookEventTypeError(event)
+
+    operator = payload["operator"].tame(check_string)
+    if operator != "auto":
+        operator_profile = guess_zulip_user_from_harbor(operator, user_profile.realm)
+        if operator_profile:
+            operator_username = f"@**{operator_profile.full_name}**"  # nocoverage
+        else:
+            operator_username = f"**{operator}**"
+    else:
+        operator_username = None
+
+    content: str = content_func(payload, operator_username)
+
+    check_send_webhook_message(
+        request, user_profile, topic_name, content, event, unquote_url_parameters=True
+    )
+    return json_success(request)