DefectDojo DefectDojo | docs

Benachrichtigungs-Webhooks (Open Source)

Dies ist eine experimentelle Open-Source-Funktion — das Verhalten kann sich in künftigen Releases ändern.

Webhooks sind ausgehende HTTP-Anfragen, die von Ihrer DefectDojo-Instanz an einen benutzerdefinierten Server gesendet werden, sobald bestimmte Ereignisse eintreten.

Einrichtung

Webhook-Endpunkte werden von Administratoren konfiguriert. Wenn ein Webhook erstellt wird, sendet DefectDojo ein ping-Ereignis, um zu prüfen, ob der Endpunkt erreichbar ist und den erwarteten Statuscode zurückgibt.

Zustandsübergänge von Endpunkten

DefectDojo überwacht den Zustellerfolg und deaktiviert einen Endpunkt auf Basis von HTTP-Antworten oder Netzwerkfehlern vorübergehend oder dauerhaft. Eine manuelle Reaktivierung durch einen Administrator ist ebenfalls möglich.

  • Stadionförmige Zustände: Aktiv — Webhooks können gesendet werden
  • Rechteckige Zustände: Inaktiv — die Webhook-Zustellung schlägt fehl und wird nicht wiederholt
  • Übergänge ausgelöst durch: HTTP-Antworten des Zielservers, Celery-Automatisierung oder manuelle Administratoraktion

Anfrage-Header

Jede Webhook-Anfrage enthält die folgenden Header:

User-Agent: DefectDojo-<version>
X-DefectDojo-Event: <event_name>
X-DefectDojo-Instance: <base_url_of_dd_instance>

Ereignisse

product_type_added

Wird ausgelöst, wenn ein neuer Produkttyp erstellt wird.

Header:

X-DefectDojo-Event: product_type_added

Body:

{
    "description": "",
    "title": "",
    "product_type": {
        "id": 4,
        "name": "notif prod type",
        "url_api": "http://localhost:8080/api/v2/product_types/4/",
        "url_ui": "http://localhost:8080/product/type/4"
    },
    "url_api": "http://localhost:8080/api/v2/product_types/4/",
    "url_ui": "http://localhost:8080/product/type/4",
    "user": {
        "id": 1,
        "email": "admin@defectdojo.local",
        "first_name": "Admin",
        "last_name": "User",
        "username": "admin",
        "url_api": "http://localhost:8080/api/v2/users/1/",
        "url_ui": "http://localhost:8080/user/1"
    }
}

product_added

Wird ausgelöst, wenn ein neues Produkt erstellt wird.

Header:

X-DefectDojo-Event: product_added

Body:

{
    "description": "",
    "title": "",
    "product": {
        "id": 4,
        "name": "notif prod",
        "url_api": "http://localhost:8080/api/v2/products/4/",
        "url_ui": "http://localhost:8080/product/4"
    },
    "product_type": {
        "id": 4,
        "name": "notif prod type",
        "url_api": "http://localhost:8080/api/v2/product_types/4/",
        "url_ui": "http://localhost:8080/product/type/4"
    },
    "url_api": "http://localhost:8080/api/v2/products/4/",
    "url_ui": "http://localhost:8080/product/4",
    "user": {
        "id": 1,
        "email": "admin@defectdojo.local",
        "first_name": "Admin",
        "last_name": "User",
        "username": "admin",
        "url_api": "http://localhost:8080/api/v2/users/1/",
        "url_ui": "http://localhost:8080/user/1"
    }
}

engagement_added

Wird ausgelöst, wenn ein neues Engagement erstellt wird.

Header:

X-DefectDojo-Event: engagement_added

Body:

{
    "description": "",
    "title": "",
    "engagement": {
        "id": 7,
        "name": "notif eng",
        "url_api": "http://localhost:8080/api/v2/engagements/7/",
        "url_ui": "http://localhost:8080/engagement/7"
    },
    "product": {
        "id": 4,
        "name": "notif prod",
        "url_api": "http://localhost:8080/api/v2/products/4/",
        "url_ui": "http://localhost:8080/product/4"
    },
    "product_type": {
        "id": 4,
        "name": "notif prod type",
        "url_api": "http://localhost:8080/api/v2/product_types/4/",
        "url_ui": "http://localhost:8080/product/type/4"
    },
    "url_api": "http://localhost:8080/api/v2/engagements/7/",
    "url_ui": "http://localhost:8080/engagement/7",
    "user": {
        "id": 1,
        "email": "admin@defectdojo.local",
        "first_name": "Admin",
        "last_name": "User",
        "username": "admin",
        "url_api": "http://localhost:8080/api/v2/users/1/",
        "url_ui": "http://localhost:8080/user/1"
    }
}

test_added

Wird ausgelöst, wenn ein neuer Test erstellt wird.

Header:

X-DefectDojo-Event: test_added

Body:

{
    "description": "",
    "title": "",
    "engagement": {
        "id": 7,
        "name": "notif eng",
        "url_api": "http://localhost:8080/api/v2/engagements/7/",
        "url_ui": "http://localhost:8080/engagement/7"
    },
    "product": {
        "id": 4,
        "name": "notif prod",
        "url_api": "http://localhost:8080/api/v2/products/4/",
        "url_ui": "http://localhost:8080/product/4"
    },
    "product_type": {
        "id": 4,
        "name": "notif prod type",
        "url_api": "http://localhost:8080/api/v2/product_types/4/",
        "url_ui": "http://localhost:8080/product/type/4"
    },
    "test": {
        "id": 90,
        "title": "notif test",
        "url_api": "http://localhost:8080/api/v2/tests/90/",
        "url_ui": "http://localhost:8080/test/90"
    },
    "url_api": "http://localhost:8080/api/v2/tests/90/",
    "url_ui": "http://localhost:8080/test/90",
    "user": {
        "id": 1,
        "email": "admin@defectdojo.local",
        "first_name": "Admin",
        "last_name": "User",
        "username": "admin",
        "url_api": "http://localhost:8080/api/v2/users/1/",
        "url_ui": "http://localhost:8080/user/1"
    }
}

scan_added / scan_added_empty

Wird ausgelöst, wenn ein Scan importiert oder erneut importiert wird. scan_added_empty wird ausgelöst, wenn ein Reimport zu keinen Änderungen führt (keine Befunde erstellt oder geschlossen).

Header:

X-DefectDojo-Event: scan_added
X-DefectDojo-Event: scan_added_empty

Body:

{
    "description": "",
    "title": "",
    "engagement": {
        "id": 7,
        "name": "notif eng",
        "url_api": "http://localhost:8080/api/v2/engagements/7/",
        "url_ui": "http://localhost:8080/engagement/7"
    },
    "finding_count": 4,
    "findings": {
        "mitigated": [
            {
                "id": 233,
                "severity": "Medium",
                "title": "Mitigated Finding",
                "url_api": "http://localhost:8080/api/v2/findings/233/",
                "url_ui": "http://localhost:8080/finding/233"
            }
        ],
        "new": [
            {
                "id": 232,
                "severity": "Critical",
                "title": "New Finding",
                "url_api": "http://localhost:8080/api/v2/findings/232/",
                "url_ui": "http://localhost:8080/finding/232"
            }
        ],
        "reactivated": [
            {
                "id": 234,
                "severity": "Low",
                "title": "Reactivated Finding",
                "url_api": "http://localhost:8080/api/v2/findings/234/",
                "url_ui": "http://localhost:8080/finding/234"
            }
        ],
        "untouched": [
            {
                "id": 235,
                "severity": "Info",
                "title": "Untouched Finding",
                "url_api": "http://localhost:8080/api/v2/findings/235/",
                "url_ui": "http://localhost:8080/finding/235"
            }
        ]
    },
    "product": {
        "id": 4,
        "name": "notif prod",
        "url_api": "http://localhost:8080/api/v2/products/4/",
        "url_ui": "http://localhost:8080/product/4"
    },
    "product_type": {
        "id": 4,
        "name": "notif prod type",
        "url_api": "http://localhost:8080/api/v2/product_types/4/",
        "url_ui": "http://localhost:8080/product/type/4"
    },
    "test": {
        "id": 90,
        "title": "notif test",
        "url_api": "http://localhost:8080/api/v2/tests/90/",
        "url_ui": "http://localhost:8080/test/90"
    },
    "url_api": "http://localhost:8080/api/v2/tests/90/",
    "url_ui": "http://localhost:8080/test/90",
    "user": {
        "id": 1,
        "email": "admin@defectdojo.local",
        "first_name": "Admin",
        "last_name": "User",
        "username": "admin",
        "url_api": "http://localhost:8080/api/v2/users/1/",
        "url_ui": "http://localhost:8080/user/1"
    }
}

ping

Wird während der Webhook-Einrichtung gesendet, um zu prüfen, ob der Endpunkt erreichbar ist.

Header:

X-DefectDojo-Event: ping

Body:

{
    "description": "Test webhook notification",
    "title": "",
    "user": {
        "id": 1,
        "email": "admin@defectdojo.local",
        "first_name": "Admin",
        "last_name": "User",
        "username": "admin",
        "url_api": "http://localhost:8080/api/v2/users/1/",
        "url_ui": "http://localhost:8080/user/1"
    }
}

Roadmap

Bekannte geplante Verbesserungen:

  • SLA-bezogene Ereignisse (noch nicht unterstützt)
  • Benutzerdefinierte Webhooks (derzeit nur für Administratoren)
  • Verbesserte Oberfläche mit Filterung und Paginierung für Webhook-Endpunkte
Davor
Konfiguration