diff --git a/docs/assets/images/OS_RA_image1.png b/docs/assets/images/OS_RA_image1.png new file mode 100644 index 00000000000..2e3ee96df15 Binary files /dev/null and b/docs/assets/images/OS_RA_image1.png differ diff --git a/docs/assets/images/OS_RA_image2.png b/docs/assets/images/OS_RA_image2.png new file mode 100644 index 00000000000..0b52ed32d7f Binary files /dev/null and b/docs/assets/images/OS_RA_image2.png differ diff --git a/docs/assets/images/OS_RA_image3.png b/docs/assets/images/OS_RA_image3.png new file mode 100644 index 00000000000..90a75fb408e Binary files /dev/null and b/docs/assets/images/OS_RA_image3.png differ diff --git a/docs/assets/images/OS_RA_image4.png b/docs/assets/images/OS_RA_image4.png new file mode 100644 index 00000000000..1fa0f32c2f0 Binary files /dev/null and b/docs/assets/images/OS_RA_image4.png differ diff --git a/docs/assets/images/OS_RA_image5.png b/docs/assets/images/OS_RA_image5.png new file mode 100644 index 00000000000..0803d4ae8c7 Binary files /dev/null and b/docs/assets/images/OS_RA_image5.png differ diff --git a/docs/assets/images/OS_RA_image6.png b/docs/assets/images/OS_RA_image6.png new file mode 100644 index 00000000000..8250ab66dd1 Binary files /dev/null and b/docs/assets/images/OS_RA_image6.png differ diff --git a/docs/assets/images/OS_RA_image7.png b/docs/assets/images/OS_RA_image7.png new file mode 100644 index 00000000000..dd835f7c6ad Binary files /dev/null and b/docs/assets/images/OS_RA_image7.png differ diff --git a/docs/assets/images/OS_RA_image8.png b/docs/assets/images/OS_RA_image8.png new file mode 100644 index 00000000000..e710f7f6872 Binary files /dev/null and b/docs/assets/images/OS_RA_image8.png differ diff --git a/docs/content/triage_findings/findings_workflows/OS__risk_acceptance.md b/docs/content/triage_findings/findings_workflows/OS__risk_acceptance.md new file mode 100644 index 00000000000..bff51d2135c --- /dev/null +++ b/docs/content/triage_findings/findings_workflows/OS__risk_acceptance.md @@ -0,0 +1,101 @@ +--- +title: "Risk Acceptances" +description: "Leveraging Risk Acceptances in DefectDojo OS" +audience: opensource +weight: 2 +--- + +**Risk Acceptances** are a special status that can be applied to Findings to formally document and operationalize the decision to acknowledge them without immediately remediating them. + +Contrary to DefectDojo Pro, Risk Acceptances in OS DefectDojo are not independent objects. Rather, Risk Acceptances are only linked to Engagements. As such, they can only contain Findings from the Engagement they live in. If 3 instances of the same Finding appear in a Test in 3 different Engagements, 3 different Risk Acceptances will be required to fully accept those Findings. + +### Accessing Risk Acceptances + +Risk Acceptances include Findings that are particular to the Test(s) within each Engagement. As such, they can be accessed from the Engagement that contains the Test those Findings are from. + +![image](images/OS_RA_image1.png) + +A complete list of individual risk-accepted Findings is viewable in the **Risk Accepted Findings** submenu of the **Findings** section in the sidebar. + +![image](images/OS_RA_image2.png) + +## Creating Risk Acceptances + +When a Finding is Risk Accepted, the following will occur: +- The Finding’s status will no longer be “Active” but it will remain queryable, reportable, and auditable. +- The Finding’s status will be changed to “Risk Accepted.” +- The Finding will no longer be counted toward Metrics, but will still appear within the Test it originated from. + +Findings can be Risk Accepted in one of two ways: They can either be manually added to a **Full Risk Acceptance**, or by using the **Simple Risk Acceptance** workflow. + +### Full Risk Acceptances + +A Full Risk Acceptance allows Users to accept the risk of multiple Findings within an Engagement and bundle them into a single unit. If organizational policy requires formal, documented risk acceptances, or Users wish to trigger certain actions once a Risk Acceptance expires, Full Risk Acceptances are the best choice, as they capture the internal decision-making process and can serve as a source of truth. + +Each Full Risk Acceptance adds additional context, such as: +- The name of the Risk Acceptance. +- The owner of the Risk Acceptance. +- The security recommendation and decision regarding how to handle the Finding(s). +- Any proof associated with the recommendation or decision. +- Details regarding the recommendation or decision. +- The User who accepts the risk associated with the decision. +- The expiration date. + - Whether the Finding’s status will return to “Active” upon expiration. + - Whether the SLA will restart upon expiration. + +Expiration is unique to Full Risk Acceptances, and allows any Findings that have been Risk Accepted to be re-examined at an appropriate time. Once a Full Risk Acceptance expires, any Findings will be set to Active again. If you don’t specify a date, the Default Risk Acceptance / Default Risk Acceptance Expiration date will be used from the System Settings page. + +Importantly, as Full Risk Acceptances are restricted to individual Engagements, there is no single section in which to view all Full Risk Acceptances. They can only be viewed within the respective Engagement that includes the Findings that the Full Risk Acceptance contains. + +#### How to Create a Full Risk Acceptance + +In order to create a Full Risk Acceptance, navigate to the Engagement view and click the **+** symbol in the Risk Acceptance box. + +![image](images/OS_RA_image3.png) + +From there, fill out the details of the Full Risk Acceptance and select the Findings to be included. **Accepted Findings** contains a dropdown list of all available Findings to be added to the Risk Acceptance. The list of Findings within the Engagement will appear in descending order of severity (Critical Findings at the top, Low Findings at the bottom). If a Finding has been previously Risk Accepted, it will not appear in the dropdown list. + +Once completed, the Full Risk Acceptance will appear within the Risk Acceptance box in the Engagement view. + +A Risk Acceptance can also be created by clicking the **Add Risk Acceptance** button from within an individual Finding's ⋮ kebab menu. + +![image](images/OS_RA_image7.png) + +#### Interacting with Full Risk Acceptances + +Once a Full Risk Acceptance has been created, it can be opened to view the Findings that were added to it as well as any details that were input when it was created (e.g., the date, owner, decision, expiration, etc.). + +To remove a Finding from a Full Risk Acceptance, click the **Remove** button within the Findings Accepted table. + +![image](images/OS_RA_image8.png) + +The Full Risk Acceptance's view also includes a table at the bottom for all other Findings from Tests within that Engagement. From there, you may select additional Findings and add them to that Full Risk Acceptance. + +Additionally, there is a Notes function that allows Users to include additional context to the Full Risk Acceptance. All public notes will appear in any Reports that are generated for the Full Risk Acceptance, whereas notes that are toggled as **Private** will not appear in reports. + +Importantly, if a Full Risk Acceptance is deleted entirely, the Findings within will have their status automatically reverted to “Active.” + +### Simple Risk Acceptances + +While Full Risk Acceptance is enabled by default, Simple Risk Acceptance must be enabled manually, either upon the creation of an Asset or within the Asset’s settings. + +![image](images/OS_RA_image4.png) + +A Simple Risk Acceptance can be performed in either one of two ways: +1. Within a Test view using the Bulk Edits menu that appears after selecting one or more Findings from within the Findings table. + +![image](images/OS_RA_image5.png) + +2. Clicking **Accept Risk** from within an individual Finding’s ⋮ kebab menu. + +![image](images/OS_RA_image6.png) + +Once a Finding has been Simple Risk Accepted, it will still appear in the Test's Findings table, but the status will be changed to **Inactive, Risk Accepted.** A complete list of individual risk-accepted Findings is viewable in the **Risk Accepted Findings** submenu of the **Findings** section in the sidebar. + +If you Simple Risk Accept a Finding and later wish to add it to a Full Risk Acceptance, the Risk must be unaccepted prior to adding it to a Full Risk Acceptance. + +### Risk Acceptance Best Practices + +As a standard practice, it is generally preferable to use either Full Risk Acceptances or Simple Risk Acceptances exclusively, rather than leveraging both. + +For example, if Full Risk Acceptances are the default approach, if a Finding is Simple Risk Accepted, it may cause confusion if there is no associated Full Risk Acceptance that contains the affected Finding. Similarly, if Findings are typically Simple Risk Accepted, it may also create confusion to then add some Findings to a Full Risk Acceptance when there are no such objects for most other Findings. diff --git a/docs/content/triage_findings/findings_workflows/risk_acceptances.md b/docs/content/triage_findings/findings_workflows/risk_acceptances.md deleted file mode 100644 index db37e0e450d..00000000000 --- a/docs/content/triage_findings/findings_workflows/risk_acceptances.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -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 -* One or more Findings governed by the Risk Acceptance - -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. - -### DefectDojo Pro vs Open Source: Cross-Product Risk Acceptances - -**DefectDojo Pro** provides enhanced Risk Acceptance capabilities that aid in managing risk decisions at scale: - -* **Cross-Product Risk Acceptances**: In DefectDojo Pro, you can apply a single Risk Acceptance across multiple Products. For example, if CVE-2024-1234 appears in 10 different products, you can create one Risk Acceptance that governs all instances of that CVE across your entire portfolio. -* **Bulk CVE Management**: Search for all Findings with a specific CVE or vulnerability ID, then apply a Risk Acceptance to all instances simultaneously, regardless of which Product they belong to. - -**DefectDojo Open Source** implements Risk Acceptances at the Engagement level: - -* **Product-Scoped Risk Acceptances**: Risk Acceptances are restricted to individual Products. If CVE-2024-1234 appears in 10 different products, you need to create 10 separate Risk Acceptances—one for each Engagement. - -Both approaches follow the same Risk Acceptance workflow described below, but the scope differs based on your DefectDojo edition. - -### 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 - -![image](images/Risk_Acceptances.png) - - -![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. -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 - -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**. - -### 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 - -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)