diff --git a/docs/assets/images/DD-Hierarchy.drawio b/docs/assets/images/DD-Hierarchy.drawio deleted file mode 100644 index 319195b2ce9..00000000000 --- a/docs/assets/images/DD-Hierarchy.drawio +++ /dev/null @@ -1 +0,0 @@ -7Z1tc5s4EIB/jT86AxJv/lgndjtzc5N20us1HzHImAtGHODEuV9/CCSD19imrnlzmOlMLSEtaPVIrHYlMsL36+3n0AxWf1KbeCMk2dsRfhghJCsIjdg/yX7PcgwNZxlO6Nq8UJ7x5P5HeKbEczeuTaK9gjGlXuwG+5kW9X1ixXt5ZhjSt/1iS+rt3zUwHXKQ8WSZ3mHu364dr3iurE3yC1+I66z4rQ2kZxfWpijMWxKtTJu+FbLwbITvQ0rj7Nd6e088pjyhl6ze/MjV3YOFxI9LKvwVkfBx8Q/TCZI8c5H0S1pohDQvKT9dUp9dsc3YHLPf4yi00hLavxv2SNNVHDMdf2IS0ZwVie4cSh2PmIEb3Vl0nWRbUVJkvjTXrsc6+DEg/ghNn0w/ygWxtsfvXKEiM7tl2t3JHSRZC7Zp0byS5rD/v4bU3qRt+P4eEPHw/IFEoUwVnuu/ZG1cmJFrJU8wXzMeo7QFOMgkjeNUDiqoEj/+8ay/zL4FDz++Pfyg0+njeDOWd120U33eChTSjW8TVl9O7v+2cmPyFJgWu/qWDIRUfWuPX2aPysmWNZ6eC5V9Id4riV3LFAX5TSSWdj3vnno0TG+KbZMYy6STplEc0hdSuKJZBlksd5p4JWFMtkc5KTbtM6FrEofvSRFeQZU4sHzEKjz5VsBfML0qkK/xPJOPOGcnOYeSdUmmTZEsYFrOeWnn8Enl1fQ2pN9Yn+C5bdyIbKtEL8NtounY1K6Dm6zt47ZL18BbNbjwANetwGUoXYNL6RNcB2TNfCexd9bE7zZcCVqGrZTBZaAF1mqauZDRNlzqANetwAVnrvbh0ga4bgUurXNw6b2G6zuJuo3VcrlEVunK0dYWmlrTC1GR2sbKGLDqP1YYdQ0r4ZwcuOozV4rROa7kgav+cwWtqw5w1St/6cBVtSVhB7jq95pw7vq26zvdRsuwSDlaC0NVVKmeV6GK2kYLlZlYoEOcpEeCU7o9qhkeLTYXQpT0u2udUo0pJRozahuMvYpbfOjBeIL4Q+Dam937HasYgDoClBADQmNtz/hyv6MXA26ncQNOnPYNjLK1docMDOj1at/AEAoaBmhPB+gR4NobgoPFepNAddTAQIM9e8u4dc7AKLNnO2RgQHdiBwyMwZ3Y7wGqds3A6Pe2kgGoI0B11cDo93aTAbfTuHXOwJicNzCIb39ip+CSlE99ctgpxzuh0Ftk68Y/WYfcqTz1zEWw3w9b3ldp4l0k/KSNhUos+Vy8lldLU6JejlV6zXaIwIGG8Yo61De9WZ7Lu5uVO9rZPCuim9AiJxQqzheaoUNOcnL2NaeWcCDyQuKZsfu6/7hlcPA7fKVuOneI3QUgVIdVwFfWTF4rR+xAkI6BIAkIyvRwIChlddfs3zhmUyHCN+BbA764TXxVHby05QvxRQBfWW8Y3wr+4yvhewRFubsoKn2YSW8HxTLHfK9RLJ+xpZMz9hXxVfswk0Lq0ORK+O7STeFbFgYY8L0cX60Psy9SzpiflfGFh5mUhvEtCysM+F6Or14RX6VVfFWA78XGAxCE4HqubnwrhCkGfH8BX6MX+ILtq7vdJr+MLzwED91ddeNbFjO6FXwNXAB4LN1Jsn7aaZEkvpLQTZRKwuuTLaa4jqMNlnUYmrOV0QaCUNPLurLoVS1oNzHDXjp8rslvVQ+Z1iq/0MEL7dnKDl7pzECom9+ycNitTM1tWBbiGN9Zfs/H4evkdwKwuzRAAQUdODjq5re5+NoH4beqY0I+fxSmRoAxnDehSVsV4ANBDUfYxItjMCCuBDCqDHCrrjUMNsZgaLhWBXgCPwXa8OJOubkYW8szsNDfWYCNVvkFO20w3HFaeQKGgqCXo25+0cDvdS0IXJFfvVV+4c6aSyNzB4IaXsEp/T6gM/PtIFNNl3c0Lol25Nsh+mQhXekDDzJwKmg1ftW7Ilv9Pu47sHX04yEdYOuWgwJtvHeVqjti5FZdpyqIpaqXuv6hIKVh17/SmOv/owBc1XCUW/WdqvCrQpf6/qEgBS6h6ga4Md//rYKIWg2iwr2x6qVOfChIuZoTP0nmfzwpK57/CSo8+x8= \ No newline at end of file diff --git a/docs/assets/images/How-To_Add,_Edit_or_Delete_Dashboard_Tiles_3.png b/docs/assets/images/How-To_Add,_Edit_or_Delete_Dashboard_Tiles_3.png index d75da933423..4716adeabde 100644 Binary files a/docs/assets/images/How-To_Add,_Edit_or_Delete_Dashboard_Tiles_3.png and b/docs/assets/images/How-To_Add,_Edit_or_Delete_Dashboard_Tiles_3.png differ diff --git a/docs/assets/images/dd-hierarchy.png b/docs/assets/images/dd-hierarchy.png new file mode 100644 index 00000000000..8d16a495c63 Binary files /dev/null and b/docs/assets/images/dd-hierarchy.png differ diff --git a/docs/assets/images/jira-instance-beta.png b/docs/assets/images/jira-instance-beta.png new file mode 100644 index 00000000000..1f45e28360d Binary files /dev/null and b/docs/assets/images/jira-instance-beta.png differ diff --git a/docs/assets/images/jira-project-settings.png b/docs/assets/images/jira-project-settings.png new file mode 100644 index 00000000000..96829e5d91a Binary files /dev/null and b/docs/assets/images/jira-project-settings.png differ diff --git a/docs/assets/images/notifs_email.png b/docs/assets/images/notifs_email.png new file mode 100644 index 00000000000..9fa61dab3dc Binary files /dev/null and b/docs/assets/images/notifs_email.png differ diff --git a/docs/assets/svgs/DD-Hierarchy.svg b/docs/assets/svgs/DD-Hierarchy.svg deleted file mode 100644 index fccd8b83dc7..00000000000 --- a/docs/assets/svgs/DD-Hierarchy.svg +++ /dev/null @@ -1,3 +0,0 @@ - - -
Product Type
Product Type
Product
Product
Product
Product
Engagement
Engagement
Engagement
Engagement
Engagement
Engagement
Test
Test
Test
Test
Test
Test
Test
Test
Test
Test
Finding
Finding
Finding
Finding
Finding
Finding
Finding
Finding
Finding
Finding
Finding
Finding
Finding
Finding
Finding
Finding
Finding
Finding
Finding
Finding
Endpoint
Endpoint
Endpoint
EndpointViewer does not support full SVG 1.1 \ No newline at end of file diff --git a/docs/content/en/api/_index.md b/docs/content/en/api/_index.md index 6f2f1ec4681..55da37c635c 100644 --- a/docs/content/en/api/_index.md +++ b/docs/content/en/api/_index.md @@ -1,5 +1,5 @@ --- -title: "API Documentation" +title: "🤖 API Documentation" description: "" summary: "" date: 2023-09-07T16:06:50+02:00 diff --git a/docs/content/en/changelog/_index.md b/docs/content/en/changelog/_index.md index 28d6d19457e..25da3f534d1 100644 --- a/docs/content/en/changelog/_index.md +++ b/docs/content/en/changelog/_index.md @@ -1,5 +1,5 @@ --- -title: "Changelog" +title: "📝 Changelog" description: "" summary: "" date: 2023-09-07T16:06:50+02:00 diff --git a/docs/content/en/cloud_management/_index.md b/docs/content/en/cloud_management/_index.md index 20cc6567008..81f358448ae 100644 --- a/docs/content/en/cloud_management/_index.md +++ b/docs/content/en/cloud_management/_index.md @@ -1,11 +1,11 @@ --- -title: "DefectDojo Cloud Manager" +title: "☁️ DefectDojo Cloud" description: "Manage Your DefectDojo subscription" summary: "" date: 2023-09-07T16:06:50+02:00 lastmod: 2023-09-07T16:06:50+02:00 draft: false -weight: 2 +weight: 6 chapter: true seo: title: "" # custom title (optional) diff --git a/docs/content/en/cloud_management/additional-cloud-instance.md b/docs/content/en/cloud_management/additional-cloud-instance.md index 2b65fd873fe..df9d5785564 100644 --- a/docs/content/en/cloud_management/additional-cloud-instance.md +++ b/docs/content/en/cloud_management/additional-cloud-instance.md @@ -1,6 +1,7 @@ --- title: "Set up an additional Cloud instance" description: "Add a test, dev, or other DefectDojo instance to your account" +weight: 2 --- The process for adding a second Cloud instance is more or less the same as adding your first instance. This guide assumes you've already set up your initial DefectDojo server, and have an agreement with our Sales team to add another instance. diff --git a/docs/content/en/cloud_management/connectivity-troubleshooting.md b/docs/content/en/cloud_management/connectivity-troubleshooting.md index 482ae7d801e..03d423785e4 100644 --- a/docs/content/en/cloud_management/connectivity-troubleshooting.md +++ b/docs/content/en/cloud_management/connectivity-troubleshooting.md @@ -1,6 +1,7 @@ --- title: "Connectivity Troubleshooting" description: "Reconnect to your DefectDojo Instance" +weight: 2 --- If you have difficulty accessing your DefectDojo instance, here are some steps you can follow to get reconnected: diff --git a/docs/content/en/cloud_management/using-cloud-manager.md b/docs/content/en/cloud_management/using-cloud-manager.md index 671aa8958f9..3e93dd775a0 100644 --- a/docs/content/en/cloud_management/using-cloud-manager.md +++ b/docs/content/en/cloud_management/using-cloud-manager.md @@ -1,6 +1,7 @@ --- title: "Using the Cloud Manager" description: "Manage your subscription and account settings" +weight: 1 --- Logging into DefectDojo's Cloud Manager allows you to configure your account settings and manage your subscription with DefectDojo Cloud. diff --git a/docs/content/en/connecting_your_tools/_index.md b/docs/content/en/connecting_your_tools/_index.md index 3a39ea26559..fe64c7f7601 100644 --- a/docs/content/en/connecting_your_tools/_index.md +++ b/docs/content/en/connecting_your_tools/_index.md @@ -1,5 +1,5 @@ --- -title: "Connect Your Tools" +title: "🛠️ Connect Your Tools" description: "Import data from 190+ different security tools (and counting)" summary: "" date: 2023-09-07T16:06:50+02:00 diff --git a/docs/content/en/connecting_your_tools/connectors/_index.md b/docs/content/en/connecting_your_tools/connectors/_index.md index b4f5ad643e0..af3a11ca40f 100644 --- a/docs/content/en/connecting_your_tools/connectors/_index.md +++ b/docs/content/en/connecting_your_tools/connectors/_index.md @@ -5,7 +5,7 @@ summary: "" date: 2023-09-07T16:06:50+02:00 lastmod: 2023-09-07T16:06:50+02:00 draft: false -weight: 3 +weight: 4 chapter: true sidebar: collapsed: true diff --git a/docs/content/en/connecting_your_tools/import_intro.md b/docs/content/en/connecting_your_tools/import_intro.md index 4b1480f6bc9..3e7a0e706d9 100644 --- a/docs/content/en/connecting_your_tools/import_intro.md +++ b/docs/content/en/connecting_your_tools/import_intro.md @@ -1,5 +1,5 @@ --- -title: "Import Methods" +title: "Import Method Comparison" description: "Learn how to import data manually, through the API, or via a connector" weight: 1 --- diff --git a/docs/content/en/connecting_your_tools/import_scan_files/_index.md b/docs/content/en/connecting_your_tools/import_scan_files/_index.md index 44f08532b34..c1547dfb3bb 100644 --- a/docs/content/en/connecting_your_tools/import_scan_files/_index.md +++ b/docs/content/en/connecting_your_tools/import_scan_files/_index.md @@ -1,11 +1,11 @@ --- -title: "Import Scans" +title: "How To Import Data" description: "Use DefectDojo's Import / Reimport to ingest data and build a pipeline" summary: "" date: 2023-09-07T16:06:50+02:00 lastmod: 2023-09-07T16:06:50+02:00 draft: false -weight: 2 +weight: 3 chapter: true sidebar: collapsed: true diff --git a/docs/content/en/connecting_your_tools/parsers/_index.md b/docs/content/en/connecting_your_tools/parsers/_index.md index e5f2e8fb543..74f9cab299f 100644 --- a/docs/content/en/connecting_your_tools/parsers/_index.md +++ b/docs/content/en/connecting_your_tools/parsers/_index.md @@ -1,5 +1,5 @@ --- -title: "Supported Reports" +title: "Supported Report Types" description: "DefectDojo has the ability to import scan reports from a large number of security tools." draft: false weight: 5 diff --git a/docs/content/en/connecting_your_tools/parsers/api/_index.md b/docs/content/en/connecting_your_tools/parsers/api/_index.md index 1d1e5a3e09d..5a4024b84ea 100644 --- a/docs/content/en/connecting_your_tools/parsers/api/_index.md +++ b/docs/content/en/connecting_your_tools/parsers/api/_index.md @@ -1,7 +1,7 @@ --- title: "API Pull" description: "Report pulled to DefectDojo via API exposed by scanning service" -weight: 2 +weight: 3 chapter: true sidebar: collapsed: true diff --git a/docs/content/en/connecting_your_tools/parsers/file/_index.md b/docs/content/en/connecting_your_tools/parsers/file/_index.md index 29b8448a859..aa4efce21cf 100644 --- a/docs/content/en/connecting_your_tools/parsers/file/_index.md +++ b/docs/content/en/connecting_your_tools/parsers/file/_index.md @@ -1,7 +1,7 @@ --- title: "Files" description: "Report uploaded to DefectDojo as files" -weight: 1 +weight: 2 chapter: true sidebar: collapsed: true diff --git a/docs/content/en/connecting_your_tools/parsers/generic_findings_import.md b/docs/content/en/connecting_your_tools/parsers/generic_findings_import.md index a4395118e0e..9cb0bf48880 100644 --- a/docs/content/en/connecting_your_tools/parsers/generic_findings_import.md +++ b/docs/content/en/connecting_your_tools/parsers/generic_findings_import.md @@ -1,6 +1,7 @@ --- title: "Generic Findings Import" toc_hide: true +weight: 1 --- You can use Generic Findings Import as a method to ingest JSON or CSV files into DefectDojo which are not already in the supported parsers list. diff --git a/docs/content/en/customize_dojo/_index.md b/docs/content/en/customize_dojo/_index.md new file mode 100644 index 00000000000..c25e6267f31 --- /dev/null +++ b/docs/content/en/customize_dojo/_index.md @@ -0,0 +1,15 @@ +--- +title: "👥 Management & Customization" +description: "Dashboards, User Access" +summary: "" +date: 2023-09-07T16:06:50+02:00 +lastmod: 2023-09-07T16:06:50+02:00 +draft: false +weight: 5 +chapter: true +seo: + title: "" # custom title (optional) + description: "" # custom description (recommended) + canonical: "" # custom canonical URL (optional) + robots: "" # custom robot tags (optional) +--- \ No newline at end of file diff --git a/docs/content/en/dashboard/Introduction_dashboard.md b/docs/content/en/customize_dojo/dashboard_notifications/Introduction_dashboard.md similarity index 64% rename from docs/content/en/dashboard/Introduction_dashboard.md rename to docs/content/en/customize_dojo/dashboard_notifications/Introduction_dashboard.md index 422f012e4fa..dd864ec130a 100644 --- a/docs/content/en/dashboard/Introduction_dashboard.md +++ b/docs/content/en/customize_dojo/dashboard_notifications/Introduction_dashboard.md @@ -1,19 +1,21 @@ --- -title: "Introduction to Dashboard Features" +title: "DefectDojo Main Dashboard" description: "Working with the front page of DefectDojo" +weight: 1 --- The Dashboard is likely the first page you'll see when you open DefectDojo. It summarizes your team’s performance, and provides tracking tools to monitor specific areas of your vulnerability tracking environment. ![image](images/Introduction_to_Dashboard_Features.png) -The dashboard has two components: + +## Dashboard Components * **Customizable Dashboard Tiles**, which you can use to visualize the metrics which are relevant to you. * **Pre\-built Dashboard Charts**, which visualize your team’s overall performance. Each team member shares a single dashboard, but the results of the dashboard are restricted by their role and Product Membership. Team members will only see calculated stats for the Products, Engagements, Findings or other objects that they have access to. For more information, see our guides on [User Permissions and Roles](https://docs.defectdojo.com/en/user_management/about-permissions--roles/). -# Dashboard Tiles +### Dashboard Tiles Tiles are designed to provide relevant information and speed up navigation within DefectDojo. @@ -27,12 +29,9 @@ Tiles can: Tiles are pinned to the top section of your **🏠 Home** page. -For more information about creating and editing Dashboard Tiles, see our guides on this topic**:** - -* [Dashboard Tile Summary](https://docs.defectdojo.com/en/dashboard/about_custom_dashboard_tiles/) -* [Add, Edit or Delete Dashboard Tiles](https://docs.defectdojo.com/en/dashboard/add_edit_delete_dashboard_tiles/) +To learn how to add and use dashboard tiles, see our [guide](../about_custom_dashboard_tiles). -## Dashboard Charts +### Dashboard Charts Located beneath Dashboard Tiles, DefectDojo has five pre\-built charts: @@ -44,25 +43,25 @@ Located beneath Dashboard Tiles, DefectDojo has five pre\-built charts: These charts can be added or removed from the dashboard via **[Dashboard Configuration](https://docs.defectdojo.com/en/dashboard/how-to-edit-dashboard-configuration/)**. -### Historical Finding Severity +#### Historical Finding Severity This chart organizes all Findings created in DefectDojo by Severity, so that you can see the overall distribution of vulnerability levels in your environment. ![image](images/Introduction_to_Dashboard_Features_3.png) -### Reported Finding Severity +#### Reported Finding Severity This chart allows you to monitor the volume and severity distribution of incoming Findings per month. ![image](images/Introduction_to_Dashboard_Features_4.png) -### Unassigned Answered Engagement Questionnaires +#### Unassigned Answered Engagement Questionnaires If you have completed Engagement Questionnaires for review, those will be listed in this table. ![image](images/Introduction_to_Dashboard_Features_5.png) -### Top 10 / Bottom 10 Graded Products +#### Top 10 / Bottom 10 Graded Products This section summarizes the Graded performance of each Product in your instance, counting the Highest and Lowest scoring Products. @@ -70,9 +69,27 @@ This section summarizes the Graded performance of each Product in your instance, Finding Counts of each severity are calculated by the tile, but note that Product Grade is only assigned based on Active Findings, so there may be Inactive Findings counted in this table which do not contribute to the Grade. -To understand how grades are calculated, see our guide to **[Product Health Grading](https://docs.defectdojo.com/en/working_with_findings/organizing_engagements_tests/product-health-grade/)**. +To understand how grades are calculated, see our guide to **[Product Health Grading](/en/working_with_findings/organizing_engagements_tests/product-health-grade/)**. + +## Dashboard Configuration + +Superusers can choose which Metrics Charts are displayed on the Dashboard. To do this, select the **Edit Dashboard Configuration** option from the top\-right hand gear menu. + +![image](images/How-To_Edit_Dashboard_Configuration.png) +This will open the **Dashboard Configuration Settings** window. + +### Configuration Settings + +![image](images/How-To_Edit_Dashboard_Configuration_2.png) + +* **Display Graphs** determines whether or not the **Historical Finding Severity** and **Reported Finding Severity** charts are visible. +* **Display Surveys determines whether or not the Unassigned Answered Engagement Questionnaires table is visible.** +* **Display Data Tables determines whether or not the Top 10 / Bottom 10 Graded Products tables are visible.** + +### Reset Dashboard Configuration + +If you would like to reset your Dashboard to a default state, you can do so by selecting **Reset Dashboard Configuration** from the top\-right hand gear menu. -# Next Steps +![image](images/How-To_Edit_Dashboard_Configuration_3.png) -* Change or reset your dashboard display by **[editing your dashboard configuration](https://docs.defectdojo.com/en/dashboard/how-to-edit-dashboard-configuration/)**. -* Learn how to customize your DefectDojo instance with **[custom Dashboard Tiles](https://docs.defectdojo.com/en/dashboard/about-custom-dashboard-tiles/)**. +**Note that this will remove any Custom Dashboard Tiles which have been added to your instance.** diff --git a/docs/content/en/dashboard/_index.md b/docs/content/en/customize_dojo/dashboard_notifications/_index.md similarity index 92% rename from docs/content/en/dashboard/_index.md rename to docs/content/en/customize_dojo/dashboard_notifications/_index.md index bf596fc0d84..772b10489a4 100644 --- a/docs/content/en/dashboard/_index.md +++ b/docs/content/en/customize_dojo/dashboard_notifications/_index.md @@ -1,5 +1,5 @@ --- -title: "Set Up Your Dashboard" +title: "Dashboards" summary: "" date: 2023-09-07T16:06:50+02:00 lastmod: 2023-09-07T16:06:50+02:00 diff --git a/docs/content/en/dashboard/add_edit_delete_dashboard_tiles.md b/docs/content/en/customize_dojo/dashboard_notifications/about_custom_dashboard_tiles.md similarity index 52% rename from docs/content/en/dashboard/add_edit_delete_dashboard_tiles.md rename to docs/content/en/customize_dojo/dashboard_notifications/about_custom_dashboard_tiles.md index c6b2a86e713..3994461a718 100644 --- a/docs/content/en/dashboard/add_edit_delete_dashboard_tiles.md +++ b/docs/content/en/customize_dojo/dashboard_notifications/about_custom_dashboard_tiles.md @@ -1,35 +1,61 @@ --- -title: "How-To: Add, Edit or Delete Dashboard Tiles" -description: "Set up custom filters to track your work" +title: "Custom Dashboard Tiles" +description: "How to make Dashboard Tiles work for you, with examples" +weight: 2 --- -Custom Dashboard Tiles can be added, edited or deleted by any user with **Superuser** Permissions. +Dashboard Tiles are customizable sets of filters for your DefectDojo instance, which can be added to your 🏠 **Home** dashboard. Tiles are designed to provide relevant information and speed up navigation within DefectDojo. + +![image](images/About_Custom_Dashboard_Tiles.png) + +Tiles can: + +* Act as shortcuts for particular sets of Findings, Products, or other objects +* Visualize relevant metrics related a Product, Engagement or other components of the [Product Hierarchy](/en/working_with_findings/organizing_engagements_tests/product_hierarchy/) +* Provide alerts on particular activity, track SLA Violations, failing imports or new Critical Findings + +Tile Filters set a narrower focus for any tile you want to create. Each Tile has a different set of relevant filters which can be selected. + +Note that only Superusers can add or edit Dashboard Tiles. + +## Tile Components + +Each Tile contains four main components: -## Adding a new Dashboard Tile +![image](images/About_Custom_Dashboard_Tiles_2.png) -New Dashboard tiles can be added by opening the **\+** (plus icon)menu on the Dashboard. New Dashboard tiles will always be created at the bottom of the Dashboard Tiles section. +2. **A count of each object** that meets the Tile’s filter conditions. For example, a Findings Tile will count the number of Findings filtered by the Tile. +3. **A customizable Header** which can be set to describe the function of the tile. +4. **A customizable Footer** which brings you to the related list of objects. For example, a Findings Tile’s footer will bring you to a list of Findings filtered by the Tile. + +## Add / Edit Dashboard Tiles + +Custom Dashboard Tiles can be added, edited or deleted by any user with **Superuser** Permissions. + +New Dashboard tiles can be added by opening the **+** (plus icon) menu on the Dashboard. New Dashboard tiles will always be created at the bottom of the Dashboard Tiles section. ![image](images/How-To_Add,_Edit_or_Delete_Dashboard_Tiles.png) Select the kind of Tile you want to add, which will then bring you to the Add Dashboard Tile form. -### Editing a Dashboard Tile +If you wish to **edit** a Dashboard Tile, you can click the Header of the Tile, which will also open the Dashboard Tile form. -If you wish to edit a Dashboard Tile, you can click the Header of the Tile, which will also open the Dashboard Tile form. - -## Add / Edit Dashboard Tile form +### Display Options From here you can set your Dashboard Tile’s options: ![image](images/How-To_Add,_Edit_or_Delete_Dashboard_Tiles_2.png) -* Set the **Header** textfor your tile **(3\)** -* Set the **Footer** textfor your tile -* Set the **Color** of your icon +* Set the **Header** text for your tile **(3)** +* Set the **Footer** text for your tile **(4)** +* Set the **Color** of your icon **(1)** ![image](images/How-To_Add,_Edit_or_Delete_Dashboard_Tiles_3.png) -## Dynamic Color Tile +### Tile Filters +Click the **Tile Filters \+** button at the bottom of the form to expand the Tile Filters menu. From here you can apply any relevant filtering to the tile. See the [Tile Index](./#dashboard-tile-index) for more info on what filters can be applied to which tile. + +### Dynamic Color Tile If you want to set your tile to change color based on the associated count of Findings, Products or other objects returned by the filter, you can enable **Dynamic Color Tile** in this menu. The color of the tile Icon will change from Green \-\> Yellow \-\> Red as the object count changes. @@ -37,7 +63,7 @@ If you want to set your tile to change color based on the associated count of Fi * **Dynamic Color Maximum** is the top of the range. If the Object count is equal to or greater than this number, the tile Icon will be set to Red. * Any number between the Minimum or the Maximum will set the filter to Yellow. -### **Example 1: Critical Findings Count** +#### **Example: Critical Findings Count** Say you wanted to set up a Dynamic Color Tile to track our Critical Findings. You can set your Dynamic Color parameters as follows: @@ -47,7 +73,7 @@ Say you wanted to set up a Dynamic Color Tile to track our Critical Findings. Yo Of course, your team’s standards and acceptable range for this kind of filter may differ from our example. -## Inverted Maximum and Minimum +#### Inverted Maximum and Minimum If your Maximum is lower than your Minimum, the range will still compute correctly. @@ -61,13 +87,30 @@ You can set your **Dynamic Color Maximum** of 2, and a **Dynamic Color Minimum** * If the filter returns 5 Objects or greater, the tile will be **Green**, indicating that a healthy amount of your Products are passing. * If the filter returns a value between those two numbers, the tile will be **Yellow**, indicating that a significant, but non\-critical amount of your Products are not passing. -## Tile Filter Index +## Dashboard Tile Index + +Here is a list summarizing each Dashboard Tile you can add, along with filters that can be applied to the Tile and an example configuration. + +### Product, Engagement or Test Tiles -To set a specific context for your tile, you can set various Tile Filters. Click the **Tile Filters \+** button at the bottom of the form to expand the Tile Filters menu. +These Tiles allow you to quickly select a list of Products, Engagements or Tests based on the filter parameters you set. You can use this tile for ease in navigation. -Filters are optional. Each Tile has a different set of relevant filters which can be selected. +![image](images/About_Custom_Dashboard_Tiles_3.png) -### Product Tile +The number on the tile represents the count of objects (Products, Engagement or Tests) contained within the tile’s filter parameters. Clicking the footer will take you to a filtered list of those objects. + +#### Example: Monitoring Engagements In Progress + +If you want to create a list of your In\-Progress Engagements in DefectDojo, you can set up an Engagement tile which filters for that condition. + +* Create an Engagement tile, and from the Tile Filters set **Engagement Status** to **In Progress**. +* To make sure your Tile is accurately labeled, set the Header of your tile to ‘**Engagements In Progress**’. + +![image](images/About_Custom_Dashboard_Tiles_4.png) + +You could also create Engagement tiles for one or more other states, such as **Blocked** or **Completed**. + +#### Product Tile Filters * **Product Name Contains**: type in one or more partial matches of Product Names, separated by commas * **Product Name Exact**: type in one or more exact matches of Product Names, separated by commas @@ -83,7 +126,7 @@ Filters are optional. Each Tile has a different set of relevant filters which ca * **Tag Contains:** type in one or more partial matches of tags, separated by commas * **Outside of SLA**: Yes/No -### Engagement Tile +#### Engagement Tile Filters * **Product Name Contains**: type in one or more partial matches of Product Names, separated by commas * **Product Type**: Select one or more options from the list @@ -99,7 +142,7 @@ Filters are optional. Each Tile has a different set of relevant filters which ca * **Does Not Have Tags**: type in one or more exact matches tags to ignore, separated by commas * **Tag Does Not Contain**: type in one or more partial matches of tags to ignore, separated by commas -### Test Tile +#### Test Tile Filters * **Test Name Contains**: type in one or more partial matches of Test Names, separated by commas * **Test Type**: select a single Test Type from the list @@ -118,7 +161,26 @@ Filters are optional. Each Tile has a different set of relevant filters which ca * **Does Not Have Tags**: type in one or more exact matches tags to ignore, separated by commas * **Tag Does Not Contain**: type in one or more partial matches of tags to ignore, separated by commas -### Finding Tile +### Finding Tiles + +Finding tiles provide a count of Findings based on the filter parameters you set. As with other tiles, clicking the Footer will take you to a list of the Findings set by the tile. + +![image](images/About_Custom_Dashboard_Tiles_5.png) + +Using filter parameters you can track Findings in a particular state or time period. + +#### Example: Monitoring Critical Findings + +If you wanted to be able to quickly access all of your Critical Findings in DefectDojo, you could do this by creating a tile. + +* Create a Finding tile, and from the Tile Filters set **Severity** to **Critical**. +* To make sure your Tile is accurately labeled, set the Header of the tile to ‘**Critical Findings**’. + +![image](images/About_Custom_Dashboard_Tiles_6.png) + +You can add additional filter parameters to make this tile more functional for your use\-case. For example, if you wanted this tile to only track Open Findings (and ignore any Mitigated Findings) you could set the **Active** filter to **Yes.** + +#### Finding Tile Filters * **Name Contains**: enter a partial match of a Finding Name from the menu * **Component Name Contains**: enter a partial match of a Component Name from the menu @@ -171,8 +233,24 @@ Filters are optional. Each Tile has a different set of relevant filters which ca * **Product Tags**: type in one or more exact matches of tags, separated by commas * **Product Does Not Have Tags**: type in one or more exact matches of tags to ignore, separated by commas -### Endpoint Tile +### Endpoint Tiles +If you need to keep track of particular Endpoints, you can set up a Tile to quickly navigate to a filtered list. This tile can be set up to filter by Host, Product, Tags or other parameters that are relevant to the Endpoints you want to track. + +![image](images/About_Custom_Dashboard_Tiles_7.png) + +Clicking the footer on this tile brings us to a filtered list of Endpoints which displays their status. DefectDojo will only create and track Endpoints with related vulnerabilities, so this will not include any Endpoints which have no vulnerabilities reported. + +#### Example: Monitor All Endpoints With Same Host + +If you wanted to use Endpoints to look at vulnerabilities on a certain part of your architecture, regardless of the associated Product, you could use an Endpoint Tile to filter for a particular URL. From there, you could see all Findings associated with that part of your network. + +* Create an Endpoint tile. For this example, we are setting the Host Contains field to **‘centralaction\-items’**, as that string is part of many Endpoint URLs in our infrastructure.​ +* Set your Header to a title which describes the intended function of your tile. In this example, we used **‘Host: centralaction\-items’**. + +![image](images/About_Custom_Dashboard_Tiles_8.png) + +#### Endpoint Tile Filters * **Protocol Contains**: type in a partial match of a Protocol from the menu * **User Info Contains**: type in a partial match of User Info from the menu * **Host Contains**: type in a partial match of a Host from the menu @@ -189,18 +267,69 @@ Filters are optional. Each Tile has a different set of relevant filters which ca ### SLA Violation Tile +This Tile counts Findings which are at risk of violating SLA. It can be set to track all Products, or specific Products chosen from a list. + +#### Example: Findings Approaching SLA Violation + +If you want to create a filter for Findings which are within 7 days of SLA expiration, you can set up your filter parameters to track this. When setting the Filter parameters for the SLA Violation tile, set **‘Days Before Expiration’** to **7**. Select either All Products, or a list of specific Products. + +Set the Header to describe the filter you’re applying, for example ‘SLA Violation \- 3 Days Or Less’. + +![image](images/About_Custom_Dashboard_Tiles_9.png) + +Clicking on the footer will bring you to a list of these Findings for you to address. This tile only tracks Active Findings, but will also track Findings with an expired SLA. + +#### SLA Violation Tile Filters * **Days Before Expiration**: select an option from the menu * **Include All Products**: Yes/No * **Included Products**: select one or more Products from the menu ### Scan Time Violation Tile +This Tile is used to track specific Products to ensure that new scan data is being added on a regular basis. + +If there are particular Products which you’re scanning on a regular interval, you can use this tile to ensure your tools and imports are running as expected. + +This Tile will return a count and related list of Products which have **not** had new scan data added in the interval you’ve defined. + +#### Example: Automation Tracking + +If you have scanning tools set to run on a weekly basis, you can use this tile to make sure those automated processes are working correctly. + +* From the Tile filters, select the target Products where the scan data will be imported via automation. Set the Days Since Last Scan field to ‘Past Week’. +* Set a descriptive name in the Header which communicates the interval you’re testing. + +![image](images/About_Custom_Dashboard_Tiles_10.png) + +If you have multiple scanning intervals that you want to monitor, you can set up multiple tiles to track each one. + +#### Scan Time Violation Tile Filters * **Days Since Last Scan**: select an option from the menu * **Include All Products**: Yes/No * **Included Products**: select one or more Products from the menu ### Product Grade Tile +This Tile compares the Product Grade of all Products on your instance, so that you can track any Products which do not meet your grading standard. + +This tile uses a comparison operator (\<, \=, \<\=, \>\=) to track Products which equal, exceed or fail to meet the Product Grade which you want to monitor. + +![image](images/About_Custom_Dashboard_Tiles_11.png) +For more information on how Product Grades are calculated, see our article on [Product Health Grading](/en/working_with_findings/organizing_engagements_tests/product-health-grade/). + +#### Example: Track Failing Products + +If you want to quickly access Products in your instance which do not meet your Grading standard, you can set up a Tile which handles that calculation. The Grading standard used in this example is ‘Less Than C’: we want our tile to flag any Products with a Grade of D or lower. + +* Create a Product Grade Tile. From the Filters list, set the Grade which you consider ‘failing’. In this case we’ll select C. +* In the Filters list, set a **Comparison Operator** to determine the logic used in counting your failing Products. In this case, we’ll select **‘Less Than’**. + +![image](images/About_Custom_Dashboard_Tiles_12.png) + +As with other Product related Tiles, you can set the Tile to look at All Products in your instance, or only a specific list of Products. + +#### Product Grade Tile Filters + * **Product Grade**: select a single Product Grade from the menu * **Comparison Operator**: select a Comparison Operator from the menu, related to Product Grade * **Include All Products**: Yes/No diff --git a/docs/content/en/customize_dojo/notifications/_index.md b/docs/content/en/customize_dojo/notifications/_index.md new file mode 100644 index 00000000000..572a09f3278 --- /dev/null +++ b/docs/content/en/customize_dojo/notifications/_index.md @@ -0,0 +1,17 @@ +--- +title: "Notifications" +summary: "" +date: 2023-09-07T16:06:50+02:00 +lastmod: 2023-09-07T16:06:50+02:00 +draft: false +weight: 7 +chapter: true +sidebar: + collapsed: true +seo: + title: "" # custom title (optional) + description: "" # custom description (recommended) + canonical: "" # custom canonical URL (optional) + robots: "" # custom robot tags (optional) +pro-feature: true +--- \ No newline at end of file diff --git a/docs/content/en/customize_dojo/notifications/about_notifications.md b/docs/content/en/customize_dojo/notifications/about_notifications.md new file mode 100644 index 00000000000..8242bd1e820 --- /dev/null +++ b/docs/content/en/customize_dojo/notifications/about_notifications.md @@ -0,0 +1,61 @@ +--- +title: "About Notifications & 🔔 Alerts" +description: "Learn about notifications, in-app alerts" +--- + +DefectDojo keeps you up to date in a variety of ways. Notifications can be sent for upcoming Engagements, user Mentions, SLA expiry, and other events in the software. + +This article contains an overview of notifications at both System\-wide and Personal levels. + +## Notification Types + +DefectDojo handles notifications in two different ways:: + +* **System\-Wide Notifications** are sent to all users. +* **Personal Notifications are set by individual users, and will be received in addition to any System\-Wide Notifications.** + +In both cases, [Role\-Based Access Control](../../user_management/about_perms_and_roles/) rules apply, so users will not receive activity notifications for Products or Product Types (or their related objects) which they don’t have access to. + +## Notification Delivery Methods + +There are four delivery methods for DefectDojo notifications: + +* DefectDojo can share **🔔 Alerts,** stored as a list in the DefectDojo interface +* DefectDojo can send notifications to an **Email** address +* DefectDojo can send notifications to **Slack,** in either a shared or individual channel +* DefectDojo can also send notifications to **Microsoft Teams** in a shared channel + +Notifications can be sent to multiple destinations simultaneously. + +Receiving Slack and Teams notifications will require you to have a working integration. For more info on setting this integration up, see our [Guide](../email_slack_teams). + +## In-App Alerts + +DefectDojo’s Alerts system keeps you up to date with all Product or system activity. + +### The Alerts List + +The Alerts List is always visible in the top\-right hand corner of DefectDojo, and contains a compact list of notifications. Clicking on each Alert will take you directly to the relevant page in DefectDojo. + +You can open your Alerts List by clicking on the **🔔▼ icon** on the top right hand corner: + +![image](images/About_In-App_Alerts.png) + +To see all of your notifications, along with additional detail, you can click the **See All Alerts \>** button, which will open the **Alerts Page**. + +You can also **Clear All Alerts \>** from the Alerts List. + +### The Alerts Page + +The Alerts Page stores all of your Alerts in DefectDojo with additional detail. On this page, you can read descriptions of each Alert in DefectDojo, and remove them from the Alerts queue once you no longer need them. + +![image](images/About_In-App_Alerts_2.png) + +To remove one or more Alerts from the Alerts Page, check the empty box next to it, and then click the **Remove selected** button in the bottom\-right corner of the Page. + +### Notes On Alerts + +* Reading an Alert, or opening the Alerts Page will not remove any Alerts from the count next to the bell icon. This is so that you can easily access past alerts to use them as reminders or a personal activity log. +* Using the **Clear All Alerts \>** function in the Alerts Menu will also completely clear the **Alerts Page**, so use this feature with care. +* Removing an Alert only affects your own Alerts List \- it will not affect any other user’s Alerts. +* Removing an Alert does not remove any import history or activity logs from DefectDojo. diff --git a/docs/content/en/notifications/configure_system_notifs.md b/docs/content/en/customize_dojo/notifications/configure_personal_notifs.md similarity index 57% rename from docs/content/en/notifications/configure_system_notifs.md rename to docs/content/en/customize_dojo/notifications/configure_personal_notifs.md index 043ce8b1c02..1aed2b41efc 100644 --- a/docs/content/en/notifications/configure_system_notifs.md +++ b/docs/content/en/customize_dojo/notifications/configure_personal_notifs.md @@ -1,39 +1,15 @@ --- -title: "Configure System & Personal Notifications" -description: "How to configure Personal & System notifications" +title: "Set Personal Notifications" +description: "Configure notifications for a personal account" --- -DefectDojo has two different kinds of notifications: **Personal** (sent to a single account) and **System** (which are sent to all users). - - - -Both your account’s Personal Notifications and the global System Notifications can be configured from the same page: **⚙️Configuration \> Notifications** in the sidebar. - - - -![image](images/Configure_System_&_Personal_Notifications.png) - -# Configure System notifications - - -**You will need Superuser access to change System\-wide notifications.** - - - -1. Start from the Notifications page (⚙️ **Configuration \> Notifications** in the sidebar). -2. From the Scope drop down menu, you can select which set of notifications you wish to edit. -3. Select System Notifications. -4. Check the notification delivery method which you wish to use for each type of notification. You can select more than one. - - -![image](images/Configure_System_&_Personal_Notifications_2.png) - -# Configure Personal notifications - +## Configure Personal notifications Personal Notifications are sent in addition to System\-Wide Notifications, and will apply to any Product, Product Type or other data type that you have access to. Personal Notification preferences only apply to a single user, and can only be set on the account which is configuring them. +![image](images/Configure_System_&_Personal_Notifications.png) +System notifications are set by a DefectDojo Superuser and cannot be opted out of by an individual user. 1. Start from the Notifications page (⚙️**Configuration \> Notifications** in the sidebar). 2. From the **Scope** drop down menu, you can select which set of notifications you wish to edit. @@ -42,24 +18,16 @@ Personal Notifications are sent in addition to System\-Wide Notifications, and w Personal Notifications cannot be sent via Microsoft Teams, as Teams only allows for posting Global notifications in a single channel. - - - -## Receive Personal notifications for a specific Product - +### Receive Personal notifications for a specific Product In addition to standard personal notifications, DefectDojo Users can also receive notifications for activity on a specific Product. This is helpful when there are certain Products which a user needs to monitor more closely. - - ![image](images/Configure_System_&_Personal_Notifications_3.png) -This configuration can be changed from the **Notifications** section on the **Product** page: e.g. **your\-instance.defectdojo.com/product/{id}**. - +This configuration can be changed from the **Notifications** section on the **Product** page: e.g. `your-instance.defectdojo.com/product/{id}`. From here, you can set whether you want to receive **🔔 Alert**, **Mail** or **Slack** notifications for actions taken on this particular Product. These notifications apply in addition to any system\-wide notifications you are already receiving. - - Microsoft Teams cannot send personal notifications of any kind, so Teams notifications cannot be chosen from this menu. +Personal email notifications will always be sent to the email associated with your DefectDojo login. To set up a personal Slack account to receive notifications, see our [Guide](../email_slack_teams/#send-personal-notifications-to-slack). \ No newline at end of file diff --git a/docs/content/en/customize_dojo/notifications/configure_system_notifs.md b/docs/content/en/customize_dojo/notifications/configure_system_notifs.md new file mode 100644 index 00000000000..04ff29f635e --- /dev/null +++ b/docs/content/en/customize_dojo/notifications/configure_system_notifs.md @@ -0,0 +1,23 @@ +--- +title: "Set System-Wide Notifications" +description: "How to configure Personal & System notifications" +--- + +DefectDojo has two different kinds of notifications: **Personal** (sent to a single account) and **System** (which are sent to all users). + +Both an account’s Personal Notifications and the global System Notifications can be configured from the same page: **⚙️Configuration \> Notifications** in the sidebar. + +![image](images/Configure_System_&_Personal_Notifications.png) + +## Configure System notifications (Classic UI) + +**You will need Superuser access to change System\-wide notifications.** + +1. Start from the Notifications page (⚙️ **Configuration \> Notifications** in the sidebar). +2. From the Scope drop down menu, you can select which set of notifications you wish to edit. +3. Select System Notifications. +4. Check the notification delivery method which you wish to use for each type of notification. You can select more than one. + +![image](images/Configure_System_&_Personal_Notifications_2.png) + +To set destinations for system wide email notifications (Email, Slack or MS Teams), see our [Guide](../email_slack_teams). \ No newline at end of file diff --git a/docs/content/en/notifications/configure_slack.md b/docs/content/en/customize_dojo/notifications/email_slack_teams.md similarity index 57% rename from docs/content/en/notifications/configure_slack.md rename to docs/content/en/customize_dojo/notifications/email_slack_teams.md index 1c80e4bb668..aa7ba993b6b 100644 --- a/docs/content/en/notifications/configure_slack.md +++ b/docs/content/en/customize_dojo/notifications/email_slack_teams.md @@ -1,8 +1,14 @@ --- -title: "Configure a Slack Integration" -description: "Set up Slack to receive notifications from DefectDojo" +title: "Set up Email, Slack or Teams notifications" +description: "Set up Microsoft Teams to receive notifications" --- +**You will need Superuser access to use the System Settings page, which is required to complete this process.** + +Notifications can be pushed to Slack or Teams when certain events trigger in DefectDojo. + +## Slack Notifications Setup + DefectDojo can post Slack notifications in two different ways: * System\-wide notifications, which will be sent to a single Slack channel @@ -14,7 +20,7 @@ Here is an example of a Slack Notification sent from DefectDojo: DefectDojo does not have a dedicated Slack app, but one can be easily created for your workspace by following this guide. A Slack app is required for both System and Personal notifications to be sent correctly. -## Create a Slack application +### Create a Slack application To set up a Slack connection to DefectDojo, you’ll need to create a custom Slack app. @@ -60,7 +66,7 @@ To set up a Slack connection to DefectDojo, you’ll need to create a custom Sla Review the App Summary, and click Create App when you’re done. Complete the installation by clicking the **Install To Workplace** button. -## Configure your Slack integration in DefectDojo +### Configure your Slack integration in DefectDojo You’ll now need to configure the Slack integration on DefectDojo to complete the integration. @@ -73,7 +79,7 @@ You’ll now need to configure the Slack integration on DefectDojo to complete t ![image](images/Configure_a_Slack_Integration_2.png) -3. Open DefectDojo in a new tab, and navigate to **Configuration \> System Settings** from the sidebar. +3. Open DefectDojo in a new tab, and navigate to **Configuration \> System Settings** from the sidebar. (In the Beta UI, this form is located under **Enterprise Settings > System Settings**.) 4. Check the **Enable Slack notifications** box. 5. Paste the **Bot User OAuth Token** from Step 1 in the **Slack token** field. 6. The **Slack Channel** field should correspond to the channel in your workspace where you want your notifications to be written by a DefectDojo bot. @@ -83,13 +89,13 @@ Once this process is complete, DefectDojo can send System\-wide notifications to ![image](images/Configure_a_Slack_Integration_3.png) -## Notes on System\-Wide Notifications in Slack**:** +#### Notes on System\-Wide Notifications in Slack: Slack cannot apply any RBAC rules to the Slack channel that you are creating, and will therefore be sharing notifications for the entire DefectDojo system. There is no method in DefectDojo to filter system\-wide Slack notifications to a Product Type, Product or Engagement. If you want to apply RBAC\-based filtering to your Slack messages, enabling personal notifications from Slack is a better option. -## Send Personal notifications to Slack +### Send Personal notifications to Slack If your team has a Slack integration enabled (through the above process), individual users can also configure notifications to send directly to your personal Slackbot channel. @@ -99,4 +105,35 @@ If your team has a Slack integration enabled (through the above process), indivi 2. Set your **Slack Email Address** in the menu. This field is nested underneath **Additional Contact Information** in DefectDojo. -You can now [set specific notifications](https://docs.defectdojo.com/en/notifications/about-notifications/) to be sent to your personal Slackbot channel. Other users on your Slack channel will not receive these messages. +You can now [set specific notifications](../about_notifications/) to be sent to your personal Slackbot channel. Other users on your Slack channel will not receive these messages. + +## Microsoft Teams Notifications Setup + +Microsoft Teams can receive notifications to a specific channel. To do this, you will need to **set up an incoming webhook** on the channel where you wish to receive messages. + +1. Complete the process listed in the **[Microsoft Teams Documentation](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook?tabs=dotnet)** for creating a new Incoming Webhook. Keep your unique webhook.office.com link handy as you will need it in subsequent steps. +​ +![image](images/Configure_a_Microsoft_Teams_Integration.png) +2. In DefectDojo, navigate to **Configuration \> System Settings** from the sidebar. (In the Beta UI, this form is located under **Enterprise Settings > System Settings**.) +3. Check the **Enable Microsoft Teams notifications** box. This will open a hidden section of the form, labeled **‘Msteams url**’. +​ +![image](images/Configure_a_Microsoft_Teams_Integration_2.png) +4. Paste the webhook.office.com URL (created in Step 1\) in the **Msteams url** box. Your Teams app will now listen to incoming Notifications from DefectDojo and post them to the channel you selected. + +### Notes on the Teams integration + +* Slack cannot apply any RBAC rules to the Teams channel that you are creating, and will therefore be sharing notifications for the entire DefectDojo system. There is no method in DefectDojo to filter system\-wide Teams notifications by a Product Type, Product or Engagement. +* DefectDojo cannot send personal notifications to users on Microsoft Teams. + +## System-Wide Email Notifications Setup + +Notifications from DefectDojo can also be sent to a specific email address. + +1. From the System Settings page (**Configuration > System Settings** in the Classic UI, or **Enterprise Settings > System Settings** in the Beta UI) navigate to Enable Mail (email) Notifications. + +2. Check the **Enable mail notifications** box, and then enter the email address where you want these notifications to be sent (mail notifications to). + +![image](images/notifs_email.png) + +Note that DefectDojo cannot apply RBAC filtering to these emails - they will be sent for all activity in DefectDojo. If you prefer to send a more customized set of email notifications, it is better to set up [Personal Notifications](../configure_personal_notifs) with a user or service account that is linked to the appropriate address. + diff --git a/docs/content/en/user_management/_index.md b/docs/content/en/customize_dojo/user_management/_index.md similarity index 97% rename from docs/content/en/user_management/_index.md rename to docs/content/en/customize_dojo/user_management/_index.md index 80e27cbfec8..b9f0a30ef7b 100644 --- a/docs/content/en/user_management/_index.md +++ b/docs/content/en/customize_dojo/user_management/_index.md @@ -5,7 +5,7 @@ summary: "" date: 2023-09-07T16:06:50+02:00 lastmod: 2023-09-07T16:06:50+02:00 draft: false -weight: 2 +weight: 5 chapter: true sidebar: collapsed: true diff --git a/docs/content/en/user_management/about_perms_and_roles.md b/docs/content/en/customize_dojo/user_management/about_perms_and_roles.md similarity index 100% rename from docs/content/en/user_management/about_perms_and_roles.md rename to docs/content/en/customize_dojo/user_management/about_perms_and_roles.md diff --git a/docs/content/en/user_management/configure_sso.md b/docs/content/en/customize_dojo/user_management/configure_sso.md similarity index 100% rename from docs/content/en/user_management/configure_sso.md rename to docs/content/en/customize_dojo/user_management/configure_sso.md diff --git a/docs/content/en/user_management/create_user_group.md b/docs/content/en/customize_dojo/user_management/create_user_group.md similarity index 100% rename from docs/content/en/user_management/create_user_group.md rename to docs/content/en/customize_dojo/user_management/create_user_group.md diff --git a/docs/content/en/user_management/set_user_permissions.md b/docs/content/en/customize_dojo/user_management/set_user_permissions.md similarity index 100% rename from docs/content/en/user_management/set_user_permissions.md rename to docs/content/en/customize_dojo/user_management/set_user_permissions.md diff --git a/docs/content/en/user_management/user_permission_chart.md b/docs/content/en/customize_dojo/user_management/user_permission_chart.md similarity index 100% rename from docs/content/en/user_management/user_permission_chart.md rename to docs/content/en/customize_dojo/user_management/user_permission_chart.md diff --git a/docs/content/en/dashboard/about_custom_dashboard_tiles.md b/docs/content/en/dashboard/about_custom_dashboard_tiles.md deleted file mode 100644 index 7969b0ced90..00000000000 --- a/docs/content/en/dashboard/about_custom_dashboard_tiles.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: "About Custom Dashboard Tiles" -description: "How to make Dashboard Tiles work for you, with examples" ---- - -Dashboard Tiles are customizable sets of filters for your DefectDojo instance, which can be added to your 🏠 **Home** dashboard. Tiles are designed to provide relevant information and speed up navigation within DefectDojo. - -![image](images/About_Custom_Dashboard_Tiles.png) - -Tiles can: - -* Act as shortcuts for particular sets of Findings, Products, or other objects -* Visualize relevant metrics related to your Product -* Provide alerts on particular activity, track SLA Violations, failing imports or new Critical Findings - -## Tile Components - -Each Tile contains four main components: - -![image](images/About_Custom_Dashboard_Tiles_2.png) - -2. **A count of each object** that meets the Tile’s filter conditions. For example, a Findings Tile will count the number of Findings filtered by the Tile. -3. **A customizable Header** which can be set to describe the function of the tile. -4. **A customizable Footer** which brings you to the related list of objects. For example, a Findings Tile’s footer will bring you to a list of Findings filtered by the Tile. - -## Types of Dashboard Tiles - -There are eight Tiles which you can choose from. These Tiles are explained in more detail below, along with examples of usage. - -* **Product Tile** -* **Engagement Tile** -* **Test Tile** -* **Endpoint Tile** -* **SLA Violation Tile** -* **Scan Time Violation Tile** -* **Product Grade Tile** - -### Product, Engagement or Test Tile - -These Tiles allow you to quickly select a list of Products, Engagements or Tests based on the filter parameters you set. You can use this tile for ease in navigation. - -![image](images/About_Custom_Dashboard_Tiles_3.png) - -The number on the tile represents the count of objects (Products, Engagement or Tests) contained within the tile’s filter parameters. Clicking the footer will take you to a filtered list of those objects. - -#### Example: Monitoring Engagements In Progress - -If you want to create a list of your In\-Progress Engagements in DefectDojo, you can set up an Engagement tile which filters for that condition. - -* Create an Engagement tile, and from the Tile Filters set **Engagement Status** to **In Progress**. -* To make sure your Tile is accurately labeled, set the Header of your tile to ‘**Engagements In Progress**’. - -![image](images/About_Custom_Dashboard_Tiles_4.png) - -You could also create Engagement tiles for one or more other states, such as **Blocked** or **Completed**. - -### Finding Tiles - -Finding tiles provide a count of Findings based on the filter parameters you set. As with other tiles, clicking the Footer will take you to a list of the Findings set by the tile. - -![image](images/About_Custom_Dashboard_Tiles_5.png) - -Using filter parameters you can track Findings in a particular state or time period. - -#### Example: Monitoring Critical Findings - -If you wanted to be able to quickly access all of your Critical Findings in DefectDojo, you could do this by creating a tile. - -* Create a Finding tile, and from the Tile Filters set **Severity** to **Critical**. -* To make sure your Tile is accurately labeled, set the Header of the tile to ‘**Critical Findings**’. - -![image](images/About_Custom_Dashboard_Tiles_6.png) - -You can add additional filter parameters to make this tile more functional for your use\-case. For example, if you wanted this tile to only track Open Findings (and ignore any Mitigated Findings) you could set the **Active** filter to **Yes.** - -### Endpoint Tiles - -If you need to keep track of particular Endpoints, you can set up a Tile to quickly navigate to a filtered list. This tile can be set up to filter by Host, Product, Tags or other parameters that are relevant to the Endpoints you want to track. - -![image](images/About_Custom_Dashboard_Tiles_7.png) - -Clicking the footer on this tile brings us to a filtered list of Endpoints which displays their status. DefectDojo will only create and track Endpoints with related vulnerabilities, so this will not include any Endpoints which have no vulnerabilities reported. - -#### Example: Monitor All Endpoints With Same Host - -If you wanted to use Endpoints to look at vulnerabilities on a certain part of your architecture, regardless of the associated Product, you could use an Endpoint Tile to filter for a particular URL. From there, you could see all Findings associated with that part of your network. - -* Create an Endpoint tile. For this example, we are setting the Host Contains field to **‘centralaction\-items’**, as that string is part of many Endpoint URLs in our infrastructure.​ -* Set your Header to a title which describes the intended function of your tile. In this example, we used **‘Host: centralaction\-items’**. - -![image](images/About_Custom_Dashboard_Tiles_8.png) - -### SLA Violation Tile - -This Tile counts Findings which are at risk of violating SLA. It can be set to track all Products, or specific Products chosen from a list. - -#### Example: Findings Approaching SLA Violation - -If you want to create a filter for Findings which are within 7 days of SLA expiration, you can set up your filter parameters to track this. When setting the Filter parameters for the SLA Violation tile, set **‘Days Before Expiration’** to **7**. Select either All Products, or a list of specific Products. - - - -Set the Header to describe the filter you’re applying, for example ‘SLA Violation \- 3 Days Or Less’. - -![image](images/About_Custom_Dashboard_Tiles_9.png) - -Clicking on the footer will bring you to a list of these Findings for you to address. This tile only tracks Active Findings, but will also track Findings with an expired SLA. - -### Scan Time Violation Tile - -This Tile is used to track specific Products to ensure that new scan data is being added on a regular basis. - -ere are particular Products which you’re scanning on a regular interval, you can use this tile to ensure your tools and imports are running as expected. - -This Tile will return a count and related list of Products which have **not** had new scan data added in the interval you’ve defined. - -#### Example: Automation Tracking - -If you have scanning tools set to run on a weekly basis, you can use this tile to make sure those automated processes are working correctly. - -* From the Tile filters, select the target Products where the scan data will be imported via automation. Set the Days Since Last Scan field to ‘Past Week’. -* Set a descriptive name in the Header which communicates the interval you’re testing. - -![image](images/About_Custom_Dashboard_Tiles_10.png) - -If you have multiple scanning intervals that you want to monitor, you can set up multiple tiles to track each one. - -### Product Grade Title - -This Tile compares the Product Grade of all Products on your instance, so that you can track any Products which do not meet your grading standard. - -This tile uses a comparison operator (\<, \=, \<\=, \>\=) to track Products which equal, exceed or fail to meet the Product Grade which you want to monitor. - -![image](images/About_Custom_Dashboard_Tiles_11.png) -For more information on how Product Grades are calculated, see our article on [Product Health Grading](https://docs.defectdojo.com/en/working_with_findings/organizing_engagements_tests/product-health-grade/). - -### Example: Track Failing Products - -If you want to quickly access Products in your instance which do not meet your Grading standard, you can set up a Tile which handles that calculation. The Grading standard used in this example is ‘Less Than C’: we want our tile to flag any Products with a Grade of D or lower. - -* Create a Product Grade Tile. From the Filters list, set the Grade which you consider ‘failing’. In this case we’ll select C. -* In the Filters list, set a **Comparison Operator** to determine the logic used in counting your failing Products. In this case, we’ll select **‘Less Than’**. - -![image](images/About_Custom_Dashboard_Tiles_12.png) - -As with other Product related Tiles, you can set the Tile to look at All Products in your instance, or only a specific list of Products. - -# **Next Steps:** - -* Learn how to [Add, Edit or Delete your Dashboard Tiles](https://docs.defectdojo.com/en/dashboard/how-to-add-edit-or-delete-dashboard-tiles/). -* For more detailed descriptions of Tile Filters, see our [Tile Filter Index](https://docs.defectdojo.com/en/dashboard/add_edit_delete_dashboard_tiles/#tile-filter-index). diff --git a/docs/content/en/dashboard/edit_dashboard_configuration.md b/docs/content/en/dashboard/edit_dashboard_configuration.md deleted file mode 100644 index 59519729432..00000000000 --- a/docs/content/en/dashboard/edit_dashboard_configuration.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: "How-To: Edit Dashboard Configuration" -description: "Customize or reset your dashboard metrics" ---- - -Superusers can choose which Metrics Charts are displayed on the Dashboard. To do this, select the **Edit Dashboard Configuration** option from the top\-right hand gear menu. - -![image](images/How-To_Edit_Dashboard_Configuration.png) -This will open the **Dashboard Configuration Settings** window. - -## Dashboard Configuration Options - -![image](images/How-To_Edit_Dashboard_Configuration_2.png) - -* **Display Graphs** determines whether or not the **Historical Finding Severity** and **Reported Finding Severity** charts are visible. -* **Display Surveys determines whether or not the Unassigned Answered Engagement Questionnaires table is visible.** -* **Display Data Tables determines whether or not the Top 10 / Bottom 10 Graded Products tables are visible.** - -## Reset Dashboard Configuration - -If you would like to reset your Dashboard to a default state, you can do so by selecting **Reset Dashboard Configuration** from the top\-right hand gear menu. - -![image](images/How-To_Edit_Dashboard_Configuration_3.png) - -**Note that this will remove any Custom Dashboard Tiles which have been added to your instance.** diff --git a/docs/content/en/jira_integration/configure_jira_dojo_webhook.md b/docs/content/en/jira_integration/configure_jira_dojo_webhook.md deleted file mode 100644 index 0e1ca714186..00000000000 --- a/docs/content/en/jira_integration/configure_jira_dojo_webhook.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "Configuring the Jira <> DefectDojo Webhook" -description: "How to create a webhook within Jira to push updates to DefectDojo" ---- - -The Jira integration allows for bidirectional sync via webhook. DefectDojo receives Jira notifications at a unique address, which can allow for Jira comments to be received on Findings, or for Findings to be resolved via Jira depending on your configuration. - - - - -# Locating your Jira Webhook URL - - -Your Jira Webhook is located on the System Settings form under **Jira Integration Settings**: **Enterprise Settings \> System Settings** from the sidebar. - - - -![image](images/Configuring_the_Jira_DefectDojo_Webhook.png) - -# Configuring Jira to send updates to your Webhook - - -1. Visit **https:// \ /plugins/servlet/webhooks** -2. Click 'Create a Webhook'. -3. For the field labeled 'URL' enter: [https://](https:) \<**YOUR DOJO DOMAIN**\> /jira/webhook/ \<**YOUR GENERATED WEBHOOK SECRET**\>. The Web Hook Secret is listed under the Jira Integration Settings as listed above. -4. Under 'Comments' enable 'Created'. Under Issue enable 'Updated'. - -Note that you do not need to create a Secret within Jira to use this webhook. The Secret is built into DefectDojo's URL, so simply adding the complete URL to the Jira Webhook form is sufficient. - - - -DefectDojo's Jira Webhook only accepts requests from the Jira API. - - - - -# Testing the Webhook - - -Once you have one or more Issues created from DefectDojo Findings, you can test the Webhook by adding a Comment to one of those Findings. The Comment should be received by the Jira webhook as a note. - - - -If this doesn’t work correctly, it could be due to a Firewall issue on your Jira instance blocking the Webhook. - - -* DefectDojo's Firewall Rules include a checkbox for **Jira Cloud,** which needs to be enabled before DefectDojo can receive Webhook messages from Jira. - - -​ - diff --git a/docs/content/en/jira_integration/connect_to_jira.md b/docs/content/en/jira_integration/connect_to_jira.md deleted file mode 100644 index d00e8549349..00000000000 --- a/docs/content/en/jira_integration/connect_to_jira.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: "Connect DefectDojo to Jira" -description: "Set up a Jira Configuration in DefectDojo - step 1 of working with Jira" ---- - -Jira Configurations are the starting point for DefectDojo’s Jira integration. You can add multiple configurations to a DefectDojo instance, to allow for many different linked Jira Projects and boards. - -Adding a configuration does not cause any Findings to push right away \- this is simply the first step. Once the Jira Configuration is created, it must be added to a Product before any information will push to Jira. See **[this guide](https://docs.defectdojo.com/en/jira_integration/add-a-connected-jira-project-to-a-product/)** for help with adding this integration to a Product. - -## The Jira Configuration Page - -The first step of setting up a Jira configuration is to add a Project to DefectDojo. - -1. If you have not already done so, navigate to the System Settings page and check the box on **Enable Jira Integration**. You will need to do this before the ⚙️ **Configuration \> JIRA** option shows up on the sidebar. -​ -2. Navigate to the ⚙️**Configuration \> JIRA** page from the DefectDojo sidebar. -​ -![image](images/Connect_DefectDojo_to_Jira.png) - - -3. You will see a list of all currently configured JIRA Projects which are linked to DefectDojo. To add a new Project Configuration, click the wrench icon and choose either the **Add JIRA Configuration (Express)** or **Add JIRA Configuration** options. - -## Add JIRA Configuration (Express) - -The Express method allows for a quicker method of linking a Project. Use the Express method if you simply want to connect a Jira Project quickly, and you aren’t dealing with a complex Jira workflow. - -![image](images/Connect_DefectDojo_to_Jira_2.png) - -1. Select a name for this Jira Configuration to use on DefectDojo. -​ -2. Select the URL for your company’s Jira instance \- likely similar to https://**yourcompany**.atlassian.net if you’re using a Jira Cloud installation. -​ -3. Enter your Username and Password for Jira. Alternatively, if your Jira instance uses a Personal Access Token (**PAT**) for authentication, you should instead enter the **PAT** in the Password field. The Username will not be used for authentication with **PAT**, but you can use this field as a label to indicate the name of the **PAT** you're using. -​ -4. Select the Default issue type which you want to create Issues as in Jira. The options for this are **Bug, Task, Story** and **Epic** (which are standard Jira issue types) as well as **Spike** and **Security**, which are custom issue types. If you have a different Issue Type which you want to use, please contact [support@defectdojo.com](mailto:support@defectdojo.com) for assistance. -​ -5. Select your Issue Template \- the two types are: -\- **Jira\_full**, which will include all Finding information in Jira Issues -\- **Jira\_limited**, which will include a smaller amount of Finding information and metadata. -​ -If you leave this field blank, it will default to **Jira\_full.** -​ -6. Select one or more Jira Resolution types which will change the status of a Finding to Accepted (when the Resolution is triggered on the Issue). If you don’t wish to use this automation, you can leave the field blank. -​ -7. Select one or more Jira Resolution types which will change the status of a Finding to False Positive (when the Resolution is triggered on the Issue). If you don’t wish to use this automation, you can leave the field blank. -​ -8. Decide whether you wish to send SLA Notifications as a comment on a Jira issue. -​ -9. Decide whether you wish to automatically sync Findings with Jira. If this is enabled, Jira Issues will automatically be kept in sync with the related Findings. If this is not enabled, you will need to manually push any changes made to a Finding after the Issue has been created in Jira. -​ -10. Select your Issue key. In Jira, this is the string associated with an Issue (e.g. the word **‘EXAMPLE’** in an issue called **EXAMPLE\-123**). If you don’t know your issue key, create a new Issue in the Jira Project. In the screenshot below, we can see that the issue key on our Jira Project is **DEF**. -​ -![image](images/Connect_DefectDojo_to_Jira_3.png) -​ -11. Click **Submit.** DefectDojo will automatically look for appropriate mappings in Jira and add them to the configuration. You are now ready to link this configuration to one or more Products in DefectDojo. - -## Add Jira Configuration (Standard) - -The Standard Jira Configuration adds a few additional steps to allow for more precise control over Jira mappings and interactions. This can be changed after a Jira configuration has been added, even if it was created using the Express method. -​ -## Additional Configuration Options - -* **Epic Name ID:** If you have multiple Epic types in Jira, you can specify the one you want to use by finding its ID in the Jira Field Spec. -​ -To obtain the 'Epic name id' visit https://\/rest/api/2/field and search for Epic Name. Copy the number out of cf\[number] and paste it here. -​ ​ -* **Reopen Transition ID:** If you want a specific Jira Transition to Reopen an issue, you can specify the Transition ID here. If using the Express Jira Configuration, DefectDojo will automatically find an appropriate Transition and create the mapping. -​ -Visit https://\/rest/api/latest/issue/\/transitions? expand\-transitions.fields to find the ID for your Jira instance. Paste it in the Reopen Transition ID field. -​ -* **Close Transition ID:** If you want a specific Jira Transition to Close an issue, you can specify the Transition ID here. If using the **Express Jira Configuration**, DefectDojo will automatically find an appropriate Transition and create the mapping. -​ -Visit https://\/rest/api/latest/issue/\/transitions? expand\-transitions.fields to find the ID for your Jira instance. Paste it in the Close Transition ID field. -​ -* **Mapping Severity Fields:** Each Jira Issue has an associated Priority, which DefectDojo will automatically assign based on the Severity of a Finding. Enter the names of each Priority which you want to map to, for Info, Low, Medium, High and Critical Severities. - -* **Finding Text** \- if you want to add additional standardized text to each Issue created, you can enter that text here. This is not text that maps to any field in Jira, but additional text that is added to the Issue Description. "**Created by DefectDojo**" for example. - -Comments (in Jira) and Notes (in DefectDojo) can be kept in sync. This setting can be enabled once the Jira configuration has been added to a Product, via the **Edit Product** form. - -# Next steps - -Now that you've set up your Jira Configuration, **[link it to one or more of your Products](https://docs.defectdojo.com/en/jira_integration/add-a-connected-jira-project-to-a-product/)** to have your Findings populate into Jira. diff --git a/docs/content/en/notifications/_index.md b/docs/content/en/notifications/_index.md deleted file mode 100644 index 1507dc47985..00000000000 --- a/docs/content/en/notifications/_index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "Set Up Notifications" -description: "Configure your DefectDojo in-app, email and other notifications" -summary: "" -date: 2023-09-07T16:06:50+02:00 -lastmod: 2023-09-07T16:06:50+02:00 -draft: false -weight: 8 -chapter: true -sidebar: - collapsed: true -seo: - title: "" # custom title (optional) - description: "" # custom description (recommended) - canonical: "" # custom canonical URL (optional) - robots: "" # custom robot tags (optional) ---- \ No newline at end of file diff --git a/docs/content/en/notifications/about_inapp_alerts.md b/docs/content/en/notifications/about_inapp_alerts.md deleted file mode 100644 index 76fc27823d3..00000000000 --- a/docs/content/en/notifications/about_inapp_alerts.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "About In-App Alerts" -description: "Manage your personal 🔔 Alerts in DefectDojo" ---- - -DefectDojo’s Alerts system keeps you up to date with all Product or system activity. - - - -## The Alerts List - - -The Alerts List is always visible in the top\-right hand corner of DefectDojo, and contains a compact list of notifications. Clicking on each Alert will take you directly to the relevant page in DefectDojo. - - - -You can open your Alerts List by clicking on the **🔔▼ icon** on the top right hand corner: - - -# - - -![image](images/About_In-App_Alerts.png) - - - -To see all of your notifications, along with additional detail, you can click the **See All Alerts \>** button, which will open the **Alerts Page**. - - - -You can also **Clear All Alerts \>** from the Alerts List. - - - - -## The Alerts Page - - -The Alerts Page stores all of your Alerts in DefectDojo with additional detail. On this page, you can read descriptions of each Alert in DefectDojo, and remove them from the Alerts queue once you no longer need them. - - - -![image](images/About_In-App_Alerts_2.png) -To remove one or more Alerts from the Alerts Page, check the empty box next to it, and then click the **Remove selected** button in the bottom\-right corner of the Page. - - - -## Notes On Alerts - - -* Reading an Alert, or opening the Alerts Page will not remove any Alerts from the count next to the bell icon. This is so that you can easily access past alerts to use them as reminders or a personal activity log. -* Using the **Clear All Alerts \>** function in the Alerts Menu will also completely clear the **Alerts Page**, so use this feature with care. -* Removing an Alertonly affects your own Alerts List \- it will not affect any other user’s Alerts. -* Removing an Alert does not remove any import history or activity logs from DefectDojo. diff --git a/docs/content/en/notifications/about_notifications.md b/docs/content/en/notifications/about_notifications.md deleted file mode 100644 index dcdfc2b188d..00000000000 --- a/docs/content/en/notifications/about_notifications.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "About Notifications" -description: "" ---- - -DefectDojo keeps you up to date in a variety of ways. Notifications can be sent for upcoming Engagements, user Mentions, SLA expiry, and other events in the software. - -This article contains an overview of notifications at both System\-wide and Personal levels. - -## Notification Types - -DefectDojo handles notifications in two different ways:: - -* **System\-Wide Notifications** are sent to all users. -* **Personal Notifications are set by individual users, and will be received in addition to any System\-Wide Notifications.** - -In both cases, [Role\-Based Access Control](https://docs.defectdojo.com/en/user_management/about-permissions--roles/) rules apply, so users will not receive activity notifications for Products or Product Types (or their related objects) which they don’t have access to. - -## Notification Delivery Methods - -There are four delivery methods for DefectDojo notifications: - -* DefectDojo can share **🔔 Alerts,** stored as a list in the DefectDojo interface -* DefectDojo can send notifications to an **Email** address -* DefectDojo can send notifications to **Slack,** in either a shared or individual channel -* DefectDojo can also send notifications to **Microsoft Teams** in a shared channel - -Notifications can be sent to multiple destinations simultaneously. - -Receiving Slack and Teams notifications will require you to have a working integration. For more info, see our articles: - -* [Slack Integration](https://docs.defectdojo.com/en/notifications/configure-a-slack-integration/) -* [Teams Integration](https://docs.defectdojo.com/en/notifications/configure-a-microsoft-teams-integration/) - -**Next Steps:** - -* **[Learn more about DefectDojo's internal 🔔 Alerts](https://docs.defectdojo.com/en/notifications/configure-a-slack-integration/)** -* [Set up a Slack integration for DefectDojo](https://docs.defectdojo.com/en/notifications/configure-a-microsoft-teams-integration/) -* [Set up a Teams integration for DefectDojo](https://docs.defectdojo.com/en/notifications/configure-a-microsoft-teams-integration/) diff --git a/docs/content/en/notifications/configure_msteams.md b/docs/content/en/notifications/configure_msteams.md deleted file mode 100644 index 401cb61745c..00000000000 --- a/docs/content/en/notifications/configure_msteams.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: "Configure a Microsoft Teams Integration" -description: "Set up Microsoft Teams to receive notifications" ---- - -**You will need Superuser access to use the System Settings page, which is required to complete this process.** - - - -Like with Slack, Microsoft Teams can receive notifications to a specific channel. To do this, you will need to **set up an incoming webhook** on the channel where you wish to receive messages. - - - -1. Complete the process listed in the **[Microsoft Teams Documentation](https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook?tabs=dotnet)** for creating a new Incoming Webhook. Keep your unique webhook.office.com link handy as you will need it in subsequent steps. -​ - - -![image](images/Configure_a_Microsoft_Teams_Integration.png) -2. In DefectDojo, navigate to **Configuration \> System Settings** from the sidebar. -3. Check the **Enable Microsoft Teams notifications** box. This will open a hidden section of the form, labeled **‘Msteams ur**l’. -​ - - -![image](images/Configure_a_Microsoft_Teams_Integration_2.png) -4. Paste the webhook.office.com URL (created in Step 1\) in the **Msteams url** box. Your Teams app will now listen to incoming Notifications from DefectDojo and post them to the channel you selected. - - -## Notes on the Teams integration - - -* Slack cannot apply any RBAC rules to the Teams channel that you are creating, and will therefore be sharing notifications for the entire DefectDojo system. There is no method in DefectDojo to filter system\-wide Teams notifications by a Product Type, Product or Engagement. -* DefectDojo cannot send personal notifications to users on Microsoft Teams. diff --git a/docs/content/en/open_source/installation/installation.md b/docs/content/en/open_source/installation/installation.md index 8f6affa702e..1d3e2fef7cc 100644 --- a/docs/content/en/open_source/installation/installation.md +++ b/docs/content/en/open_source/installation/installation.md @@ -16,10 +16,6 @@ See instructions in [DOCKER.md]( SLA Configur If enabled, any Issue where the associated DefectDojo Risk Acceptance expires will have a comment added to the Jira issue indicating this. These comments will be posted daily until the Issue is resolved. -# Testing \& Troubleshooting the Jira integration +## Testing the Jira integration -## Test 1: Do Findings successfully push to Jira? +### Test 1: Do Findings successfully push to Jira? In order to test that the Jira integration is working properly, you can add a new blank Finding to the Product associated with Jira in DefectDojo. **Product \> Findings \> Add New Finding.** @@ -130,7 +140,7 @@ If Jira Issues are not being created correctly, check your Notifications for err * Confirm that the Jira User associated with DefectDojo's Jira Configuration has permission to create and update issues on that particular Jira Project. -## Test 2: Jira Webhooks send and receive updates from DefectDojo +### Test 2: Jira Webhooks send to DefectDojo In order to test the Jira webhooks, add a Note to a Finding which also exists in JIRA as an Issue (for example, the test issue in the section above). @@ -142,4 +152,4 @@ If this doesn’t work correctly, it could be due to a Firewall issue on your Ji # Next Steps -Learn how to create Jira Issues from your Product with **[this guide](https://docs.defectdojo.com/en/jira_integration/creating-issues-in-jira/).** +Learn how to create Jira Issues from your Product with **[this guide](../create_issues_in_jira).** diff --git a/docs/content/en/share_your_findings/jira_integration/connect_to_jira.md b/docs/content/en/share_your_findings/jira_integration/connect_to_jira.md new file mode 100644 index 00000000000..100a7125ea5 --- /dev/null +++ b/docs/content/en/share_your_findings/jira_integration/connect_to_jira.md @@ -0,0 +1,154 @@ +--- +title: "Connect DefectDojo to Jira" +description: "Set up a Jira Configuration in DefectDojo - step 1 of working with Jira" +weight: 1 +--- + +Connecting a Jira Instance is the first step to take when setting up DefectDojo’s Jira integration. + +Each Jira Instance connection needs to be set up with the following attributes: +* a Jira Cloud URL +* a Jira username and password, or personal access token which DefectDojo can use to connect to that Jira Cloud URL + +When you set up your Jira Instance, you'll set up the following value mappings: +* the Epic name that you want to use +* Jira Transitions to trigger Re-Opening and Closing Findings +* Jira Resolutions which can apply Risk Acceptance and False Positive statuses to Findings (optional) + +Multiple Jira Projects can be handled by a single Jira Instance connection, as long as the Jira account / token used by DefectDojo has permission to create Issues in the associated Jira Project. + +Connecting a Jira instance does not cause any Findings to push right away \- this is simply the first step. Once the Jira Instance connection is created, it must be associated with a Product before any information will push to Jira. See **[this guide](../add_jira_to_product)** for help with adding this integration to a Product. + +## Add a Jira Instance (Beta UI) + +1. If you have not already done so, navigate to the System Settings page and check the box on **Enable Jira Integration**. + +2. Navigate to the **Enterprise Settings \> Jira Instances \> + New Jira Instance** page from the DefectDojo sidebar. + +![image](images/jira-instance-beta.png) + +3. Select a **Configuration Name** for this Jira Instance to use in DefectDojo. This name is simply a label for the Instance connection in DefectDojo, and does not need to be related to any Jira data. + +4. Select the URL for your company’s Jira instance \- likely similar to https://**yourcompany**.atlassian.net if you’re using a Jira Cloud installation. + +5. Enter an appropriate Username and Password for Jira. Alternatively, if your Jira instance uses a Personal Access Token (**PAT**) for authentication, you should instead enter the **PAT** in the Password field. The Username will not be used for authentication with **PAT**, but you can use this field as a label to indicate the name of the **PAT** you're using. Note that the user associated with this connection have permission to create Issues and access data in your Jira instance. + +6. You will need to provide values for an Epic Name ID, Re-open Transition ID and Close Transition ID. These values can be changed later. While logged into Jira, you can access these values from the following URLs: +- **Epic Name ID**: visit `https://\/rest/api/2/field` and search for Epic Name. Copy the number out of cf\[number] and paste it here. +- **Re-open Transition ID**: visit `https://\/rest/api/latest/issue/\/transitions? expand\-transitions.fields` to find the ID for your Jira instance. Paste it in the Reopen Transition ID field. +- **Close Transition ID**: Visit `https://\/rest/api/latest/issue/\/transitions? expand\-transitions.fields` to find the ID for your Jira instance. Paste it in the Close Transition ID field. + +7. Select the Default issue type which you want to create Issues as in Jira. The options for this are **Bug, Task, Story** and **Epic** (which are standard Jira issue types) as well as **Spike** and **Security**, which are custom issue types. If you have a different Issue Type which you want to use, please contact [support@defectdojo.com](mailto:support@defectdojo.com) for assistance. + +8. Select your Issue Template \- the two types are: +\- **Jira\_full**, which will include all Finding information in Jira Issues +\- **Jira\_limited**, which will include a smaller amount of Finding information and metadata. +​ +If you leave this field blank, it will default to **Jira\_full.** + +9. If you wish, enter the name of a Jira Resolution which will change the status of a Finding to Accepted or to False Positive (when the Resolution is triggered on the Issue). + +The form can be submitted from here. If you wish, you can further customize your Jira integration under Optional Fields. Clicking this button will allow you to apply generic text to Jira Issues or change the mapping of Jira Severity Mappings. + +## Add a Jira Instance (Legacy UI) + +1. If you have not already done so, navigate to the System Settings page and check the box on **Enable Jira Integration**. You will need to do this before the ⚙️ **Configuration \> JIRA** option shows up on the sidebar. +​ +2. Navigate to the ⚙️ **Configuration \> JIRA** page from the DefectDojo sidebar. +​ + +![image](images/Connect_DefectDojo_to_Jira.png) + + +3. You will see a list of all currently configured JIRA Projects which are linked to DefectDojo. To add a new Project Configuration, click the wrench icon and choose either the **Add JIRA Configuration (Express)** or **Add JIRA Configuration** options. + +### Add JIRA Configuration (Express) + +The Express method allows for a quicker method of linking a Project. Use the Express method if you simply want to connect a Jira Project quickly, and you aren’t dealing with a complex Jira workflow. + +![image](images/Connect_DefectDojo_to_Jira_2.png) + +1. Select a name for this Jira Configuration to use in DefectDojo. This name is simply a label for the Instance connection in DefectDojo, and does not need to be related to any Jira data. +​ +2. Select the URL for your company’s Jira instance \- likely similar to https://**yourcompany**.atlassian.net if you’re using a Jira Cloud installation. +​ +3. Enter your Username and Password for Jira. Alternatively, if your Jira instance uses a Personal Access Token (**PAT**) for authentication, you should instead enter the **PAT** in the Password field. The Username will not be used for authentication with **PAT**, but you can use this field as a label to indicate the name of the **PAT** you're using. +​ +4. Select the Default issue type which you want to create Issues as in Jira. The options for this are **Bug, Task, Story** and **Epic** (which are standard Jira issue types) as well as **Spike** and **Security**, which are custom issue types. If you have a different Issue Type which you want to use, please contact [support@defectdojo.com](mailto:support@defectdojo.com) for assistance. +​ +5. Select your Issue Template \- the two types are: +\- **Jira\_full**, which will include all Finding information in Jira Issues +\- **Jira\_limited**, which will include a smaller amount of Finding information and metadata. +​ +If you leave this field blank, it will default to **Jira\_full.** +​ +6. Select one or more Jira Resolution types which will change the status of a Finding to Accepted (when the Resolution is triggered on the Issue). If you don’t wish to use this automation, you can leave the field blank. +​ +7. Select one or more Jira Resolution types which will change the status of a Finding to False Positive (when the Resolution is triggered on the Issue). If you don’t wish to use this automation, you can leave the field blank. +​ +8. Decide whether you wish to send SLA Notifications as a comment on a Jira issue. +​ +9. Decide whether you wish to automatically sync Findings with Jira. If this is enabled, Jira Issues will automatically be kept in sync with the related Findings. If this is not enabled, you will need to manually push any changes made to a Finding after the Issue has been created in Jira. +​ +10. Select your Issue key. In Jira, this is the string associated with an Issue (e.g. the word **‘EXAMPLE’** in an issue called **EXAMPLE\-123**). If you don’t know your issue key, create a new Issue in the Jira Project. In the screenshot below, we can see that the issue key on our Jira Project is **DEF**. +​ +![image](images/Connect_DefectDojo_to_Jira_3.png) +​ +11. Click **Submit.** DefectDojo will automatically look for appropriate mappings in Jira and add them to the configuration. You are now ready to link this configuration to one or more Products in DefectDojo. + +### Add Jira Configuration (Standard) + +The Standard Jira Configuration adds a few additional steps to allow for more precise control over Jira mappings and interactions. This can be changed after a Jira configuration has been added, even if it was created using the Express method. +​ +### Additional Configuration Options + +* **Epic Name ID:** If you have multiple Epic types in Jira, you can specify the one you want to use by finding its ID in the Jira Field Spec. +​ +To obtain the 'Epic name id' visit `https://\/rest/api/2/field` and search for Epic Name. Copy the number out of cf\[number] and paste it here. +​ ​ +* **Reopen Transition ID:** If you want a specific Jira Transition to Reopen an issue, you can specify the Transition ID here. If using the Express Jira Configuration, DefectDojo will automatically find an appropriate Transition and create the mapping. +​ +Visit `https://\/rest/api/latest/issue/\/transitions? expand\-transitions.fields` to find the ID for your Jira instance. Paste it in the Reopen Transition ID field. +​ +* **Close Transition ID:** If you want a specific Jira Transition to Close an issue, you can specify the Transition ID here. If using the **Express Jira Configuration**, DefectDojo will automatically find an appropriate Transition and create the mapping. +​ +Visit `https://\/rest/api/latest/issue/\/transitions? expand\-transitions.fields` to find the ID for your Jira instance. Paste it in the Close Transition ID field. +​ +* **Mapping Severity Fields:** Each Jira Issue has an associated Priority, which DefectDojo will automatically assign based on the Severity of a Finding. Enter the names of each Priority which you want to map to, for Info, Low, Medium, High and Critical Severities. + +* **Finding Text** \- if you want to add additional standardized text to each Issue created, you can enter that text here. This is not text that maps to any field in Jira, but additional text that is added to the Issue Description. "**Created by DefectDojo**" for example. + +Comments (in Jira) and Notes (in DefectDojo) can be kept in sync. This setting can be enabled once the Jira configuration has been added to a Product, via the **Edit Product** form. + +## Configure Bidirectional Sync: Jira Webhook + +The Jira integration allows for bidirectional sync via webhook. DefectDojo receives Jira notifications at a unique address, which can allow for Jira comments to be received on Findings, or for Findings to be resolved via Jira depending on your configuration. + +### Locating your Jira Webhook URL + +Your Jira Webhook is located on the System Settings form under **Jira Integration Settings**: **Enterprise Settings \> System Settings** from the sidebar. + +![image](images/Configuring_the_Jira_DefectDojo_Webhook.png) + +### Configuring Jira to send updates to your Webhook + +1. Visit `**https:// \ /plugins/servlet/webhooks**` +2. Click 'Create a Webhook'. +3. For the field labeled 'URL' enter: `https:// \<**YOUR DOJO DOMAIN**\> /jira/webhook/ \<**YOUR GENERATED WEBHOOK SECRET**\>`. The Web Hook Secret is listed under the Jira Integration Settings as listed above. +4. Under 'Comments' enable 'Created'. Under Issue enable 'Updated'. + +Note that you do not need to create a Secret within Jira to use this webhook. The Secret is built into DefectDojo's URL, so simply adding the complete URL to the Jira Webhook form is sufficient. + +DefectDojo's Jira Webhook only accepts requests from the Jira API. + +### Testing the Webhook + +Once you have one or more Issues created from DefectDojo Findings, you can test the Webhook by adding a Comment to one of those Findings. The Comment should be received by the Jira webhook as a note. + +If this doesn’t work correctly, it could be due to a Firewall issue on your Jira instance blocking the Webhook. + +* DefectDojo's Firewall Rules include a checkbox for **Jira Cloud,** which needs to be enabled before DefectDojo can receive Webhook messages from Jira. + +## Next steps + +* Now that you've set up your Jira Configuration, **[link it to one or more of your Products](../add_jira_to_product)** to have your Findings populate into Jira. diff --git a/docs/content/en/jira_integration/create_issues_in_jira.md b/docs/content/en/share_your_findings/jira_integration/create_issues_in_jira.md similarity index 93% rename from docs/content/en/jira_integration/create_issues_in_jira.md rename to docs/content/en/share_your_findings/jira_integration/create_issues_in_jira.md index a37f7e33cd3..0e7fc040cc8 100644 --- a/docs/content/en/jira_integration/create_issues_in_jira.md +++ b/docs/content/en/share_your_findings/jira_integration/create_issues_in_jira.md @@ -1,12 +1,13 @@ --- -title: "Creating Issues in Jira" +title: "Send Finding data to Jira" description: "Pushing DefectDojo Findings to a linked Jira Project" +weight: 3 --- Before you can create an Issue in Jira, you'll need to have: -* **[a Jira integration configured](https://docs.defectdojo.com/en/jira_integration/connect-defectdojo-to-jira/)** -* **[that same Jira integration linked to a Product](https://docs.defectdojo.com/en/jira_integration/add-a-connected-jira-project-to-a-product/)** +* **[a Jira integration configured](../connect_to_jira/)** +* **[that same Jira integration linked to a Product](../add_jira_to_product/)** Please see the guides above for help with this process. diff --git a/docs/content/en/share_your_findings/jira_integration/troubleshooting_jira.md b/docs/content/en/share_your_findings/jira_integration/troubleshooting_jira.md new file mode 100644 index 00000000000..bcb8fbfe044 --- /dev/null +++ b/docs/content/en/share_your_findings/jira_integration/troubleshooting_jira.md @@ -0,0 +1,29 @@ +--- +title: "Troubleshooting Jira errors" +description: "Set up a Jira Configuration in DefectDojo - step 1 of working with Jira" +--- + +Here are some common issues with the Jira integration, and ways to address them. + +## Findings that I 'Push To Jira' do not appear in Jira +Using the 'Push To Jira' workflow triggers an asynchronous process, however an Issue should be created in Jira fairly quickly after 'Push To Jira' is triggered. + +* Check your DefectDojo notifications to see if the process was successful. If the push failed, you will get an error response from Jira in your notifications. + +Common reasons issues are not created: +* The Default Issue Type you have selected is not usable with the Jira Project +* Issues in the Project have required attributes that prevent them from being created via DefectDojo (see our guide to [Custom Fields](../using_custom_fields/)) + + +## Error: Product Misconfigured or no permissions in Jira? + +This error message can appear when attempting to add a created Jira configuration to a Product. DefectDojo will attempt to validate a connection to Jira, and if that connection fails, it will raise this error message. + +* Check to see if your Jira credentials are allowed to create issues in the given Jira Project you have selected. +* The "Project Key" field needs to be a valid Jira Project. Jira issues can use many different Keys within a single Project; the easiest way to confirm your Project Key is to look at the URL for that particular Jira Project: generally this will look like `https://xyz.atlassian.net/jira/core/projects/JTV/board`. In this case `JTV` is the Project Key. + +## Changes made to Jira issues are not updating Findings in DefectDojo + +* Start by confirming that the [DefectDojo webhook receiver](../connect_to_jira/#configure-bidirectional-sync-jira-webhook) is configured correctly and can successfully receive updates. + +* If you're trying to push status changes, confirm that Jira transition mappings are set up correctly (Reopen / Close [Transition IDs](../connect_to_jira/#configure-bidirectional-sync-jira-webhook)). \ No newline at end of file diff --git a/docs/content/en/jira_integration/using_custom_fields.md b/docs/content/en/share_your_findings/jira_integration/using_custom_fields.md similarity index 90% rename from docs/content/en/jira_integration/using_custom_fields.md rename to docs/content/en/share_your_findings/jira_integration/using_custom_fields.md index 62d637e6385..79fcfc21e1b 100644 --- a/docs/content/en/jira_integration/using_custom_fields.md +++ b/docs/content/en/share_your_findings/jira_integration/using_custom_fields.md @@ -1,33 +1,20 @@ --- -title: "Using Custom Fields in Jira" +title: "Custom Fields in Jira" description: "Making sure DefectDojo can successfully create Issues with custom fields" --- +DefectDojo does not currently support passing any Issue\-specific information into these Custom Fields \- these fields will need to be updated manually in Jira after the issue is created. Each Custom Field will only be created from DefectDojo with a default value. -**DefectDojo does not currently support passing any Issue\-specific information into these Custom Fields \- these fields will need to be updated manually in Jira after the issue is created. Each Custom Field will only be created from DefectDojo with a default value.** - - - -**Jira Cloud now allows you to create a default Custom Field value directly in\-app. [See Atlassian's documentation on Custom Fields](https://support.atlassian.com/jira-cloud-administration/docs/configure-a-custom-field/) for more information on how to configure this.** - - + Jira Cloud now allows you to create a default Custom Field value directly in\-app. [See Atlassian's documentation on Custom Fields](https://support.atlassian.com/jira-cloud-administration/docs/configure-a-custom-field/) for more information on how to configure this. DefectDojo's built\-in Jira Issue Types (**Bug, Task, Story** and **Epic)** are set up to work 'out of the box'. Data fields in DefectDojo will automatically map to the corresponding fields in Jira. By default, DefectDojo will assign Priority, Labels and a Reporter to any new Issue it creates. - - Some Jira configurations require additional custom fields to be accounted for before an issue can be created. This process will allow you to account for these custom fields in your DefectDojo \-\> Jira integration, ensuring that issues are created successfully. These custom fields will be added to any API calls sent from DefectDojo to a linked Jira instance. - - If you don’t already use Custom Fields in Jira, there is no need to follow this process. - - - # Process Summary - 1. Recording the names of your Custom Fields in Jira (**Jira UI**) 2. Determine the Key values for the new Custom Fields (Jira Field Spec Endpoint) 3. Locate the acceptable data for each Custom Field, using the Key values as a reference (Jira Issue Endpoint) @@ -35,126 +22,71 @@ If you don’t already use Custom Fields in Jira, there is no need to follow thi 5. Store the JSON block in the associated DefectDojo Product, to allow Custom Fields to be created from Jira (DefectDojo UI) 6. Test your work and ensure that all required data is flowing from Jira properly - - ## Step 1: Record the names of your Custom Fields in Jira - Jira supports a variety of different Context Fields, including Date Pickers, Custom Labels, Radio Buttons. Each of these Context Fields will have a different Key value that can be found in the Jira API. - - Write down the names of each required Custom Field, as you will need to search through the Jira API to find them in the next step. - - **Example of a Custom Field list (your Custom Field names will be different):** - * DefectDojo Custom URL Field * Another example of a Custom Field * ... - - - ## Step 2: Finding your Jira Custom Field Key Values - Start this process by navigating to the Field Spec URL for your entire Jira instance. - - Here is an example of a Field Spec URL: - -[https://yourcompany\-example.atlassian.net/rest/api/2/field](https://yourcompany-example.atlassian.net/rest/api/2/field) - - +`https://yourcompany\-example.atlassian.net/rest/api/2/field` The API will return a long string of JSON, which should be formatted into readable text (using a code editor, browser extension or ). - - The JSON returned from this URL will contain all of your Jira custom fields, most of which are irrelevant to DefectDojo and have values of `“Null”`. Each object in this API response corresponds to a different field in Jira. You will need to search for the objects that have `“name”` attributes which match the names of each Custom Field you created in the Jira UI, and then note the value of their “key” attribute. - - ![image](images/Using_Custom_Fields.png) - - Once you’ve found the matching object in the JSON output, you can determine the “key” value \- in this case, it's `customfield_10050`. - - Jira generates different key values for each Custom Field, but these key values do not change once created. If you create another Custom Field in the future, it will have a new key value. - - - **Expanding our Custom Field list:** - * “DefectDojo Custom URL Field” \= customfield\_10050 * “Another example of a Custom Field” \= customfield\_12345 * ... - - - ## Step 3 \- Finding the Custom Fields on a Jira Issue - Locate an Issue in Jira that contains the Custom Fields which you recorded in Step 2\. Copy the Issue Key for the title (should look similar to “`EXAMPLE-123`”) and navigate to the following URL: - - -[https://yourcompany\-example.atlassian.net/rest/api/2/issue/EXAMPLE\-123](https://yourcompany-example.atlassian.net/rest/api/2/issue/EXAMPLE-123) - - +`https://yourcompany\-example.atlassian.net/rest/api/2/issue/EXAMPLE\-123` This will return another string of JSON. - - As before, API output will contain lots of `customfield_##` object parameters with `null` values \- these are custom fields that Jira adds by default, which aren’t relevant to this issue. It will also contain `customfield_##` values that match the Custom Field Key values that you found in the previous step. Unlike with the Field Spec output, you won’t see names identifying any of these custom fields, which is why you needed to record the key values in Step 2\. - - ![image](images/Using_Custom_Fields_2.png) + **Example:** We know that `customfield_10050` represents the DefectDojo Custom URL Field because we recorded it in Step 2\. We can now see that `customfield_10050` contains a value of `“https://google.com”` in the `EXAMPLE-123` issue. - - - ## Step 4 \- Creating a JSON Field Reference from each Jira Custom Field Key - You’ll now need to take the value of each of the Custom Fields from your list and store them in a JSON object (to use as a reference). You can ignore any Custom Fields that don’t correspond to your list. - - This JSON object will contain all of the default values for new Jira Issues. We recommend using names that are easy for your team to recognize as ‘default’ values that need to be changed: ‘`change-me.com`’, ‘`Change this paragraph.`’ etc. - - - **Example:** - From step 3, we now know that Jira expects a URL string for "`customfield_10050`”. We can use this to build our example JSON object. - - Say we had also located a DefectDojo\-related short text field, which we identified as "`customfield_67890`”. We would look at this field in our second API output, look at the associated value, and reference the stored value in our example JSON object as well. ​ Your JSON object will start to look like this as you add more Custom Fields to it. - - - ``` { "customfield_10050": "https://change-me.com", @@ -164,27 +96,17 @@ Your JSON object will start to look like this as you add more Custom Fields to i Repeat this process until all of the DefectDojo\-relevant custom fields from Jira have been added to your JSON Field Reference. - - #### Data types \& Jira Syntax - Some fields, such as Date fields, may relate to multiple custom fields in Jira. If that is the case, you’ll need to add both fields to your JSON Field Reference. - - - ``` "customfield_10040": "1970-01-01", "customfield_10041": "1970-01-01T03:30:00.000+0200", ``` - Other fields, such as the Label field, may be tracked as a list of strings \- please make sure your JSON Field Reference uses a format that matches API output from Jira. - - - ``` // a list of custom labels on a Jira object "customfield_10042": [ @@ -194,14 +116,10 @@ Other fields, such as the Label field, may be tracked as a list of strings \- pl ], ``` - Other custom fields may contain additional, contextual information that should be removed from the Field Reference. For example, the Custom Multichoice Field contains an extra block in the API output, which you’ll need to remove, as this block stores the current value of the field. - * you should remove the extra object from this field: - - ``` "customfield_10047": [ { @@ -216,8 +134,6 @@ Other custom fields may contain additional, contextual information that should b ``` * instead, you can shorten this to the following and disregard the second part: - - ``` "customfield_10047": [ { @@ -226,15 +142,10 @@ Other custom fields may contain additional, contextual information that should b ] ``` - ### Example Completed Field Reference - Here is a complete JSON Field Reference, with in\-line comments explaining what each custom field pertains to. This is meant as an all\-encompassing example. Your JSON will contain different key values and data points depending on the Custom Values you want to use during issue creation. - - - ``` { "customfield_10050": "https://change-me.com", @@ -284,25 +195,16 @@ Here is a complete JSON Field Reference, with in\-line comments explaining what } ``` - ## Step 5 \- Adding the Custom Fields to a DefectDojo Product - You can now add these custom fields to the associated DefectDojo Product, in the Custom Fields section. Once again, - * Navigate to Edit Product \- defectdojo.com/product/ID/edit . * Navigate to Custom fields and paste the JSON Field Reference as plain text in the Custom Fields box. * Click ‘Submit’. - ## Step 6 \- Testing your Jira Custom Fields from a new Finding: - Now, when you create a new Finding in the Jira\-associated Product, Jira will automatically create all of these Custom Fields in Jira according to the JSON block contained within. These Custom Fields will be created with the default (“change\-me\-please”, etc.) values. - - Within the Product on DefectDojo, navigate to the Findings \> Add New Finding page. Make sure the Finding is both Active and Verified to ensure that it pushes to Jira, and then confirm on the Jira side that the Custom Fields are successfully created without any inconsistencies. - - diff --git a/docs/content/en/pro_reports/_index.md b/docs/content/en/share_your_findings/pro_reports/_index.md similarity index 97% rename from docs/content/en/pro_reports/_index.md rename to docs/content/en/share_your_findings/pro_reports/_index.md index b47cec1a57b..cca519206ac 100755 --- a/docs/content/en/pro_reports/_index.md +++ b/docs/content/en/share_your_findings/pro_reports/_index.md @@ -5,7 +5,7 @@ summary: "" date: 2023-09-07T16:06:50+02:00 lastmod: 2023-09-07T16:06:50+02:00 draft: false -weight: 9 +weight: 4 chapter: true sidebar: collapsed: true diff --git a/docs/content/en/pro_reports/using_the_report_builder.md b/docs/content/en/share_your_findings/pro_reports/using_the_report_builder.md similarity index 100% rename from docs/content/en/pro_reports/using_the_report_builder.md rename to docs/content/en/share_your_findings/pro_reports/using_the_report_builder.md diff --git a/docs/content/en/pro_reports/working_with_generated_reports.md b/docs/content/en/share_your_findings/pro_reports/working_with_generated_reports.md similarity index 100% rename from docs/content/en/pro_reports/working_with_generated_reports.md rename to docs/content/en/share_your_findings/pro_reports/working_with_generated_reports.md diff --git a/docs/content/en/working_with_findings/_index.md b/docs/content/en/working_with_findings/_index.md index f5ecca6649b..a7e0d7dc8c4 100644 --- a/docs/content/en/working_with_findings/_index.md +++ b/docs/content/en/working_with_findings/_index.md @@ -1,9 +1,9 @@ --- -title: "Working With Findings" +title: "🚩 Work With Findings" date: 2021-02-02T20:46:29+01:00 draft: false type: docs -weight: 8 +weight: 3 sidebar: - collapsed: true + collapsed: false --- diff --git a/docs/content/en/working_with_findings/finding_deduplication/_index.md b/docs/content/en/working_with_findings/finding_deduplication/_index.md index 7a5fb41a14b..3c51af604a8 100644 --- a/docs/content/en/working_with_findings/finding_deduplication/_index.md +++ b/docs/content/en/working_with_findings/finding_deduplication/_index.md @@ -3,4 +3,7 @@ title: "Finding Deduplication" date: 2021-02-02T20:46:29+01:00 draft: false type: docs +weight: 3 +sidebar: + collapsed: true --- diff --git a/docs/content/en/working_with_findings/finding_deduplication/about_deduplication.md b/docs/content/en/working_with_findings/finding_deduplication/about_deduplication.md index 7da2e72b4ba..7d105230130 100644 --- a/docs/content/en/working_with_findings/finding_deduplication/about_deduplication.md +++ b/docs/content/en/working_with_findings/finding_deduplication/about_deduplication.md @@ -1,73 +1,41 @@ --- title: "About Deduplication" description: "Deduplication fundamentals and key concepts" +weight: 1 --- DefectDojo is designed to ingest bulk reports from tools, creating one or more Findings based on the content of the report. When using DefectDojo, you’ll most likely be ingesting reports from the same tool on a regular basis, which means that duplicate Findings are highly likely. - - This is where Deduplication comes in, a Smart feature which you can set up to automatically manage duplicate Findings. - - - ## How DefectDojo handles duplicates - 1. First, you import **Test 1\.** Your report contains a vulnerability which is recorded as Finding A. 2. **Later, you import Test 2 which contains the same vulnerability. This will be recorded as Finding B, and Finding B will be marked as a duplicate of Finding A.** 3. Later still, you import **Test 3** which also contains that vulnerability. This will be recorded as Finding C, which will be marked as a duplicate of Finding A. By creating and marking Duplicates in this way, DefectDojo ensures that all the work for the ‘original’ vulnerability is centralized on the original Finding page, without creating separate contexts, or giving your team the impression that there are multiple separate vulnerabilities which need to be addressed. - - By default, these Tests would need to be nested under the same Product for Deduplication to be applied. If you wish, you can further limit the Deduplication scope to a single Engagement. - - Duplicate Findings are set as Inactive by default. This does not mean the Duplicate Finding itself is Inactive. Rather, this is so that your team only has a single active Finding to work on and remediate, with the implication being that once the original Finding is Mitigated, the Duplicates will also be Mitigated. - - - ## Deduplication vs Reimport - Deduplication and Reimport are similar processes but they have a key difference: - * When you Reimport to a Test, the Reimport process looks at incoming Findings, **filters and** **discards any matches**. Those matches will never be created as Findings or Finding Duplicates. * Deduplication is applied 'passively' on Findings that have already been created. It will identify duplicates in scope and **label them**, but it will not delete or discard the Finding unless 'Delete Deduplicate Findings' is enabled. * The 'reimport' action of discarding a Finding always happens before deduplication; DefectDojo **cannot deduplicate Findings that are never created** as a result of Reimport's filtering. - ## When are duplicates appropriate? - Duplicates are useful when you’re dealing with shared, but discrete Testing contexts. For example, if your Product is uploading Test results for two different repositories, which need to be compared, it’s useful to know which vulnerabilities are shared across those repositories. - - -However, if DefectDojo is creating excess duplicates, this can also be a sign that you need to adjust your import processes. - - +However, if DefectDojo is creating excess duplicates, this can also be a sign that you need to adjust your pipelines or import processes. ## What do my duplicates indicate? - * **The same vulnerability, but found in a different context:** this is the appropriate way to use Duplicate Findings. If you have many components which are affected by the same vulnerability, you would likely want to know which components are affected to understand the scope of the problem. ​ * **The same vulnerability, found in the same context**: better options exist for this case. If the Duplicate Finding does not give you any new context on the vulnerability, or if you find yourself frequently ignoring or deleting your duplicate Findings, this is a sign that your process can be improved. For example, Reimport allows you to effectively manage incoming reports from a CI/CD pipeline. Rather than create a completely new Finding object for each duplicate, Reimport will make a note of the incoming duplicate without creating the Duplicate Finding at all. - - - -# Next Steps: - - -* **Enable and configure Deduplication** from the System Settings page. -* Brush up on DefectDojo’s **Product and Engagement data models** to make sure that your environment is optimized for deduplication. -* Learn how to manage excess duplicates with the **Delete Deduplicate Findings** option. - - diff --git a/docs/content/en/working_with_findings/finding_deduplication/avoiding_duplicates_via_reimport.md b/docs/content/en/working_with_findings/finding_deduplication/avoiding_duplicates_via_reimport.md index 4339cae8b7a..414a16f3ed1 100644 --- a/docs/content/en/working_with_findings/finding_deduplication/avoiding_duplicates_via_reimport.md +++ b/docs/content/en/working_with_findings/finding_deduplication/avoiding_duplicates_via_reimport.md @@ -1,122 +1,69 @@ --- -title: "Avoiding Duplicates: Reimport Recurring Tests" +title: "Avoid Duplicates: Reimport Recurring Tests" description: "" +weight: 4 --- If you have a CI/CD pipeline, a daily scan process or any kind of repeated incoming report, setting up a Reimport process in advance is key to avoiding excessive duplicates. Reimport collapses the context and Findings associated with a recurring test into a single Test page, where you can review import history and track vulnerability changes across scans. - - 1. Create an Engagement to store the CI/CD results for the object you’re running CI/CD on. This could be a code repository where you have CI/CD actions set up to run. Generally, you want a separate Engagement set up for each pipeline so that you can quickly understand where the Finding results are coming from. ​ 2. Each CI/CD action will import data to DefectDojo in a separate step, so each of those should be mapped to a separate Test. For example, if each pipeline execution runs an NPM\-audit as well as a dependency scan, each scan result will need to flow into a Test (nested under the Engagement). ​ 3. You do not need to create a new Test each time the CI/CD action runs. Instead, you can **Reimport** data to the same test location. - -​ - - -# Reimport in action - - +## Reimport in action DefectDojo will compare the incoming scan data with the existing scan data, and then apply changes to the Findings contained within your Test as follows: ​ - - - -## Create Findings - +### Create Findings Any vulnerabilities which were not contained in the previous import will be added to the Test automatically as new Findings. ​ - - - -## Ignore existing Findings - +### Ignore existing Findings If any incoming Findings match Findings that already exist, the incoming Findings will be discarded rather than recorded as Duplicates. These Findings have been recorded already \- no need to add a new Finding object. The Test page will show these Findings as **Left Untouched**. ​ - - - -## Close Findings - +### Close Findings If there are any Findings that already exist in the Test but which are not present in the incoming report, you can choose to automatically set those Findings to Inactive and Mitigated (on the assumption that those vulnerabilities have been resolved since the previous import). The Test page will show these Findings as **Closed**. - - If you don’t want any Findings to be closed, you can disable this behavior on Reimport: - * Uncheck the **Close Old Findings** checkbox if using the UI -* Set **close\_old\_findings** to **False** if using the API -​ - -## Reopen Findings +* Set **close\_old\_findings** to **False** if using the API ​ +### Reopen Findings * If there are any Closed Findings which appear again in a Reimport, they will automatically be Reopened. The assumption is that these vulnerabilities have occurred again, despite previous mitigation. The Test page will track these Findings as **Reactivated**. - If you’re using a triage\-less scanner, or you don’t otherwise want Closed Findings to reactivate, you can disable this behavior on Reimport: - * Set **do\_not\_reactivate** to **True** if using the API * Check the **Do Not Reactivate** checkbox if using the UI - - - - -# Working with Import History - +## Working with Import History Import History for a given test is listed under the **Test Overview** header on the **Test** page. - - This table shows each Import or Reimport as a single line with a **Timestamp**, along with **Branch Tag, Build ID, Commit Hash** and **Version** columns if those were specified. - - - ![image](images/Avoiding_Duplicates_Reimport_Recurring_Tests.png) -## Actions - +### Actions This header indicates the actions taken by an Import/Reimport. - - * **\# created indicates the number of new Findings created at the time of Import/Reimport** * **\# closed shows the number of Findings that were closed by a Reimport (due to not existing in the incoming report).** * **\# left untouched shows the count of Open Findings which were unchanged by a Reimport (because they also existed in the incoming report).** * **\#** **reactivated** shows any Closed Findings which were reopened by an incoming Reimport. - - - - -# Why not simply use Import? - +## Why not simply use Import? Although both methods are possible, Import should be reserved for **new occurrences** of Findings and Data, while Reimport should be applied for **further iterations** of the same data. - - If your CI/CD pipeline runs an Import and creates a new Test object each time, each Import will give you a collection of discrete Findings which you will then need to manage as separate objects. Using Reimport alleviates this problem and eliminates the amount of ‘cleanup’ you’ll need to do when a vulnerability is resolved. - - Using Reimport allows you to store each recurring report on the same page, and maintains a continuity of each time new data was added to the Test. - - However, if you’re using the same scanning tool in multiple locations or contexts, it may be more appropriate to create a separate Test for each location or context. This depends on your preferred method of organization. - - - diff --git a/docs/content/en/working_with_findings/finding_deduplication/delete_deduplicates.md b/docs/content/en/working_with_findings/finding_deduplication/delete_deduplicates.md index dd5e0df4fbc..8a4cbed898b 100644 --- a/docs/content/en/working_with_findings/finding_deduplication/delete_deduplicates.md +++ b/docs/content/en/working_with_findings/finding_deduplication/delete_deduplicates.md @@ -1,36 +1,23 @@ --- title: "Delete Deduplicate Findings" description: "Remove excess duplicate Findings from DefectDojo" +weight: 3 --- If you have an excessive amount of duplicate Findings which you want to delete, you can set **Delete Deduplicate Findings** as an option in the **System Settings**. - - **Delete Deduplicate Findings**, combined with the **Maximum Duplicates** field allows DefectDojo to limit the amount of Duplicate Findings stored. When this field is enabled, DefectDojo will only keep a certain number of Duplicate Findings. - - - ## Which duplicates will be deleted? - The original Finding will never be deleted automatically from DefectDojo, but once the threshold for Maximum Duplicates is crossed, DefectDojo will automatically delete the oldest Duplicate Finding. - - - For example, let’s say that you had your Maximum Duplicates field set to ‘1’. - - 1. First, you import **Test 1\.** Your report contains a vulnerability which is recorded as Finding A. 2. **Later, you import Test 2 contains the same vulnerability. This will be recorded as Finding B, and Finding B will be marked as a duplicate of Finding A.** 3. Later still, you import **Test 3** which also contains that vulnerability. This will be recorded as Finding C, which will be marked as a duplicate of Finding A. At this time, Finding B will be deleted from DefectDojo as the threshold for maximum duplicates has been crossed. - -# Applying this setting - +## Applying this setting Applying **Delete Deduplicate Findings** will begin a deletion process immediately. This setting can be applied on the **System Settings** page. See Enabling Deduplication for more information. - diff --git a/docs/content/en/working_with_findings/finding_deduplication/enabling_deduplication_with_engagement.md b/docs/content/en/working_with_findings/finding_deduplication/enabling_deduplication_with_engagement.md deleted file mode 100644 index f7d2ac65984..00000000000 --- a/docs/content/en/working_with_findings/finding_deduplication/enabling_deduplication_with_engagement.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "Enabling Deduplication within an Engagement" -description: "" ---- - -Rather than Deduplicating across an entire Product, you can set a deduplication scope to be within a single Engagement exclusively. - - - -# Navigating to the Edit Engagement page - - - -* To enable Deduplication within a New Engagement, start with the **\+ New Engagement** option from the sidebar, which you can find by opening the **📥Engagements** sub\-menu. -​ - - -![image](images/Enabling_Deduplication_within_an_Engagement.png) - -​ -* To enable Deduplication within an existing Engagement: from the **All Engagements** page, select the **Edit Engagement** option from the **⋮** menu. -​ - - -![image](images/Enabling_Deduplication_within_an_Engagement_2.png) -* You can also open this menu from a specific **Engagement Page** by clicking the ⚙️Gear icon in the top\-right hand corner. -​ - - -![image](images/Enabling_Deduplication_within_an_Engagement_3.png) - - -# Completing the Edit Engagement form - - -1. Start by opening the **Optional Fields \+** menu at the bottom of the **Edit Engagement** form. -2. Click the ☐ **Deduplication Within This Engagement** box. -3. Submit the form. - -![image](images/Enabling_Deduplication_within_an_Engagement_4.png) \ No newline at end of file diff --git a/docs/content/en/working_with_findings/finding_deduplication/enabling_product_deduplication.md b/docs/content/en/working_with_findings/finding_deduplication/enabling_product_deduplication.md index a9ea4204757..0c8c19a7847 100644 --- a/docs/content/en/working_with_findings/finding_deduplication/enabling_product_deduplication.md +++ b/docs/content/en/working_with_findings/finding_deduplication/enabling_product_deduplication.md @@ -1,11 +1,14 @@ --- -title: "Enabling Product-Level Deduplication" +title: "Enabling Deduplication" description: "How to enable Deduplication at the Product level" +weight: 2 --- -Deduplication can be implemented at either a Product level or at a more narrow Engagement level. This article describes the more common approach of deduplicating within a single Product. +Deduplication can be implemented at either a Product level or at a more narrow Engagement level. -1. Start by navigating to the System Settings page. This is nested under **Settings \> Pro Settings \> ⚙️System Settings** on the sidebar. +## Deduplication for Products + +1. Start by navigating to the System Settings page. This is nested under **Settings \> Pro Settings \> ⚙️ System Settings** on the sidebar. ![image](images/Enabling_Product-Level_Deduplication.png) @@ -13,14 +16,40 @@ Deduplication can be implemented at either a Product level or at a more narrow E ​ ![image](images/Enabling_Product-Level_Deduplication_2.png) -## Enable Finding Deduplication +### Enable Finding Deduplication **Enable Finding Deduplication** will turn on the Deduplication Algorithm for all Findings. Deduplication will be triggered on all subsequent imports \- when this happens, DefectDojo will look at any Findings contained in the destination Product, and deduplicate as per your settings. -## Delete Deduplicate Findings +### Delete Deduplicate Findings **Delete Deduplicate Findings**, combined with the **Maximum Duplicates** field allows DefectDojo to limit the amount of Duplicate Findings stored. When this field is enabled, DefectDojo will only keep a certain number of Duplicate Findings. Applying **Delete Deduplicate Findings** will begin a deletion process immediately. DefectDojo will look at each Finding with Duplicates recorded, and will delete old duplicate Findings until the Maximum Duplicate number has been reached. -For more information on how DefectDojo determines what to delete, see our guide to **[Deleting Deduplicate Findings](https://docs.defectdojo.com/en/working_with_findings/finding_deduplication/delete-deduplicate-findings/).** +For more information on how DefectDojo determines what to delete, see our guide to **[Deleting Deduplicate Findings](../delete_deduplicates/).** + +## Deduplication for Engagements + +Rather than Deduplicating across an entire Product, you can set a deduplication scope to be within a single Engagement exclusively. + +### Edit Engagement page + +* To enable Deduplication within a New Engagement, start with the **\+ New Engagement** option from the sidebar, which you can find by opening the **📥Engagements** sub\-menu. +​ +![image](images/Enabling_Deduplication_within_an_Engagement.png) + +* To enable Deduplication within an existing Engagement: from the **All Engagements** page, select the **Edit Engagement** option from the **⋮** menu. +​ +![image](images/Enabling_Deduplication_within_an_Engagement_2.png) + +* You can also open this menu from a specific **Engagement Page** by clicking the ⚙️Gear icon in the top\-right hand corner. +​ +![image](images/Enabling_Deduplication_within_an_Engagement_3.png) + +### Completing the Edit Engagement form + +1. Start by opening the **Optional Fields \+** menu at the bottom of the **Edit Engagement** form. +2. Click the ☐ **Deduplication Within This Engagement** box. +3. Submit the form. + +![image](images/Enabling_Deduplication_within_an_Engagement_4.png) \ No newline at end of file diff --git a/docs/content/en/working_with_findings/findings_workflows/_index.md b/docs/content/en/working_with_findings/findings_workflows/_index.md index 21f410a14f3..e6fe74549c5 100644 --- a/docs/content/en/working_with_findings/findings_workflows/_index.md +++ b/docs/content/en/working_with_findings/findings_workflows/_index.md @@ -1,6 +1,9 @@ --- -title: "Findings Workflows" +title: "Finding Workflows & Status" date: 2021-02-02T20:46:29+01:00 draft: false +weight: 3 type: docs +sidebar: + collapsed: true --- diff --git a/docs/content/en/working_with_findings/findings_workflows/bulk_edit_findings.md b/docs/content/en/working_with_findings/findings_workflows/bulk_edit_findings.md deleted file mode 100644 index 164ed2df2c0..00000000000 --- a/docs/content/en/working_with_findings/findings_workflows/bulk_edit_findings.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "Bulk Editing Findings" -description: "Quickly update one or more Findings from a table" ---- - -Findings can be edited in bulk from a Finding List, which can be found either on the Findings page itself, or from within a Test. - - - -# Selecting Findings for Bulk Edit - - -When looking at a table with multiple Findings, such as the ‘Findings From \[tool]’ table on a Test Page or the All Findings list, you can use the checkboxes next to Findings to mark them for Bulk Edit. - - - -Selecting one or more Findings in this way will open the (hidden) Bulk Edit menu, which contains the following four options: - - -* **Bulk Update Actions**: apply metadata changes to the selected Findings. -* **Risk Acceptance Actions: create a Full Risk Acceptance to govern the selected Findings, or add the Findings to an existing Full Risk Acceptance** -* **Finding Group Actions: create a Finding Group made up of the selected Findings. Note that Finding Groups can only be created within an individual Test.** -* **Delete: delete the selected Findings. You will need to confirm this action in a new window.** - - -![image](images/Bulk_Editing_Findings.png) -## Bulk Update Actions - - -Through the Bulk Update Actions menu, you can apply the following changes to any Findings you have selected: - - -* Update the **Severity** -* Apply a new **Finding Status** -* Change the Discovery or Planned Remediation Date of the Findings -* Add a **Simple Risk Acceptance,** if the option is enabled at the Product level -* Apply **Tags** or **Notes** to all of the selected Findings. - - -![image](images/Bulk_Editing_Findings_2.png) - -## Risk Acceptance Actions - - -This page allows you to add a **Full Risk Acceptance** to the selected Findings. You can either create a new **Full Risk Acceptance** or add the Findings to one that already exists. - - -![image](images/Bulk_Editing_Findings_3.png) - -## Finding Group Actions - - -This page allows you to create a new Finding Group from the Selected Findings, or add them to an existing Finding Group. - - -However, Finding Groups can only be created within an individual **Test** \- Findings from different Tests, Engagements or Products cannot be added to the same Finding Group. - - - -![image](images/Bulk_Editing_Findings_4.png) - -## Bulk Delete Findings - - -You can also Delete selected Findings by clicking on the red **Delete** button. A popup window will appear asking you to confirm this decision. - - - -![image](images/Bulk_Editing_Findings_5.png) - diff --git a/docs/content/en/working_with_findings/findings_workflows/create_findings_manually.md b/docs/content/en/working_with_findings/findings_workflows/create_findings_manually.md index cf9917ff25b..639ac411fd3 100644 --- a/docs/content/en/working_with_findings/findings_workflows/create_findings_manually.md +++ b/docs/content/en/working_with_findings/findings_workflows/create_findings_manually.md @@ -1,20 +1,15 @@ --- title: "Creating Findings Manually" description: "Track vulnerability information without using a scan tool" +weight: 2 --- Normally, most of the Findings in your environment will be imported from other security tools. If you wish, you can add manual Finding entries as well, if you have vulnerabilities or work you wish to manage that was not created from a scan tool. - - 1. From the DefectDojo Sidebar, open the New Finding link by clicking **Manage \> Findings \> New Finding**. ​ - - ![image](images/Creating_Findings_Manually.png) -​ 2. This opens the **New Finding** form, which you can fill out with any relevant information surrounding your Finding. You will need to assign this Finding to a previously created Test in DefectDojo. - -![image](images/Creating_Findings_Manually_2.png) \ No newline at end of file +![image](images/Creating_Findings_Manually_2.png) diff --git a/docs/content/en/working_with_findings/findings_workflows/editing_findings.md b/docs/content/en/working_with_findings/findings_workflows/editing_findings.md index c708cde96e7..3602779bd8c 100644 --- a/docs/content/en/working_with_findings/findings_workflows/editing_findings.md +++ b/docs/content/en/working_with_findings/findings_workflows/editing_findings.md @@ -1,28 +1,22 @@ --- title: "Editing Findings" description: "Change a Finding’s Status, or add more metadata as you resolve an issue" +weight: 1 --- If you want to add notes or update the language on a Finding to be more relevant to the current situation, you can do so through the Edit Finding form. - - -# Opening the Edit Finding Form - +## Open the Edit Finding Form You can update a Finding by opening the **⚙️ Gear** **Menu** in the top and clicking **Edit Finding.** - - ![image](images/Editing_Findings.png) This will open the **Edit Finding** form, where you can edit the metadata, change the Finding’s Status and add additional information. - - ![image](images/Editing_Findings_2.png) -## Edit Finding Form: Fields +### Edit Finding Form: Fields * **"Test" cannot be edited:** Findings always have to be associated with a Test object, and cannot be moved out of that context. However, the Engagement containing a Test can be moved to another Product. ​ @@ -41,3 +35,52 @@ This will open the **Edit Finding** form, where you can edit the metadata, chang * **Active / Verified** are the primary Finding statuses used by a tool. Active Findings are Findings that are currently active in your network and have been reported by a tool. Verified means that this Finding has been confirmed to exist by a team member. ​ * **SAST / DAST** are labels used to organize your Findings into the context they were discovered in. Generally, this label is populated based on the scanning tool used, but you can adjust this to a more accurate level (for example, if the Finding was found by both a SAST and a DAST tool). + +## Bulk Edit Findings + +Findings can be edited in bulk from a Finding List, which can be found either on the Findings page itself, or from within a Test. + +### Selecting Findings for Bulk Edit + +When looking at a table with multiple Findings, such as the ‘Findings From \[tool]’ table on a Test Page or the All Findings list, you can use the checkboxes next to Findings to mark them for Bulk Edit. + +Selecting one or more Findings in this way will open the (hidden) Bulk Edit menu, which contains the following four options: + +* **Bulk Update Actions**: apply metadata changes to the selected Findings. +* **Risk Acceptance Actions: create a Full Risk Acceptance to govern the selected Findings, or add the Findings to an existing Full Risk Acceptance** +* **Finding Group Actions: create a Finding Group made up of the selected Findings. Note that Finding Groups can only be created within an individual Test.** +* **Delete: delete the selected Findings. You will need to confirm this action in a new window.** + +![image](images/Bulk_Editing_Findings.png) + +### Bulk Update Actions + +Through the Bulk Update Actions menu, you can apply the following changes to any Findings you have selected: + +* Update the **Severity** +* Apply a new **Finding Status** +* Change the Discovery or Planned Remediation Date of the Findings +* Add a **Simple Risk Acceptance,** if the option is enabled at the Product level +* Apply **Tags** or **Notes** to all of the selected Findings. + +![image](images/Bulk_Editing_Findings_2.png) + +### Risk Acceptance Actions + +This page allows you to add a **Full Risk Acceptance** to the selected Findings. You can either create a new **Full Risk Acceptance** or add the Findings to one that already exists. + +![image](images/Bulk_Editing_Findings_3.png) + +### Finding Group Actions + +This page allows you to create a new Finding Group from the Selected Findings, or add them to an existing Finding Group. + +However, Finding Groups can only be created within an individual **Test** \- Findings from different Tests, Engagements or Products cannot be added to the same Finding Group. + +![image](images/Bulk_Editing_Findings_4.png) + +### Bulk Delete Findings + +You can also Delete selected Findings by clicking on the red **Delete** button. A popup window will appear asking you to confirm this decision. + +![image](images/Bulk_Editing_Findings_5.png) \ No newline at end of file diff --git a/docs/content/en/working_with_findings/finding_status_deduplication.md b/docs/content/en/working_with_findings/findings_workflows/finding_status_definitions.md similarity index 96% rename from docs/content/en/working_with_findings/finding_status_deduplication.md rename to docs/content/en/working_with_findings/findings_workflows/finding_status_definitions.md index 9322c289658..4dfa444d403 100644 --- a/docs/content/en/working_with_findings/finding_status_deduplication.md +++ b/docs/content/en/working_with_findings/findings_workflows/finding_status_definitions.md @@ -1,140 +1,79 @@ --- title: "Finding Status Definitions" description: "A quick reference to Finding status: Open, Verified, Accepted.." +weight: 2 --- Each Finding created in DefectDojo has a Status which communicates relevant information. Statuses help your team keep track of their progress in resolving issues. - - Each Finding status has a context\-specific meaning which will need to be defined by your own team. These are our suggestions, but your team's usage may vary. - - ## **Active** **Findings** - ‘This Finding has been discovered by a scanning tool.’ - - By default, any new Finding created in DefectDojo will be labeled as **Active**. Active in this case means ‘this is a new Finding that DefectDojo has not recorded on a past import’. If a Finding has been Mitigated in the past, but appears in a scan again in the future, the status of that Finding will reopen to reflect that the vulnerability has returned. - - ## **Verified Findings** - ‘This Finding has been confirmed by our team to exist.’ - - Just because a tool records a problem does not necessarily mean the Finding requires engineering attention. Therefore, new Findings are also labeled as **Unverified** by default. - - If you’re able to confirm that the Finding does exist, you can mark it as **Verified**. - - If you don’t need to manually verify each Finding, you can automatically mark them as Verified during import, or disregard this Status. - - ## **Open Findings** - ‘There is work to be done on these Findings.’ - - Once a Finding is **Active**, it will be labeled as an **Open** Finding, regardless of whether or not it has been **Verified.** - - Open Findings can be seen from the **Findings \> Open Findings** view of DefectDojo. - - ## **Closed Findings** - -**‘**The Vulnerability recorded here is no longer active’. - - +'The Vulnerability recorded here is no longer active’. Once the work on a Finding is complete, you can manually Close it from the Close Findings option. Alternatively, if a scan is re\-imported into DefectDojo which does not contain a previously\-recorded Finding, the previously\-recorded Finding will automatically close. - - ## **Under Review** - ‘I have sent this Finding to one or more team members to look at.’ - - When a Finding is Under Review, it needs to be reviewed by a team member. You can put a Finding under review by Selecting **Request Peer Review** from the Finding’s drop\-down menu. - - - ![image](images/Finding_Status_Definitions.png) ## **Risk Accepted** - ‘Our team has evaluated the risk associated with this Finding, and we’ve agreed that we can safely delay fixing it.’ - - Findings cannot always be remediated or addressed for various reasons. You can add a Risk Acceptance to a Finding with the Add Risk Acceptance option. Risk Acceptances allow you to upload files and enter notes to support a Risk Acceptance decision. - - Risk Acceptances have expiry dates, at which time you can reevaluate the impact of the Finding and decide what to do next. - - +For more information on Risk Acceptances, see our [Guide](../risk_acceptances). ## **Out Of Scope** - ‘This Finding was discovered by our scanning tool, but detecting this kind of vulnerability was not the direct goal of our test.’ - - When you mark a Finding as Out Of Scope, you are indicating that it is not directly relevant to the Engagement or Test it is contained within. - - If you have a testing and remediation effort related to a specific aspect of your software, you can use this Status to indicate that this Finding is not part of your effort. - - - ## **False Positive** - ‘This Finding was discovered by our scanning tool, but after reviewing the Finding we have discovered that this reported vulnerability does not exist.’ - - Once you’ve reviewed a Finding, you might discover that the vulnerability reported does not actually exist. The False Positive status allows DefectDojo to keep track of this information, and future imports will also apply the False Positive status to this Finding. - - If a different scanning tool finds a similar Finding, it will not be recorded as a False Positive. DefectDojo can only compare Findings within the same tool to determine if a Finding has already been recorded. - - - ## **Inactive** - ‘This Finding was discovered previously but it was either mediated or does not require immediate attention.’ - - If a Finding is marked as Inactive, this means that the issue currently has no impact on the software environment and does not need to be addressed. This status does not necessarily mean that the issue has been resolved. - diff --git a/docs/content/en/working_with_findings/findings_workflows/manage_duplicate_findings.md b/docs/content/en/working_with_findings/findings_workflows/manage_duplicate_findings.md index a9b420387dc..b1eac050c2f 100644 --- a/docs/content/en/working_with_findings/findings_workflows/manage_duplicate_findings.md +++ b/docs/content/en/working_with_findings/findings_workflows/manage_duplicate_findings.md @@ -1,6 +1,7 @@ --- title: "Manage Duplicate Findings" description: "How to discover and correct redundancies in your workflow - using Deduplication, Reimiport and other Smart features" +weight: 3 --- One of DefectDojo’s strengths is that the data model can accommodate many different use\-cases and applications. You’ll likely change your approach as you master the software and discover ways to optimize your workflow. @@ -35,7 +36,7 @@ DefectDojo has two methods for importing test data to create Findings: **Import* Each time you import new vulnerability reports into DefectDojo, those reports will be stored in a Test object. A Test object can be created by a user ahead of time to hold a future **Import**. If a user wants to import data without specifying a Test destination, a new Test will be created to store the incoming report. -Tests are flexible objects, and although they can only hold one *kind* of report, they can handle multiple instances of that same report through the **Reimport** method. To learn more about Reimport, see our **[article](https://docs.defectdojo.com/en/connecting_your_tools/import_scan_files/using_reimport/)** on this topic. +Tests are flexible objects, and although they can only hold one *kind* of report, they can handle multiple instances of that same report through the **Reimport** method. To learn more about Reimport, see our **[article](/en/connecting_your_tools/import_scan_files/using_reimport)** on this topic. ## When are Duplicate Findings acceptable? diff --git a/docs/content/en/working_with_findings/risk_acceptances.md b/docs/content/en/working_with_findings/findings_workflows/risk_acceptances.md similarity index 94% rename from docs/content/en/working_with_findings/risk_acceptances.md rename to docs/content/en/working_with_findings/findings_workflows/risk_acceptances.md index b82321af917..9746e864a81 100644 --- a/docs/content/en/working_with_findings/risk_acceptances.md +++ b/docs/content/en/working_with_findings/findings_workflows/risk_acceptances.md @@ -1,26 +1,19 @@ --- -title: "Risk Acceptances" +title: "Using Risk Acceptances" description: "Adding Simple and Full Risk Acceptances to your Findings" --- ‘Risk Accepted’ is a special status that can be applied to a Finding in two ways: - * **Risk Accepted** can be freely applied as a Status **if ‘Simple Risk Acceptance’** is enabled. * You can also create **Full Risk Acceptances**, which are objects stored in DefectDojo to capture a risk acceptance decision made by your team. - A **Full Risk Acceptance** is a special object in DefectDojo, used when Active Findings are ‘backlogged’ by your team. Often, both security teams and developer teams will decide when a Risk Acceptance is appropriate. In DefectDojo, your team can create Risk Acceptances which capture the internal decision making process and can be used as a source of truth. - - ## About Full Risk Acceptances - - Each Full Risk Acceptance can store details about the following: - * The Security team’s recommendation to a Product owner or other stakeholder * Description of the decision made by stakeholders * The DefectDojo user involved in the decision making process @@ -28,22 +21,14 @@ Each Full Risk Acceptance can store details about the following: Findings can be added to a Risk Acceptance regardless of the Product, Test or Engagement they are in. - - Any Findings associated with a Full Risk Acceptance will be set to **Inactive**, **Risk Accepted**. - - Generally, any Risk Acceptances should follow your internal security policy and be re\-examined at an appropriate time. As a result, Risk Acceptances also have expiration dates. Once a Risk Acceptance expires, any Findings will be set to Active again. - - -## Adding a new Full Risk Acceptance - +### Add a new Full Risk Acceptance Risk Acceptances can be added to a Finding in two ways: - * Using the **Bulk Edit** menu, when looking at a list of Findings * Using the **Add Risk Acceptance** button on an individual Finding @@ -53,40 +38,24 @@ Risk Acceptances can be added to a Finding in two ways: ![image](images/Risk_Acceptances_2.png) To create a New Risk Acceptance, complete the Add to New Risk Acceptance form on a Finding you wish to Risk Accept. - -# - - ![image](images/Risk_Acceptances_3.png) -2. Select the **Owner** of the Risk Acceptance \- this is generally meant to be the DefectDojo team member responsible for the decision to Risk Accept the Finding + +2. Select the **Owner** of the Risk Acceptance \- this is generally meant to be the DefectDojo team member responsible for the decision to Risk Accept the Finding. 3. Complete the **Optional Fields** with any relevant information. If you want to set an Expiration Date or a Warning for that Expiration Date, you can do so here as well. If you don’t specify a date, the Default Risk Acceptance / Default Risk Acceptance Expiration days will be used from the **System Settings** page. 4. Select whether you want to **Reactivate** or **Restart SLAs** on any associated Findings once the Risk Acceptance expires. - -# Simple Risk Acceptances - +## Simple Risk Acceptances If you don’t want to create a Full Risk Acceptance object and would prefer to simply **apply a status of ‘Risk Accepted’ to a Finding**, you can do so through the Bulk Edit menu. This method is called **Simple Risk Acceptance**. - - Before you can apply a Simple Risk Acceptance to a Finding, Simple Risk Acceptance will need to be enabled at the Product level. This setting can be found on the **Edit Product Form**. - - -## Applying a Simple Risk Acceptance - +### Apply a Simple Risk Acceptance With one or more Findings selected, open **Bulk Update Actions**. Navigate to **Simple Risk Acceptance Status** and select either **Accept Risk** or **Unaccept Risk**. Once you have submitted the Bulk Update, ‘Risk Accepted’ will be applied to any Findings selected without the need to create a Risk Acceptance object (with an expiration date or additional metadata). - - - -# Locating Risk Accepted Findings - +## Locating Risk Accepted Findings The sidebar in DefectDojo allows you to quickly find any Risk Accepted Findings by opening **Manage \> Risk Acceptances.** From here you can view the Risk Acceptance objects themselves, or view a list of Risk Accepted Findings. - - ![image](images/Risk_Acceptances_4.png) diff --git a/docs/content/en/working_with_findings/intro_to_findings.md b/docs/content/en/working_with_findings/intro_to_findings.md index 058028ac681..aea8533378d 100644 --- a/docs/content/en/working_with_findings/intro_to_findings.md +++ b/docs/content/en/working_with_findings/intro_to_findings.md @@ -1,6 +1,7 @@ --- title: "Introduction to Findings" description: "The main workflow and vulnerability tracking system of DefectDojo" +weight: 1 --- Findings are the main way that DefectDojo standardizes and guides the reporting and remediation process of your security tools. Regardless of whether a vulnerability was reported in SonarQube, Acunetix, or your team’s custom tool, Findings give you the ability to manage each vulnerability in the same way. @@ -73,7 +74,7 @@ If you’re in charge of security reporting for many different contexts, softwar * Each Product in DefectDojo can have a different SLA configuration, so that you can instantly flag Findings that are discovered in Production or other highly sensitive environments. * You can create a report directly from a **Product Type, Product, Engagement or Test** to ‘zoom in and out’ of your security context. **Tests** contain results from a single tool, **Engagements** can combine multiple Tests, **Products** can contain multiple Engagements, **Product Types** can contain multiple Products. -For more information on creating a Report, see our guides to **[Custom Reporting](https://docs.defectdojo.com/en/pro_reports/using_the_report_builder/)**. +For more information on creating a Report, see our guides to **[Custom Reporting](/en/pro_reports/using_the_report_builder/)**. ### Triage Vulnerabilities using Finding Status @@ -104,6 +105,5 @@ If a Finding’s EPSS score changes (i.e. the related Finding becomes more explo # Next Steps: -* Learn how to add or adjust data on your Findings through the **[Edit Findings](https://docs.defectdojo.com/en/working_with_findings/findings_workflows/editing-findings/)** menu. -* Learn how to update Findings in bulk using the **[Bulk Edit](https://docs.defectdojo.com/en/working_with_findings/findings_workflows/bulk-editing-findings/)** menu. -* Learn how to apply **[Risk Acceptances](https://docs.defectdojo.com/en/working_with_findings/risk-acceptances/)** to Findings which create a record of sensitive decisions made surrounding risk\-accepted vulnerabilities. +* Learn how to add or adjust data on your Findings: **[Editing Findings](../findings_workflows/editing_findings)**. +* Learn how to apply **[Risk Acceptances](../findings_workflows/risk_acceptances/)** to Findings which create a record of sensitive decisions made surrounding risk\-accepted vulnerabilities. diff --git a/docs/content/en/working_with_findings/organizing_engagements_tests/_index.md b/docs/content/en/working_with_findings/organizing_engagements_tests/_index.md index 73f51afe3ed..93fd562d706 100644 --- a/docs/content/en/working_with_findings/organizing_engagements_tests/_index.md +++ b/docs/content/en/working_with_findings/organizing_engagements_tests/_index.md @@ -1,6 +1,9 @@ --- -title: "Organizing Engagements and Tests" +title: "Organizing Data" date: 2021-02-02T20:46:29+01:00 draft: false +weight: 4 type: docs +sidebar: + collapsed: false --- diff --git a/docs/content/en/working_with_findings/organizing_engagements_tests/product_health_grade.md b/docs/content/en/working_with_findings/organizing_engagements_tests/product_health_grade.md index 4e951611d19..30e883f5e3c 100644 --- a/docs/content/en/working_with_findings/organizing_engagements_tests/product_health_grade.md +++ b/docs/content/en/working_with_findings/organizing_engagements_tests/product_health_grade.md @@ -5,25 +5,14 @@ description: "How DefectDojo calculates a Product Health Grade" DefectDojo can calculate a grade for your Products based on the amount of Findings contained within. Grades are ranked from A \- F. - - Note that only Active \& Verified Findings contribute to a Product Grade \- unverified Findings will not have an impact. - - - -# Product Grade Calculation - +## Product Grade Calculation Every Product Grade starts at 100 (with no Findings). - - Grade calculation starts by looking at the highest **Severity** level of a Finding in a Product, and reducing the Product Health to a base level. - - - | **Highest Severity Level of a Finding** | **Maximum Grade** | | --- | --- | | **Critical** | **40** | @@ -33,13 +22,9 @@ Grade calculation starts by looking at the highest **Severity** level of a Findi Further points are then deducted from the Grade for each additional Finding: - - - | **Severity Level of an additional Finding** | **Grade Reduced by** | | --- | --- | | **Critical** | **5** | | **High** | **3** | | **Medium** | **2** | | **Low** | **1** | - diff --git a/docs/content/en/working_with_findings/organizing_engagements_tests/product_hierarchy.md b/docs/content/en/working_with_findings/organizing_engagements_tests/product_hierarchy.md index f14068f135a..b7bc370a465 100644 --- a/docs/content/en/working_with_findings/organizing_engagements_tests/product_hierarchy.md +++ b/docs/content/en/working_with_findings/organizing_engagements_tests/product_hierarchy.md @@ -1,23 +1,21 @@ --- title: "Product Hierarchy: Overview" description: "Understand Product Types, Products, Engagements, Tests and Findings" +weight: 1 --- DefectDojo uses five main data classes to organize your work: **Product Types, Products**, **Engagements**, **Tests**, and **Findings**. - - DefectDojo is made to be flexible to conform to your team, rather than making your team conform to the tool. You'll be able to design a robust, adaptable workspace once you understand how these data classes can be used to organize your work. +### Product Hierarchy Diagram +![image](images/dd-hierarchy.png) - -# **Product Types** - +## **Product Types** The first category of data you'll need to set up in DefectDojo is a Product Type. Product Types are intended to categorize Products in a specific way. This could be: - * by business domain * by development team * by security team @@ -25,11 +23,7 @@ The first category of data you'll need to set up in DefectDojo is a Product Type ![image](images/Product_Hierarchy_Overview.png) Product Types can have Role\-Based Access Control rules applied, which limit team members' ability to view and interact with their data (including any underlying Products with Engagement, Test and Finding data). For more information on user roles, see our **Introduction To Roles** article. - - - -## What can a Product Type represent? - +#### What can a Product Type represent? * If a particular software project has many distinct deployments or versions, it may be worth creating a single Product Type which covers the scope of the entire project, and having each version exist as individual Products. ​ @@ -37,18 +31,12 @@ Product Types can have Role\-Based Access Control rules applied, which limit tea ​ * Ultimately, it's your decision how you wish to organize your Products, and what you Product Type to represent. Your DefectDojo hierarchy may need to change to fit your security teams' needs. - - -# **Products** - +## **Products** A **Product** in DefectDojo is intended to represent any project, program, or product that you are currently testing. The Product hosts all of the security work and testing history related to the underlying goal. - - ![image](images/Product_Hierarchy_Overview_2.png) - * a unique **Name** * a **Description** * a product **Type** @@ -56,45 +44,28 @@ A **Product** in DefectDojo is intended to represent any project, program, or pr Products can be as broad or as specific in scope as you wish. By default, Products are completely separate objects in the hierarchy, but they can be grouped together by **Product Type**. - - Products are 'walled\-off' and do not interact with other Products. DefectDojo's Smart Features, such as **Deduplication**, only apply within the context of a single Product. - - Like **Product Types**, **Products** can have Role\-Based Access Control rules applied, which limit team members' ability to view and interact with them (as well as any underlying Engagement, Test and Finding data). For more information on user roles, see our **Introduction To Roles** article. - - - -## What can a Product represent? - +#### What can a Product represent? DefectDojo's concept of a 'Product' will not necessarily correspond 1:1 to what your organization would refer to as a 'Product'. Software development is complex, and security needs can vary greatly even within the scope of a single piece of software. - - The following scenarios are good reasons to consider creating a separate DefectDojo Product: - * "**ExampleProduct**" has a Windows version, a Mac version, and a Cloud version * "**ExampleProduct 1\.0**" uses completely different software components from "**ExampleProduct 2\.0**", and both versions are actively supported by your company. * The team assigned to work on "**ExampleProduct version A**" is different than the product team assigned to work on "**ExampleProduct version B**", and needs to have different security permissions assigned as a result. - These variations within a single Product can also be handled at the Engagement level. Note that Engagements don't have access control in the way Products and Product Types do. - -# **Engagements** - +## **Engagements** Once a Product is set up, you can begin creating and scheduling Engagements. Engagements are meant to represent moments in time when testing is taking place, and contain one or more **Tests**. - - Engagements always have: - * a unique **Name** * target **Start and End dates** * **Status** (Not Started, In Progress, Cancelled, Completed...) @@ -103,66 +74,43 @@ Engagements always have: There are two types of Engagement: **Interactive** and **CI/CD**. - * An **Interactive Engagement** is typically run by an engineer. Interactive Engagements are focused on testing the application while the app is running, using an automated test, human tester, or any activity “interacting” with the application functionality. See [OWASP's definition of IAST](https://owasp.org/www-project-devsecops-guideline/latest/02c-Interactive-Application-Security-Testing#:~:text=Interactive%20Application%20Security%20Testing,interacting%E2%80%9D%20with%20the%20application%20functionality.). * A **CI/CD Engagement** is for automated integration with a CI/CD pipeline. CI/CD Engagements are meant to import data as an automated action, triggered by a step in the release process. Engagements can be tracked using DefectDojo's **Calendar** view. - - - -## What can an Engagement represent? - +#### What can an Engagement represent? Engagements are meant to represent groups of related testing efforts. How you wish to group your testing efforts depends on your approach. - - If you have a planned testing effort scheduled, an Engagement offers you a place to store all of the related results. Here's an example of this kind of Engagement: - #### **Engagement:** ExampleSoftware 1\.5\.2 \- Interactive Testing Effort - *In this example, a security team runs multiple tests on the same day as part of a software release.* - * **Test:** Nessus Scan Results (March 12\) * **Test:** NPM Scan Audit Results (March 12\) * **Test:** Snyk Scan Results (March 12\) ​ - - You can also organize CI/CD Test results within an Engagement. These kinds of Engagements are 'Open\-Ended' meaning that they don't have a date, and will instead add additional data each time the associated CI/CD actions are run. - #### Engagement: ExampleSoftware CI/CD Testing - *In this example, multiple CI/CD scans are automatically imported as Tests every time a new software release is created.* - * Test: 1\.5\.2 Scan Results (March 12\) * Test: 1\.5\.1 Scan Results (March 3\) * Test: 1\.5\.0 Scan Results (February 14\) - - Engagements can be organized however works best for your team. All Engagements nested under a Product can be viewed by the team assigned to work on the Product. - - -# **Tests** - +## **Tests** Tests are a grouping of activities conducted by engineers to attempt to discover flaws in a product. - - Tests always have: - * a unique **Test Title** * a specific **Test Type (**API Test, Nessus Scan, etc) * an associated test **Environment** @@ -170,50 +118,30 @@ Tests always have: Tests can be created in different ways. Scan data can be directly imported to an Engagement, which will then create a new Test containing that data. Tests can also be created in advance without scan data, as part of planning future Engagements. - - - -## **How do Tests interact with each other?** - +#### **How do Tests interact with each other?** Tests take your testing data and group it into Findings. Generally, security teams will be running the same testing effort repeatedly, and Tests in DefectDojo allow you to handle this process in an elegant way. - - **Previously imported tests can be reimported** \- If you're running the same type of test within the same Engagement context, you can Reimport the test results after each completed scan. DefectDojo will compare the Reimported data to the existing result, and will not create new Findings if duplicates exist in the scan data. - - **Tests can be imported separately** \- If you run the same test on a Product within separate Engagements, DefectDojo will still compare the data with previous Tests to find duplicate Findings. This allows you to keep track of previously mitigated or risk\-accepted Findings. - - If a Test is added directly to a Product without an Engagement, a generic Engagement will be created automatically to contain the Test. This allows for ad\-hoc data imports. - - **Examples of Tests:** - * Burp Scan from Oct. 29, 2015 to Oct. 29, 2015 * Nessus Scan from Oct. 31, 2015 to Oct. 31, 2015 * API Test from Oct. 15, 2015 to Oct. 20, 2015 - -# **Findings** - +## **Findings** Once data has been added uploaded to a Test, the results of that data will be listed in the Test as individual **Findings** for review. - - A finding represents a specific flaw discovered while testing. - - Findings always have: - * a unique **Finding Name** * the **Date** they were uncovered * multiple associated **Statuses**, such as Active, Verified or False Positive @@ -222,12 +150,17 @@ Findings always have: Findings can be added through a data import, but they can also be added manually to a Test. - - **Examples of Findings:** - * OpenSSL ‘ChangeCipherSpec’ MiTM Potential Vulnerability * Web Application Potentially Vulnerable to Clickjacking * Web Browser XSS Protection Not Enabled +## **Endpoints** + +Scan data generally will contain references to the hosts or endpoints affected by a given Finding. DefectDojo automatically aggregates Findings per-endpoint, so you can use the Endpoint view to look at all Findings that affect a given Endpoint or Hostname. + +Examples: +- https://www.example.com +- https://www.example.com:8080/products +- 192.168.0.36 \ No newline at end of file