diff --git a/docs/assets/diagrams/Asset_Hierarchy_Full.drawio b/docs/assets/diagrams/Asset_Hierarchy_Full.drawio new file mode 100644 index 00000000000..e9b86be565d --- /dev/null +++ b/docs/assets/diagrams/Asset_Hierarchy_Full.drawio @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/assets/diagrams/Asset_Hierarchy_Overview.drawio b/docs/assets/diagrams/Asset_Hierarchy_Overview.drawio new file mode 100644 index 00000000000..31bf4cbbc34 --- /dev/null +++ b/docs/assets/diagrams/Asset_Hierarchy_Overview.drawio @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/assets/diagrams/Asset_Hierarchy_Overview_2.drawio b/docs/assets/diagrams/Asset_Hierarchy_Overview_2.drawio new file mode 100644 index 00000000000..87ec3405739 --- /dev/null +++ b/docs/assets/diagrams/Asset_Hierarchy_Overview_2.drawio @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/assets/images/Asset_Hierarchy_Full.png b/docs/assets/images/Asset_Hierarchy_Full.png new file mode 100644 index 00000000000..bfcbaf5ebee Binary files /dev/null and b/docs/assets/images/Asset_Hierarchy_Full.png differ diff --git a/docs/assets/images/Asset_Hierarchy_Overview.png b/docs/assets/images/Asset_Hierarchy_Overview.png new file mode 100644 index 00000000000..cdc855827d3 Binary files /dev/null and b/docs/assets/images/Asset_Hierarchy_Overview.png differ diff --git a/docs/assets/images/Asset_Hierarchy_Overview_2.png b/docs/assets/images/Asset_Hierarchy_Overview_2.png new file mode 100644 index 00000000000..fc00bef5b43 Binary files /dev/null and b/docs/assets/images/Asset_Hierarchy_Overview_2.png differ diff --git a/docs/assets/images/PT_ss2.png b/docs/assets/images/PT_ss2.png deleted file mode 100644 index 1602a7bb2c8..00000000000 Binary files a/docs/assets/images/PT_ss2.png and /dev/null differ diff --git a/docs/assets/images/Product_Hierarchy_Overview.png b/docs/assets/images/Product_Hierarchy_Overview.png deleted file mode 100644 index 3a6b683a328..00000000000 Binary files a/docs/assets/images/Product_Hierarchy_Overview.png and /dev/null differ diff --git a/docs/assets/images/Product_Hierarchy_Overview_2.png b/docs/assets/images/Product_Hierarchy_Overview_2.png deleted file mode 100644 index 20760513bbb..00000000000 Binary files a/docs/assets/images/Product_Hierarchy_Overview_2.png and /dev/null differ diff --git a/docs/assets/images/product-custom-fields_1.png b/docs/assets/images/asset-custom-fields_1.png similarity index 100% rename from docs/assets/images/product-custom-fields_1.png rename to docs/assets/images/asset-custom-fields_1.png diff --git a/docs/assets/images/asset-health-grade.png b/docs/assets/images/asset-health-grade.png new file mode 100644 index 00000000000..a4e279e6429 Binary files /dev/null and b/docs/assets/images/asset-health-grade.png differ diff --git a/docs/assets/images/product-scm-type_1.png b/docs/assets/images/asset-scm-type_1.png similarity index 100% rename from docs/assets/images/product-scm-type_1.png rename to docs/assets/images/asset-scm-type_1.png diff --git a/docs/assets/images/asset_ss1.png b/docs/assets/images/asset_ss1.png new file mode 100644 index 00000000000..fe3e1c5fde0 Binary files /dev/null and b/docs/assets/images/asset_ss1.png differ diff --git a/docs/assets/images/asset_ss2.png b/docs/assets/images/asset_ss2.png new file mode 100644 index 00000000000..ad70b4a0145 Binary files /dev/null and b/docs/assets/images/asset_ss2.png differ diff --git a/docs/assets/images/asset_ss3.png b/docs/assets/images/asset_ss3.png new file mode 100644 index 00000000000..7078f51aace Binary files /dev/null and b/docs/assets/images/asset_ss3.png differ diff --git a/docs/assets/images/asset_ss5.png b/docs/assets/images/asset_ss5.png new file mode 100644 index 00000000000..d39db4865a5 Binary files /dev/null and b/docs/assets/images/asset_ss5.png differ diff --git a/docs/assets/images/asset_ss6.png b/docs/assets/images/asset_ss6.png new file mode 100644 index 00000000000..e6c483dc358 Binary files /dev/null and b/docs/assets/images/asset_ss6.png differ diff --git a/docs/assets/images/asset_ss7.png b/docs/assets/images/asset_ss7.png new file mode 100644 index 00000000000..7f058ba18fd Binary files /dev/null and b/docs/assets/images/asset_ss7.png differ diff --git a/docs/assets/images/asset_ss8.png b/docs/assets/images/asset_ss8.png new file mode 100644 index 00000000000..5cce4564bf0 Binary files /dev/null and b/docs/assets/images/asset_ss8.png differ diff --git a/docs/assets/images/dashboard.png b/docs/assets/images/dashboard.png index 454e53bd548..d9762e7f1c4 100644 Binary files a/docs/assets/images/dashboard.png and b/docs/assets/images/dashboard.png differ diff --git a/docs/assets/images/dd-hierarchy.png b/docs/assets/images/dd-hierarchy.png deleted file mode 100644 index 8d16a495c63..00000000000 Binary files a/docs/assets/images/dd-hierarchy.png and /dev/null differ diff --git a/docs/assets/images/organization_ss1.png b/docs/assets/images/organization_ss1.png new file mode 100644 index 00000000000..1c62f401b81 Binary files /dev/null and b/docs/assets/images/organization_ss1.png differ diff --git a/docs/assets/images/product_ss1.png b/docs/assets/images/product_ss1.png deleted file mode 100644 index 956eb53493b..00000000000 Binary files a/docs/assets/images/product_ss1.png and /dev/null differ diff --git a/docs/assets/images/product_ss2.png b/docs/assets/images/product_ss2.png deleted file mode 100644 index cd37c0578d7..00000000000 Binary files a/docs/assets/images/product_ss2.png and /dev/null differ diff --git a/docs/assets/images/product_ss3.png b/docs/assets/images/product_ss3.png deleted file mode 100644 index f45fa3cdb8c..00000000000 Binary files a/docs/assets/images/product_ss3.png and /dev/null differ diff --git a/docs/assets/images/product_ss5.png b/docs/assets/images/product_ss5.png deleted file mode 100644 index 4ea580146c0..00000000000 Binary files a/docs/assets/images/product_ss5.png and /dev/null differ diff --git a/docs/assets/images/product_ss6.png b/docs/assets/images/product_ss6.png deleted file mode 100644 index 3f372106104..00000000000 Binary files a/docs/assets/images/product_ss6.png and /dev/null differ diff --git a/docs/assets/images/product_ss7.png b/docs/assets/images/product_ss7.png deleted file mode 100644 index d7da19c5cb5..00000000000 Binary files a/docs/assets/images/product_ss7.png and /dev/null differ diff --git a/docs/assets/images/product_ss8.png b/docs/assets/images/product_ss8.png deleted file mode 100644 index 4840d71fd63..00000000000 Binary files a/docs/assets/images/product_ss8.png and /dev/null differ diff --git a/docs/assets/images/tags-bulk-edit-complete.png b/docs/assets/images/tags-bulk-edit-complete.png index 9ca91e2b294..f4f5e5f7edf 100644 Binary files a/docs/assets/images/tags-bulk-edit-complete.png and b/docs/assets/images/tags-bulk-edit-complete.png differ diff --git a/docs/assets/images/tags-bulk-edit-submit.png b/docs/assets/images/tags-bulk-edit-submit.png index 7e5c0d86c28..0155c091f4b 100644 Binary files a/docs/assets/images/tags-bulk-edit-submit.png and b/docs/assets/images/tags-bulk-edit-submit.png differ diff --git a/docs/assets/images/tags-finding-filter-snippet.png b/docs/assets/images/tags-finding-filter-snippet.png index af8986c367b..08aec92afb6 100644 Binary files a/docs/assets/images/tags-finding-filter-snippet.png and b/docs/assets/images/tags-finding-filter-snippet.png differ diff --git a/docs/assets/images/tags-high-level-example.png b/docs/assets/images/tags-high-level-example.png index b85ba163d3b..0820374ee24 100644 Binary files a/docs/assets/images/tags-high-level-example.png and b/docs/assets/images/tags-high-level-example.png differ diff --git a/docs/assets/images/tags-inherit-exmaple.png b/docs/assets/images/tags-inherit-exmaple.png index e4b80605ee2..bdbd18bd3a4 100644 Binary files a/docs/assets/images/tags-inherit-exmaple.png and b/docs/assets/images/tags-inherit-exmaple.png differ diff --git a/docs/assets/images/tags-management-on-object.png b/docs/assets/images/tags-management-on-object.png index 79bd0527534..32942b26d04 100644 Binary files a/docs/assets/images/tags-management-on-object.png and b/docs/assets/images/tags-management-on-object.png differ diff --git a/docs/assets/images/tags-select-findings-for-bulk-edit.png b/docs/assets/images/tags-select-findings-for-bulk-edit.png index 8e6fc47dc98..e872b28cce9 100644 Binary files a/docs/assets/images/tags-select-findings-for-bulk-edit.png and b/docs/assets/images/tags-select-findings-for-bulk-edit.png differ diff --git a/docs/assets/js/custom.js b/docs/assets/js/custom.js index c9ff8188682..cfe53a366c7 100644 --- a/docs/assets/js/custom.js +++ b/docs/assets/js/custom.js @@ -7,6 +7,26 @@ console.log("[VersionToggle] custom.js loaded"); + // Asset-modelling landing pages per edition. The top nav is otherwise + // static, so a single URL can't be correct for both editions: we keep the + // "Model Your Assets" nav link in sync with the selected version, and — + // when the user is already viewing one of these pages — navigate to the + // matching edition's page so the main content follows the toggle. + const assetNavUrls = { + opensource: "/asset_modelling/engagements_tests/os__assets/", + pro: "/asset_modelling/pro_hierarchy/assets_organizations/", + }; + + const switchAssetPageForVersion = (version) => { + const target = assetNavUrls[version]; + const other = assetNavUrls[version === "pro" ? "opensource" : "pro"]; + // Only redirect when currently on the *other* edition's asset page, + // so this never fires on unrelated pages or loops on the target page. + if (target && location.pathname === other) { + location.assign(target); + } + }; + const setVersion = (version) => { console.log("[VersionToggle] Setting version to:", version); @@ -31,6 +51,14 @@ sidebar.style.visibility = "visible"; console.log("[VersionToggle] Sidebar revealed"); } + + // Edition-aware top nav: route "Model Your Assets" to the page that + // matches the selected version (see assetNavUrls above). + document.querySelectorAll("a.nav-link").forEach(link => { + if (link.textContent.trim() === "Model Your Assets") { + link.setAttribute("href", assetNavUrls[version] || assetNavUrls.opensource); + } + }); }; const initVersionToggle = () => { @@ -44,6 +72,9 @@ if (e.target && e.target.id === "version-select") { console.log("[VersionToggle] Dropdown changed to:", e.target.value); setVersion(e.target.value); + // Only on an explicit user toggle (not on load) follow the page to + // the matching edition when viewing an asset-modelling page. + switchAssetPageForVersion(e.target.value); } }); diff --git a/docs/config/_default/menus/menus.en.toml b/docs/config/_default/menus/menus.en.toml index f82d38e9abc..67ad0c35f91 100644 --- a/docs/config/_default/menus/menus.en.toml +++ b/docs/config/_default/menus/menus.en.toml @@ -15,7 +15,7 @@ [[main]] name = "Model Your Assets" - url = "/asset_modelling/pro_hierarchy/assets_organizations/" + url = "/asset_modelling/engagements_tests/os__assets/" weight = 13 [[main]] diff --git a/docs/content/asset_modelling/OS_hierarchy/OS__asset_health_grade.md b/docs/content/asset_modelling/OS_hierarchy/OS__asset_health_grade.md new file mode 100644 index 00000000000..1c7088363f4 --- /dev/null +++ b/docs/content/asset_modelling/OS_hierarchy/OS__asset_health_grade.md @@ -0,0 +1,39 @@ +--- +title: "Asset Health Grade" +description: "How DefectDojo calculates an Asset Health Grade" +weight: 7 +audience: opensource +aliases: + - /en/working_with_findings/organizing_engagements_tests/product_health_grade + - /asset_modelling/os_hierarchy/product_health_grade/ + - /en/asset_modelling/os_hierarchy/product_health_grade/ +--- +DefectDojo can calculate a grade for your Assets based on the amount of Findings contained within. Grades are ranked from A \- F. + +Note that only Active \& Verified Findings contribute to an Asset Grade \- unverified Findings will not have an impact. + +*Each Asset's health grade (A \- F) appears beside its name in the Asset List.* + +![Asset Health Grades shown beside each Asset in the Asset List](images/asset-health-grade.png) + +## Asset Grade Calculation + +Every Asset Grade starts at 100 (with no Findings). + +Grade calculation starts by looking at the highest **Severity** level of a Finding in an Asset, and reducing the Asset Health to a base level. + +| **Highest Severity Level of a Finding** | **Maximum Grade** | +| --- | --- | +| **Critical** | **40** | +| **High** | **60** | +| **Medium** | **80** | +| **Low** | **95** | + +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/asset_modelling/OS_hierarchy/product_hierarchy.md b/docs/content/asset_modelling/OS_hierarchy/OS__asset_hierarchy.md similarity index 67% rename from docs/content/asset_modelling/OS_hierarchy/product_hierarchy.md rename to docs/content/asset_modelling/OS_hierarchy/OS__asset_hierarchy.md index 36e0149b34a..533d9779a9e 100644 --- a/docs/content/asset_modelling/OS_hierarchy/product_hierarchy.md +++ b/docs/content/asset_modelling/OS_hierarchy/OS__asset_hierarchy.md @@ -1,70 +1,74 @@ --- -title: "Product Hierarchy: Overview" -description: "Understand Product Types, Products, Engagements, Tests and Findings" +title: "Asset Hierarchy: Overview" +description: "Understand Organizations, Assets, Engagements, Tests and Findings" weight: 1 audience: opensource aliases: - /en/working_with_findings/organizing_engagements_tests/product_hierarchy + - /asset_modelling/os_hierarchy/product_hierarchy/ + - /en/asset_modelling/os_hierarchy/product_hierarchy/ --- -DefectDojo uses five main data classes to organize your work: **Product Types, Products**, **Engagements**, **Tests**, and **Findings**. +DefectDojo uses five main data classes to organize your work: **Organizations, Assets**, **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) +### Asset Hierarchy Diagram +![image](images/Asset_Hierarchy_Full.png) -## **Product Types** +## **Organizations** -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: +The first category of data you'll need to set up in DefectDojo is an Organization. Organizations are intended to categorize Assets in a specific way. This could be: * by business domain * by development team * by security team -![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. +![image](images/Asset_Hierarchy_Overview.png) +*Assets are grouped and nested underneath their Organization.* -#### What can a Product Type represent? +Organizations can have Role\-Based Access Control rules applied, which limit team members' ability to view and interact with their data (including any underlying Assets with Engagement, Test and Finding data). For more information on user roles, see our **Introduction To Roles** article. -* 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. +#### What can an Organization represent? + +* If a particular software project has many distinct deployments or versions, it may be worth creating a single Organization which covers the scope of the entire project, and having each version exist as individual Assets. ​ -* You also might consider using Product Types to represent stages in your software development process: one Product Type for 'In Development', one Product Type for 'In Production', etc. +* You also might consider using Organizations to represent stages in your software development process: one Organization for 'In Development', one Organization for 'In Production', etc. ​ -* 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. +* Ultimately, it's your decision how you wish to organize your Assets, and what you want your Organizations to represent. Your DefectDojo hierarchy may need to change to fit your security teams' needs. -## **Products** +## **Assets** -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. +An **Asset** in DefectDojo is intended to represent any project, program, or application that you are currently testing. The Asset hosts all of the security work and testing history related to the underlying goal. -![image](images/Product_Hierarchy_Overview_2.png) +![image](images/Asset_Hierarchy_Overview_2.png) * a unique **Name** * a **Description** -* a product **Type** +* an **Organization** * an assigned **SLA Configuration** -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**. +Assets can be as broad or as specific in scope as you wish. By default, Assets are completely separate objects in the hierarchy, but they can be grouped together by **Organization**. -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. +Assets are 'walled\-off' and do not interact with other Assets. DefectDojo's Smart Features, such as **Deduplication**, only apply within the context of a single Asset. -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. +Like **Organizations**, **Assets** 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 an Asset 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. +DefectDojo's concept of an 'Asset' 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: +The following scenarios are good reasons to consider creating a separate DefectDojo Asset: -* "**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. +* "**ExampleAsset**" has a Windows version, a Mac version, and a Cloud version +* "**ExampleAsset 1\.0**" uses completely different software components from "**ExampleAsset 2\.0**", and both versions are actively supported by your company. +* The team assigned to work on "**ExampleAsset version A**" is different than the Asset team assigned to work on "**ExampleAsset 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. +These variations within a single Asset can also be handled at the Engagement level. Note that Engagements don't have access control in the way Assets and Organizations do. ## **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**. +Once an Asset 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: @@ -72,7 +76,7 @@ Engagements always have: * target **Start and End dates** * **Status** (Not Started, In Progress, Cancelled, Completed...) * an assigned **Testing Lead** -* an associated **Product** +* an associated **Asset** There are two types of Engagement: **Interactive** and **CI/CD**. @@ -105,11 +109,11 @@ You can also organize CI/CD Test results within an Engagement. These kinds of En * 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. +Engagements can be organized however works best for your team. All Engagements nested under an Asset can be viewed by the team assigned to work on the Asset. ## **Tests** -Tests are a grouping of activities conducted by engineers to attempt to discover flaws in a product. +Tests are a grouping of activities conducted by engineers to attempt to discover flaws in an Asset. Tests always have: @@ -168,9 +172,9 @@ Tests take your testing data and group it into Findings. Generally, security tea **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. +**Tests can be imported separately** \- If you run the same test on an Asset 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. +If a Test is added directly to an Asset without an Engagement, a generic Engagement will be created automatically to contain the Test. This allows for ad\-hoc data imports. **Examples of Tests:** diff --git a/docs/content/asset_modelling/OS_hierarchy/OS__source-code-repositories.md b/docs/content/asset_modelling/OS_hierarchy/OS__source-code-repositories.md index a6c41c90d79..4d6f560de07 100644 --- a/docs/content/asset_modelling/OS_hierarchy/OS__source-code-repositories.md +++ b/docs/content/asset_modelling/OS_hierarchy/OS__source-code-repositories.md @@ -33,15 +33,15 @@ For CI/CD Engagements, the commit hash, branch/tag and code line can vary, so yo In a CI/CD Engagement, you can specify a commit hash or branch/tag in the **Edit Engagement** form, which will be appended to any links rendered by DefectDojo. If these are not set, the SCM URL will need to contain a complete link which includes the code branch. -SCM navigation URL is composed from Repo URL using SCM Type. A specific SCM type can be set in Product custom field "scm-type". If no "scm-type" is set and the URL contains "https://github.com", a "github" SCM type is assumed. +SCM navigation URL is composed from Repo URL using SCM Type. A specific SCM type can be set in Asset custom field "scm-type". If no "scm-type" is set and the URL contains "https://github.com", a "github" SCM type is assumed. -Product custom fields: +Asset custom fields: -![Product custom fields](images/product-custom-fields_1.png) +![Asset custom fields](images/asset-custom-fields_1.png) -Product SCM type add: +Asset SCM type add: -![Product scm type](images/product-scm-type_1.png) +![Asset scm type](images/asset-scm-type_1.png) Possible SCM types could be 'github', 'gitlab', 'bitbucket', 'bitbucket-standalone', 'gitea', 'codeberg' or nothing (for default github). diff --git a/docs/content/asset_modelling/OS_hierarchy/_index.md b/docs/content/asset_modelling/OS_hierarchy/_index.md index 81e9356aa58..a5302b58fac 100644 --- a/docs/content/asset_modelling/OS_hierarchy/_index.md +++ b/docs/content/asset_modelling/OS_hierarchy/_index.md @@ -1,5 +1,5 @@ --- -title: "Product Hierarchy" +title: "Asset Hierarchy" audience: opensource date: 2021-02-02T20:46:29+01:00 draft: false diff --git a/docs/content/asset_modelling/OS_hierarchy/product_health_grade.md b/docs/content/asset_modelling/OS_hierarchy/product_health_grade.md deleted file mode 100644 index 53961251fd3..00000000000 --- a/docs/content/asset_modelling/OS_hierarchy/product_health_grade.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: "Product Health Grade" -description: "How DefectDojo calculates a Product Health Grade" -aliases: - - /en/working_with_findings/organizing_engagements_tests/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 - -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** | -| **High** | **60** | -| **Medium** | **80** | -| **Low** | **95** | - -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/asset_modelling/engagements_tests/OS__assets.md b/docs/content/asset_modelling/engagements_tests/OS__assets.md new file mode 100644 index 00000000000..2f875bf05cf --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__assets.md @@ -0,0 +1,180 @@ +--- +title: "Assets" +description: "Understanding Assets in DefectDojo OS" +audience: opensource +weight: 2 +aliases: + - /asset_modelling/engagements_tests/os__products/ + - /en/asset_modelling/engagements_tests/os__products/ +--- +Organizations → **ASSETS** → Engagements → Tests → Findings + +## Overview + +**Assets** sit at the center of how security work is organized within DefectDojo’s object hierarchy. Assets represent any project, program, software, or physical asset that your security team is testing, and host all of the security work and testing history related to the testing goal. Examples of Assets can include: +- Software releases +- Third-party software +- Virtual machines or assets in production +- A single application +- A microservice +- An API +- A SaaS platform +- A mobile app +- An internal system +- A business service +- A customer-facing platform +- A cloud environment or infrastructure domain + +In general, an Asset should represent the “thing” whose security posture you want to track over time. This includes the associated testing history, Findings, metrics, ownership, integrations, and remediation workflows related to that “thing.” + +### Asset Examples + +Assets can become even more granular depending on the needs of your organization. For example, you may consider creating separate DefectDojo Assets in the following scenarios: + +- “ExampleAsset” has a Windows version, a Mac version, and a Cloud version +- “ExampleAsset 1.0” uses completely different software components from “ExampleAsset 2.0”, and both versions are actively supported by your company. +- The team assigned to work on “ExampleAsset version A” is different from the Asset team assigned to work on “ExampleAsset version B”, and needs to have different security permissions assigned as a result. + +While you may also elect to represent these variations as Engagements within a single Asset, RBAC can only be set at the level of Assets or Organizations, which may limit users’ access to the appropriate Engagement (as well as the Tests and Findings within those Engagements) if they’re organized as such. For more information on RBAC and permissions in DefectDojo, click [here](/admin/user_management/about_perms_and_roles/). + +## Asset Data + +Assets will always include the following components: + +- **Unique name** +- **Description** +- **Organization** +- **SLA Configuration** + +Optional Asset metadata includes: + +- **Tags** +- **Personnel information** (e.g., Asset Manager, Team Manager, Technical Contact, etc.) +- **Regulations** (e.g., HIPAA, GLBA, OPPA, etc.) +- **Business criticality** +- **Platform** (e.g., API, Desktop, IoT, Mobile, Web, etc.) +- **Lifecycle** (e.g., Construction, Production, Retirement, etc.) +- **Origin** (e.g., Third-Party Library, Purchased, Open Source, etc.) +- **User records** (i.e., the estimated number of user records in the Asset) +- **Revenue** + +This metadata improves filtering, reporting, and prioritization across your security program, but most importantly, Assets also contain all of the Engagements, Tests, and Findings related to the testing efforts surrounding that Asset. All Findings from Tests ultimately roll up to the Asset level, enabling long-term tracking, trend analysis, and reporting. + +## Accessing Assets + +Assets are accessible via the sidebar. The submenu also provides the option to create a new Asset. + +![image](images/asset_ss3.png) + +### Permissions + +Assets can have Role-Based Access Control (RBAC) rules applied, which limit team members’ ability to view and interact with them. + +Permissions cascade downward, meaning that access to an Asset automatically grants access to all objects within that Asset (e.g., Engagements, Tests, and Findings). + +For more information on user roles, see our [Introduction To Roles article](/admin/user_management/about_perms_and_roles/). + +## Asset View + +Asset views contain a variety of tables and charts to interpret an Asset’s status at a glance. This includes: + +- **Metadata** + - Including Organization, business criticality, revenue, and other details added from the Asset settings. +- **Metrics** + - A list of open Findings within the Asset, grouped by severity +- **Service Level Agreement by Severity** + - Applies the Asset SLA configuration from settings to the Findings within the Asset. +- **Technologies** + - E.g., next.js, vue.js, npm v.1.2.3, Django, nginx, Hugo +- **Regulations** +- **Benchmark Progress** +- **Members** +- **Groups** +- **Contacts** +- **Notifications** + - Toggles notifications on and off depending on specific events (e.g., an Engagement has been added or closed) + +## Working with Assets + +### Create Assets + +There are multiple ways to create a new Asset, including: + +- The **Add Asset** button in the All Assets list + +![image](images/asset_ss2.png) + +- From the dropdown menu of the Assets table within an Organization’s view + - This will automatically create the Asset within that Organization. + +![image](images/asset_ss1.png) + +- The **Add Asset** button in the sidebar + +![image](images/asset_ss5.png) + +### Edit Assets + +An Asset can be edited from its settings, which can be accessed in two ways: + +- The **Edit** button within ⋮ kebab menu to the left of the Asset in the All Assets view + +![image](images/asset_ss6.png) + +- The **Edit** button within the **Settings** dropdown in the Asset’s view + +![image](images/asset_ss7.png) + +### Delete Assets + +The option to delete an Asset can be found at the bottom of the same menus described in the **Edit Assets** section above. This action can’t be undone. Asset can’t be closed and reopened later. + +Deleting an Asset will also delete the following: +- Any Engagements and Tests contained within the Asset +- All associated security history, including Findings and integrations +- Any linked Jira Epics +- All notes and file uploads associated with the Asset’s Engagements and Tests + +## Asset Boundaries + +### Deduplication + +Assets are “walled-off” and do not interact with other Assets. DefectDojo’s Smart Features, such as Deduplication, only apply within the context of a single Asset. Findings across different Assets will not be automatically deduplicated. + +### Metrics + +Most reporting and metrics aggregate data at the Asset level, making Assets the primary unit for measuring and tracking risk. + +As a result, many key metrics are calculated per Asset, including: + +- Total number of Findings (by severity or status) +- Mean time to remediate (MTTR) +- SLA compliance and breach rates +- Risk trends over time + +This means that how Assets are structured will directly impact the accuracy and usefulness of reports. For example, grouping multiple unrelated systems under a single Asset may obscure risk visibility, while overly granular Asset structures can fragment reporting, making it difficult to identify broader trends. + +Asset-specific metrics can be accessed from the **Metrics** button in the top bar of the chosen Asset’s view. + +![image](images/asset_ss8.png) + +### CI/CD Pipeline + +CI/CD pipelines automate the import of scan results. Regardless of the integration method, all scan imports must be associated with an Asset, making the Asset the anchor point for pipeline-driven security data. + +When a pipeline submits scan results, it must either: + +- Specify an existing Asset (and optionally an Engagement), or +- Be configured in a way that consistently maps results to the correct Asset + +All imported Findings will inherit the Asset’s context, including ownership, permissions, SLA configuration, and reporting scope. + +In practice, Assets should be defined to reflect how systems are built and deployed within CI/CD to ensure that security results are consistently associated with the correct application or service. + +### Jira Relationships + +Assets can be mapped directly to Jira Projects, which push the Asset’s Findings into a Jira instance. + +Because Findings inherit risk, priority, and ownership from their parent Asset, the Asset effectively determines the remediation context that flows into Jira tickets and Integrator workflows. + +Importantly, Assets are also the primary determining factor in a Finding’s SLA characteristics. Therefore, the SLA of a Findings depends on the SLA configuration of its parent Asset. More information about SLA configurations can be found [here](/asset_modelling/os_hierarchy/os__sla_configuration/#main-content). diff --git a/docs/content/asset_modelling/engagements_tests/OS__organizations.md b/docs/content/asset_modelling/engagements_tests/OS__organizations.md new file mode 100644 index 00000000000..b33fa0a498a --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__organizations.md @@ -0,0 +1,138 @@ +--- +title: "Organizations" +description: "Understanding Organizations in DefectDojo OS" +audience: opensource +weight: 1 +aliases: + - /asset_modelling/engagements_tests/os_producttype/ + - /en/asset_modelling/engagements_tests/os_producttype/ +--- +**ORGANIZATIONS** → Assets → Engagements → Tests → Findings + +## Overview + +**Organizations** sit at the very top of DefectDojo’s object hierarchy. Organizations are distinct from the descending objects in the hierarchy—Assets, Engagements, Tests, and Findings—because they are not technical scan targets, but rather serve primarily as organizational abstractions that compartmentalize your security efforts according to: +- Business domain +- Development team +- Security team +- Software applications +- Overarching product family +- Customer or subsidiary +- Reporting structure +- etc. + +The theme of the above examples exemplifies the essential utility of Organizations: they should generally represent stable, long-lived boundaries within your security program. + +## Organization Data and Structure + +As Organizations are not scanned directly, the only mandatory field required to create them is a name. Beyond that, they act as containers for Assets and their descending Engagements, Tests, and Findings. + +When creating an Organization, consider how their structure will inform your reporting. Do you primarily need Organizations to represent the teams working on the projects (Assets) that Organizations will contain? Or would Organizations better represent overarching projects that contain different iterations of the projects (Assets) within it? + +If you have a single Organization that contains all of the relevant information for a given business domain or development team, having that represented as an Organization will facilitate smoother reporting, rather than having to pull together a report from various Assets and Organizations. + +If a particular software project has many distinct deployments or versions, it may be worth creating a single Organization which covers the scope of the entire project and having each version exist as individual Assets. In some workflows, Organizations may also be used to separate software lifecycle stages: one Organization for “In Development,” one Organization for “In Production,” etc. + +Organizations can be used to determine access to subsidiaries, acquired companies, or other regulated business units for RBAC purposes. In complex businesses, where there are a lot of unique projects with different access rules, Organizations are particularly relevant. + +Ultimately, the decision of how to use Organizations and Assets depends on how you best wish to reflect your unique organizational structure and the needs of your security team. + +Below are some example structures to inform how you designate your objects as either Organizations or Assets. + +- **Organization**: Payments Division + - Asset: Payments API - Production + - Asset: Payments API - Staging + - Asset: Billing Worker + +- **Organization**: Software Product A + - Asset: Web Portal + - Asset: Mobile Backend + +Additionally, the following is an illustrative guide as to whether a something is better represented by an Organization or an Asset: + +| Organizations | Assets | +|--------------|--------| +| Business units | Individual applications | +| Departments | Deployments/environments | +| Security ownership domains | Infrastructure components | +| Product families | Specific microservices | +| Portfolio-level reporting | Scan targets | +| Customers | Specific software versions | + +As noted, your structure may differ depending on your unique security needs. + +## Accessing Organizations + +Organizations are accessible via the sidebar. The submenu also provides the option to create new Organizations. + +![image](images/organization_ss1.png) + +### Organization View + +An Organization’s view contains a variety of tables and charts to interpret its status at a glance. This includes: +- **Description** +- **Key/Critical Checkbox** + - Checking Critical or Key is used solely for filtering purposes +- **List of Assets within the Organization** +- **Authorized Users** (DefectDojo Users) + +## Working with Organizations + +### Create Organizations + +There are two ways to create Organizations: + +- From the **Add Organization** option in the side menu +- From the **Add Organization** button at the top of the All Organizations list + +### Edit Organizations + +Organizations can be edited by clicking **Edit** from within the dropdown menu at the top right of the Description table in the Organization’s view. The same menu can also be accessed by clicking the ⋮ kebab menu to the left of the Organization in the All Organizations list. + +All ensuing fields that can be edited are also available when the Organization is being created. + +### Delete Organizations + +Deleting an Organization can be performed by selecting **Delete Organization** from the Organization’s settings. + +Because Organizations sit at the top of the hierarchy, deleting them removes all downstream security history, relationships, and child objects, such as: +- Any Assets, Engagements, and Tests contained within the Organization +- All associated security history, including Findings and integrations +- Any linked Jira Epics +- All notes and file uploads associated with the Assets, Engagements, and Tests within that Organization + +Deleting an Organization can’t be undone. If you would like to “decommission” an Organization without deleting underlying data (for example, preserving legacy software testing records for audit purposes), you can change the Organization’s name or add a Tag to indicate that it is in a deprecated state. + +## Organizations vs. Metadata + +Organizations are intended to represent structural ownership or reporting boundaries, rather than lightweight classifications. Attributes such as deployment status, internal labels, or temporary workflow states may be better represented through tags or metadata rather than separate Organizations. + +## Organization Boundaries + +Organizations establish both reporting and access boundaries within DefectDojo. Because integrations, RBAC permissions, ownership, metrics, and deduplication models frequently inherit Organizations’ structure, designing clear boundaries early helps avoid hierarchy sprawl and reporting fragmentation later. + +### Findings and Automation + +Although integrations are typically configured on lower-level objects such as Assets, Engagements, or Findings, Organizations still define the ownership, reporting, and access boundaries within which those integrations operate. + +Permissions cascade downward, meaning that access to an Organization automatically grants access to all objects within that Organization (e.g., Assets, Engagements, Tests, and Findings). + +The DefectDojo RBAC model can be used to gate human user access, but can also restrict API tokens’ access to particular Organizations. + +For more information on user roles, see our [Permissions](/admin/user_management/os__authorized_users/) article. + +### Ownership + +As top-level objects, Organizations also imply ownership over the child objects within them. SLA tracking, remediation workflows, ticket routing, and general governance all flow more smoothly when Organizations have been set up to accurately reflect the individuals accountable for them. + +### Metrics/Reporting + +Metrics dashboards, tiles and views can be filtered per Organization, making them a critical component in how your security data is calculated, visualized, and ultimately exported. + +For reporting purposes, it is generally easier to combine multiple Organizations into a single document than it is to subdivide a single Organization into separate documents. Therefore, we recommend setting up Organizations at as granular a level as makes sense for your team’s reports. For example, there is no need to represent a large business division as an Organization if you’re primarily going to be reporting to individual departments within that division. + +Effectively structuring your Organizations to reflect your reporting needs is critical to accurately assessing your security posture. For more information on Metrics, click [here](/metrics_reports/dashboards/introduction_dashboard/). + +### Deduplication + +Deduplication in DefectDojo occurs at the Asset level, and is not affected by the parent Organization. diff --git a/docs/content/asset_modelling/engagements_tests/OS__products.md b/docs/content/asset_modelling/engagements_tests/OS__products.md deleted file mode 100644 index d0b07c5fd5c..00000000000 --- a/docs/content/asset_modelling/engagements_tests/OS__products.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: "Products" -description: "Understanding Products in DefectDojo OS" -audience: opensource -weight: 2 ---- -Product Types → **PRODUCTS** → Engagements → Tests → Findings - -## Overview - -**Products** sit at the center of how security work is organized within DefectDojo’s object hierarchy. Products represent any project, program, software, or physical asset that your security team is testing, and host all of the security work and testing history related to the testing goal. Examples of Products can include: -- Software releases -- Third-party software -- Virtual machines or assets in production -- A single application -- A microservice -- An API -- A SaaS platform -- A mobile app -- An internal system -- A business service -- A customer-facing platform -- A cloud environment or infrastructure domain - -In general, a Product should represent the “thing” whose security posture you want to track over time. This includes the associated testing history, Findings, metrics, ownership, integrations, and remediation workflows related to that “thing.” - -### Product Examples - -Products can become even more granular depending on the needs of your organization. For example, you may consider creating separate DefectDojo Products in the following scenarios: - -- “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 from the product team assigned to work on “ExampleProduct version B”, and needs to have different security permissions assigned as a result. - -While you may also elect to represent these variations as Engagements within a single Product, RBAC can only be set at the level of Products or Product Types, which may limit users’ access to the appropriate Engagement (as well as the Tests and Findings within those Engagements) if they’re organized as such. For more information on RBAC and permissions in DefectDojo, click [here](/admin/user_management/about_perms_and_roles/). - -## Product Data - -Products will always include the following components: - -- **Unique name** -- **Description** -- **Product Type** -- **SLA Configuration** - -Optional Product metadata includes: - -- **Tags** -- **Personnel information** (e.g., Product Manager, Team Manager, Technical Contact, etc.) -- **Regulations** (e.g., HIPAA, GLBA, OPPA, etc.) -- **Business criticality** -- **Platform** (e.g., API, Desktop, IoT, Mobile, Web, etc.) -- **Lifecycle** (e.g., Construction, Production, Retirement, etc.) -- **Origin** (e.g., Third-Party Library, Purchased, Open Source, etc.) -- **User records** (i.e., the estimated number of user records in the Product) -- **Revenue** - -This metadata improves filtering, reporting, and prioritization across your security program, but most importantly, Products also contain all of the Engagements, Tests, and Findings related to the testing efforts surrounding that Product. All Findings from Tests ultimately roll up to the Product level, enabling long-term tracking, trend analysis, and reporting. - -## Accessing Products - -Products are accessible via the sidebar. The submenu also provides the option to create a new Product. - -![image](images/product_ss3.png) - -### Permissions - -Products can have Role-Based Access Control (RBAC) rules applied, which limit team members’ ability to view and interact with them. - -Permissions cascade downward, meaning that access to a Product automatically grants access to all objects within that Product (e.g., Engagements, Tests, and Findings). - -For more information on user roles, see our [Introduction To Roles article](/admin/user_management/about_perms_and_roles/). - -## Product View - -Product views contain a variety of tables and charts to interpret a Product’s status at a glance. This includes: - -- **Metadata** - - Including Product Type, business criticality, revenue, and other details added from the Product settings. -- **Metrics** - - A list of open Findings within the Product, grouped by severity -- **Service Level Agreement by Severity** - - Applies the Product SLA configuration from settings to the Findings within the Product. -- **Technologies** - - E.g., next.js, vue.js, npm v.1.2.3, Django, nginx, Hugo -- **Regulations** -- **Benchmark Progress** -- **Members** -- **Groups** -- **Contacts** -- **Notifications** - - Toggles notifications on and off depending on specific events (e.g., an Engagement has been added or closed) - -## Working with Products - -### Create Products - -There are multiple ways to create a new Product, including: - -- The **Add Product** button in the All Products list - -![image](images/product_ss2.png) - -- From the dropdown menu of the Products table within a Product Type’s view - - This will automatically create the Product within that Product Type. - -![image](images/product_ss1.png) - -- The **Add Product** button in the sidebar - -![image](images/product_ss5.png) - -### Edit Products - -A Product can be edited from its settings, which can be accessed in two ways: - -- The **Edit** button within ⋮ kebab menu to the left of the Product in the All Products view - -![image](images/product_ss6.png) - -- The **Edit** button within the **Settings** dropdown in the Product’s view - -![image](images/product_ss7.png) - -### Delete Products - -The option to delete a Product can be found at the bottom of the same menus described in the **Edit Products** section above. This action can’t be undone. Product can’t be closed and reopened later. - -Deleting a Product will also delete the following: -- Any Engagements and Tests contained within the Product -- All associated security history, including Findings and integrations -- Any linked Jira Epics -- All notes and file uploads associated with the Product’s Engagements and Tests - -## Product Boundaries - -### Deduplication - -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. Findings across different Products will not be automatically deduplicated. - -### Metrics - -Most reporting and metrics aggregate data at the Product level, making Products the primary unit for measuring and tracking risk. - -As a result, many key metrics are calculated per Product, including: - -- Total number of Findings (by severity or status) -- Mean time to remediate (MTTR) -- SLA compliance and breach rates -- Risk trends over time - -This means that how Products are structured will directly impact the accuracy and usefulness of reports. For example, grouping multiple unrelated systems under a single Product may obscure risk visibility, while overly granular Product structures can fragment reporting, making it difficult to identify broader trends. - -Product-specific metrics can be accessed from the **Metrics** button in the top bar of the chosen Product’s view. - -![image](images/product_ss8.png) - -### CI/CD Pipeline - -CI/CD pipelines automate the import of scan results. Regardless of the integration method, all scan imports must be associated with a Product, making the Product the anchor point for pipeline-driven security data. - -When a pipeline submits scan results, it must either: - -- Specify an existing Product (and optionally an Engagement), or -- Be configured in a way that consistently maps results to the correct Product - -All imported Findings will inherit the Product’s context, including ownership, permissions, SLA configuration, and reporting scope. - -In practice, Products should be defined to reflect how systems are built and deployed within CI/CD to ensure that security results are consistently associated with the correct application or service. - -### Jira Relationships - -Products can be mapped directly to Jira Projects, which push the Product’s Findings into a Jira instance. - -Because Findings inherit risk, priority, and ownership from their parent Product, the Product effectively determines the remediation context that flows into Jira tickets and Integrator workflows. - -Importantly, Products are also the primary determining factor in a Finding’s SLA characteristics. Therefore, the SLA of a Findings depends on the SLA configuration of its parent Product. More information about SLA configurations can be found [here](/asset_modelling/os_hierarchy/os__sla_configuration/#main-content). diff --git a/docs/content/asset_modelling/engagements_tests/OS_producttype.md b/docs/content/asset_modelling/engagements_tests/OS_producttype.md deleted file mode 100644 index 4fb37c688be..00000000000 --- a/docs/content/asset_modelling/engagements_tests/OS_producttype.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: "Product Types" -description: "Understanding Product Types in DefectDojo OS" -audience: opensource -weight: 1 ---- -**PRODUCT TYPES** → Products → Engagements → Tests → Findings - -## Overview - -**Product Types** sit at the very top of DefectDojo’s product hierarchy. Product Types are distinct from the descending objects in the hierarchy—Products, Engagements, Tests, and Findings—because they are not technical scan targets, but rather serve primarily as organizational abstractions that compartmentalize your security efforts according to: -- Business domain -- Development team -- Security team -- Software applications -- Overarching product family -- Customer or subsidiary -- Reporting structure -- etc. - -The theme of the above examples exemplifies the essential utility of Product Types: they should generally represent stable, long-lived boundaries within your security program. - -## Product Type Data and Structure - -As Product Types are not scanned directly, the only mandatory field required to create them is a name. Beyond that, they act as containers for Products and their descending Engagements, Tests, and Findings. - -When creating a Product Type, consider how their structure will inform your reporting. Do you primarily need Product Types to represent the teams working on the projects (Products) that Product Types will contain? Or would Product Types better represent overarching projects that contain different iterations of the projects (Products) within it? - -If you have a single Product Type that contains all of the relevant information for a given business domain or development team, having that represented as a Product Type will facilitate smoother reporting, rather than having to pull together a report from various Products and Product Types. - -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. In some workflows, Product Types may also be used to separate software lifecycle stages: one Product Type for “In Development,” one Product Type for “In Production,” etc. -​ -Product Types can be used to determine access to subsidiaries, acquired companies, or other regulated business units for RBAC purposes. In complex businesses, where there are a lot of unique projects with different access rules, Product Types are particularly relevant. - -Ultimately, the decision of how to use Product Types and Products depends on how you best wish to reflect your unique organizational structure and the needs of your security team. - -Below are some example structures to inform how you designate your objects as either Product Types or Products. - -- **Product Type**: Payments Division - - Product: Payments API - Production - - Product: Payments API - Staging - - Product: Billing Worker - -- **Product Type**: Software Product A - - Product: Web Portal - - Product: Mobile Backend - -Additionally, the following is an illustrative guide as to whether a something is better represented by a Product Type or an Product: - -| Product Types | Products | -|--------------|--------| -| Business units | Individual applications | -| Departments | Deployments/environments | -| Security ownership domains | Infrastructure components | -| Product families | Specific microservices | -| Portfolio-level reporting | Scan targets | -| Customers | Specific software versions | - -As noted, your structure may differ depending on your unique security needs. - -## Accessing Product Types - -Product Types are accessible via the sidebar. The submenu also provides the option to create new Product Types. - -![image](images/PT_ss2.png) - -### Product Type View - -A Product Type’s view contains a variety of tables and charts to interpret its status at a glance. This includes: -- **Description** -- **Key/Critical Checkbox** - - Checking Critical or Key is used solely for filtering purposes -- **List of Products within the Product Type** -- **Authorized Users** (DefectDojo Users) - -## Working with Product Types - -### Create Product Types - -There are two ways to create Product Types: - -- From the **Add Product Type** option in the side menu -- From the **Add Product Type** button at the top of the All Product Type list - -### Edit Product Types - -Product Types can be edited by clicking **Edit** from within the dropdown menu at the top right of the Description table in the Product Type’s view. The same menu can also be accessed by clicking the ⋮ kebab menu to the left of the Product Type in the All Product Type list. - -All ensuing fields that can be edited are also available when the Product Type is being created. - -### Delete Product Types - -Deleting a Product Type can be performed by selecting **Delete Product Type** from the Product Type’s settings. - -Because Product Types sit at the top of the hierarchy, deleting them removes all downstream security history, relationships, and child objects, such as: -- Any Products, Engagements, and Tests contained within the Product Type -- All associated security history, including Findings and integrations -- Any linked Jira Epics -- All notes and file uploads associated with the Products, Engagements, and Tests within that Product Type - -Deleting a Product Type can’t be undone. If you would like to “decommission” a Product Type without deleting underlying data (for example, preserving legacy software testing records for audit purposes), you can change the Product Type’s name or add a Tag to indicate that it is in a deprecated state. - -## Product Types vs. Metadata - -Product Types are intended to represent structural ownership or reporting boundaries, rather than lightweight classifications. Attributes such as deployment status, internal labels, or temporary workflow states may be better represented through tags or metadata rather than separate Product Types. - -## Product Type Boundaries - -Product Types establish both reporting and access boundaries within DefectDojo. Because integrations, RBAC permissions, ownership, metrics, and deduplication models frequently inherit Product Types’ structure, designing clear boundaries early helps avoid hierarchy sprawl and reporting fragmentation later. - -### Findings and Automation - -Although integrations are typically configured on lower-level objects such as Product Types, Engagements, or Findings, Product Types still define the ownership, reporting, and access boundaries within which those integrations operate. - -Permissions cascade downward, meaning that access to a Product Type automatically grants access to all objects within that Product Type (e.g., Product Types, Engagements, Tests, and Findings). - -The DefectDojo RBAC model can be used to gate human user access, but can also restrict API tokens’ access to particular Product Types. - -For more information on user roles, see our [Permissions](/admin/user_management/os__authorized_users/) article. - -### Ownership - -As top-level objects, Product Types also imply ownership over the child objects within them. SLA tracking, remediation workflows, ticket routing, and general governance all flow more smoothly when Product Types have been set up to accurately reflect the individuals accountable for them. - -### Metrics/Reporting - -Metrics dashboards, tiles and views can be filtered per Product Type, making them a critical component in how your security data is calculated, visualized, and ultimately exported. - -For reporting purposes, it is generally easier to combine multiple Product Types into a single document than it is to subdivide a single Product Type into separate documents. Therefore, we recommend setting up Product Types at as granular a level as makes sense for your team’s reports. For example, there is no need to represent a large business division as a Product Type if you’re primarily going to be reporting to individual departments within that division. - -Effectively structuring your Product Types to reflect your reporting needs is critical to accurately assessing your security posture. For more information on Metrics, click [here](/metrics_reports/dashboards/introduction_dashboard/). - -### Deduplication - -Deduplication in DefectDojo occurs at the Product level, and is not affected by the parent Product Type. diff --git a/docs/content/asset_modelling/tags/OS__tagging_objects.md b/docs/content/asset_modelling/tags/OS__tagging_objects.md index 4dcf74b87fd..56e108f0570 100644 --- a/docs/content/asset_modelling/tags/OS__tagging_objects.md +++ b/docs/content/asset_modelling/tags/OS__tagging_objects.md @@ -7,12 +7,12 @@ exclude_search: false audience: opensource --- -Tags are ideal for grouping objects in a manner that can be filtered out into smaller, more digestible chunks. They can be used to denote status, or to create custom sets of Product Type, Products, Engagements or Findings across the data model. +Tags are ideal for grouping objects in a manner that can be filtered out into smaller, more digestible chunks. They can be used to denote status, or to create custom sets of Organizations, Assets, Engagements or Findings across the data model. In DefectDojo, tags are a first class citizen and are recognized as the facilitators of organization within each level of the data model. -Here is an example with a Product with two tags and four findings each with a single tag: +Here is an example with an Asset with two tags and four findings each with a single tag: ![High level example of usage with tags](images/tags-high-level-example.png) @@ -35,7 +35,7 @@ Tags can be managed in the following ways: When a new object is created or edited through the UI or API, there is a field for specifying the tags to be set on a given object. This field is a multiselect field that also has auto completion to make searching and adding existing tags a breeze. Here is what the field - looks like on the Product from the screenshot in the previous section: + looks like on the Asset from the screenshot in the previous section: ![Tag management on an object](images/tags-management-on-object.png) @@ -71,17 +71,17 @@ Tags can be managed in the following ways: ## Tag Inheritance -When Tag Inheritance is enabled, tags applied to a given Product will automatically be applied to all objects under Products in the [Product Hierarchy](/asset_modelling/os_hierarchy/product_hierarchy/). +When Tag Inheritance is enabled, tags applied to a given Asset will automatically be applied to all objects under Assets in the [Asset Hierarchy](/asset_modelling/os_hierarchy/os__asset_hierarchy/). ### Configuration Tag Inheritance can be enabled at the following scope levels: - Global Scope - - Every Product system wide will begin applying tags to all children objects (Engagements, Tests and Findings) + - Every Asset system wide will begin applying tags to all children objects (Engagements, Tests and Findings) - This is set within the System Settings -- Product Scope - - Only the selected Product will begin applying tags to all children objects (Engagements, Tests and Findings) - - This is set at the Product creation/edit page +- Asset Scope + - Only the selected Asset will begin applying tags to all children objects (Engagements, Tests and Findings) + - This is set at the Asset creation/edit page ### Behaviors @@ -91,7 +91,7 @@ See the following example of adding a tag "test_only_tag" to the Test object and ![Example of inherited tags](images/tags-inherit-exmaple.png) -When updates are made to the tag list on a Product, the same changes are made to all objects within the Product asynchronously. The duration of this task directly correlates to the number the objects contained within a finding. +When updates are made to the tag list on an Asset, the same changes are made to all objects within the Asset asynchronously. The duration of this task directly correlates to the number the objects contained within a finding. **Open-Source:** If Tag changes are not observed within a reasonable time period, consult the celery worker logs to identify where any problems might have arisen. @@ -145,5 +145,5 @@ but at different levels in the data model: - Not Tags (Test): filter on any tags that are *not* attached to the Test of a given Finding - Tags (Engagement): filter on any tags that are attached to the Engagement of a given Finding - Not Tags (Engagement): filter on any tags that are *not* attached to the Engagement of a given Finding - - Tags (Product): filter on any tags that are attached to the Product of a given Finding - - Not Tags (Product): filter on any tags that are *not* attached to the Product of a given Finding + - Tags (Asset): filter on any tags that are attached to the Asset of a given Finding + - Not Tags (Asset): filter on any tags that are *not* attached to the Asset of a given Finding