fix(webhook notif): Reorg docs, add 'ping'

[kiblik]

• Fix for Docs: Lost "notification webhooks" and broken "mermaid" #11627
• Add documentation page for ping
• Add test for ping

New menu items

[dryrunsecurity]

DryRun Security Summary

The GitHub Pull Request updates documentation for DefectDojo's experimental Notification Webhooks feature, providing details on webhook handling, event types, and potential security considerations for sending HTTP requests to external web servers.

Expand for full summary

Summary:

The provided GitHub Pull Request includes a series of documentation updates related to the "Notification Webhooks" feature in the DefectDojo application. This feature allows DefectDojo to send HTTP requests (webhooks) to a user-defined web server when certain events occur, such as the creation of new products, engagements, or test results.

From an application security perspective, the key points are:

1. Webhook Handling and Validation: The documentation includes details on how DefectDojo handles webhook delivery failures and validates incoming webhook requests. This includes features like temporary or permanent deactivation of webhook endpoints based on HTTP response codes, as well as the use of specific headers to identify the source and type of the webhook event.

2. Sensitive Data Exposure: The documentation examples include some potentially sensitive information, such as IDs, URLs, and titles of various entities within the application. It's important to ensure that in the actual application, any sensitive data is properly sanitized and access-controlled before being included in webhook payloads or other external communications.

3. Input Validation: While the documentation does not directly address input validation, it's crucial to ensure that any user-provided data in the webhook payloads is properly validated and sanitized to prevent potential injection attacks, such as cross-site scripting (XSS) or SQL injection.

4. Experimental Nature: The documentation clearly states that the Notification Webhooks feature is in an experimental stage, which means that the functionality may change in future releases. This is an important note for users to be aware of, as it sets the expectation that the feature may not be considered production-ready and may undergo further changes.

Files Changed:

1. docs/content/en/open_source/notification_webhooks/_index.md: This file provides a comprehensive overview of the Notification Webhooks feature, including a state transition diagram, headers, and information about the experimental nature of the functionality.

2. docs/content/en/open_source/notification_webhooks/ping.md: This file documents the "ping" event, which is used to test the webhook endpoint and ensure it is properly configured and secured.

3. docs/content/en/open_source/notification_webhooks/engagement_added.md: This file describes the "engagement_added" event, which includes sensitive information in the webhook payload that should be properly secured.

4. docs/content/en/open_source/notification_webhooks/how_to.md: This file provides a general overview of the webhooks functionality, including details on handling webhook failures and the experimental nature of the feature.

5. docs/content/en/open_source/notification_webhooks/test_added.md, docs/content/en/open_source/notification_webhooks/scan_added.md, docs/content/en/open_source/notification_webhooks/product_added.md, and docs/content/en/open_source/notification_webhooks/product_type_added.md: These files document the various webhook events, including the structure of the webhook payloads.

6. unittests/test_notifications.py: This file contains unit tests for the WebhookNotificationManager class, which is responsible for sending notifications to configured webhooks. The tests cover various security-related aspects, such as input validation, error handling, and webhook status management.

Code Analysis

We ran 9 analyzers against 9 files and 0 analyzers had findings. 9 analyzers had no findings.

View PR in the DryRun Dashboard.

[kiblik]

@paulOsinski, how do you see it? Is it good?

[kiblik]

@paulOsinski, in the end, fix of mermaid has not been that hard: 34ffd71

[paulOsinski]

Looks good to me! Thank you for fixing this.

[mtesauro]

Approved