diff --git a/docs/assets/images/assets_ss1.png b/docs/assets/images/assets_ss1.png new file mode 100644 index 00000000000..b791e78c5a9 Binary files /dev/null and b/docs/assets/images/assets_ss1.png differ diff --git a/docs/assets/images/assets_ss2.png b/docs/assets/images/assets_ss2.png new file mode 100644 index 00000000000..34a2bda5550 Binary files /dev/null and b/docs/assets/images/assets_ss2.png differ diff --git a/docs/assets/images/engagements_ss99.png b/docs/assets/images/engagements_ss99.png new file mode 100644 index 00000000000..6deddded007 Binary files /dev/null and b/docs/assets/images/engagements_ss99.png differ diff --git a/docs/assets/images/product_ss1.png b/docs/assets/images/product_ss1.png new file mode 100644 index 00000000000..956eb53493b Binary files /dev/null and b/docs/assets/images/product_ss1.png differ diff --git a/docs/assets/images/product_ss2.png b/docs/assets/images/product_ss2.png new file mode 100644 index 00000000000..cd37c0578d7 Binary files /dev/null and b/docs/assets/images/product_ss2.png differ diff --git a/docs/assets/images/product_ss3.png b/docs/assets/images/product_ss3.png new file mode 100644 index 00000000000..f45fa3cdb8c Binary files /dev/null and b/docs/assets/images/product_ss3.png differ diff --git a/docs/assets/images/product_ss4.png b/docs/assets/images/product_ss4.png new file mode 100644 index 00000000000..40a7c227bcd Binary files /dev/null and b/docs/assets/images/product_ss4.png differ diff --git a/docs/assets/images/product_ss5.png b/docs/assets/images/product_ss5.png new file mode 100644 index 00000000000..4ea580146c0 Binary files /dev/null and b/docs/assets/images/product_ss5.png differ diff --git a/docs/assets/images/product_ss6.png b/docs/assets/images/product_ss6.png new file mode 100644 index 00000000000..3f372106104 Binary files /dev/null and b/docs/assets/images/product_ss6.png differ diff --git a/docs/assets/images/product_ss7.png b/docs/assets/images/product_ss7.png new file mode 100644 index 00000000000..d7da19c5cb5 Binary files /dev/null and b/docs/assets/images/product_ss7.png differ diff --git a/docs/assets/images/product_ss8.png b/docs/assets/images/product_ss8.png new file mode 100644 index 00000000000..4840d71fd63 Binary files /dev/null and b/docs/assets/images/product_ss8.png differ diff --git a/docs/content/asset_modelling/engagements_tests/OS__calendar.md b/docs/content/asset_modelling/engagements_tests/OS__calendar.md index 74d7afbf31f..64286709dbb 100644 --- a/docs/content/asset_modelling/engagements_tests/OS__calendar.md +++ b/docs/content/asset_modelling/engagements_tests/OS__calendar.md @@ -2,7 +2,7 @@ title: "Calendar" description: "How to use the Calendar in DefectDojo Pro" audience: opensource -weight: 2 +weight: 9 --- DefectDojo’s Calendar provides a centralized timeline view of all Engagements and Tests with defined start and end dates, allowing Users to quickly understand testing activity across Products, identify scheduling overlaps, and navigate directly to related objects. diff --git a/docs/content/asset_modelling/engagements_tests/OS__engagements.md b/docs/content/asset_modelling/engagements_tests/OS__engagements.md index b6b28ddf0a6..781f654af44 100644 --- a/docs/content/asset_modelling/engagements_tests/OS__engagements.md +++ b/docs/content/asset_modelling/engagements_tests/OS__engagements.md @@ -2,7 +2,7 @@ title: "Engagements" description: "Understanding Engagements in DefectDojo OS" audience: opensource -weight: 2 +weight: 3 --- Product Types → Products → **ENGAGEMENTS** → Tests → Findings diff --git a/docs/content/asset_modelling/engagements_tests/OS__products.md b/docs/content/asset_modelling/engagements_tests/OS__products.md new file mode 100644 index 00000000000..0a2fa253a25 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/OS__products.md @@ -0,0 +1,177 @@ +--- +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) + +## Product Lifecycle + +### 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__tests.md b/docs/content/asset_modelling/engagements_tests/OS__tests.md index fe0f7e7078e..bda58c23bbf 100644 --- a/docs/content/asset_modelling/engagements_tests/OS__tests.md +++ b/docs/content/asset_modelling/engagements_tests/OS__tests.md @@ -2,7 +2,7 @@ title: "Tests" description: "Understanding Tests in DefectDojo OS" audience: opensource -weight: 2 +weight: 4 --- Organizations → Assets → Engagements → **TESTS** → Findings diff --git a/docs/content/asset_modelling/engagements_tests/PRO__assets.md b/docs/content/asset_modelling/engagements_tests/PRO__assets.md new file mode 100644 index 00000000000..cceb22d07c9 --- /dev/null +++ b/docs/content/asset_modelling/engagements_tests/PRO__assets.md @@ -0,0 +1,185 @@ +--- +title: "Assets" +description: "Understanding Assets in DefectDojo Pro" +audience: pro +weight: 2 +--- +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: + +- **Organization** +- **Unique name** +- **Description** +- **SLA Configuration** +- **Prioritization Engine** + +Optional Asset metadata includes: + +- **Tags** +- **Business criticality** +- **User records** (i.e., the estimated number of user records in the Asset) +- **Revenue** +- **Personnel information** (e.g., Asset Manager, Team Manager, Technical Contact, etc.) +- **Regulations** (e.g., HIPAA, GLBA, OPPA, etc.) +- **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.) + +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 provides access to the [Asset Hierarchy](/asset_modelling/engagements_tests/pro__assets/#asset-nesting) and All Assets, as well as the option to create a new Asset. + +![image](images/assets_ss1.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](/admin/user_management/set_user_permissions/#introduction-to-permission-types) article. + +## Asset View + +Asset views contain a variety of tables and charts to interpret an Asset’s status at a glance. This includes: + +- **Open Finding Severity** + - A list of open Findings within the Asset, grouped by severity +- **Asset Overview** + - A breakdown of various features of the Asset, including Description, Components, Contacts, [User Groups](/admin/user_management/create_user_group/ +), Members, Technologies, and Regulations. + - Technologies: next.js, vue.js, npm v.1.2.3, Django, nginx, Hugo +- **Metadata** + - Including parent and child Assets, Organization, business criticality, revenue, and other details added from the Asset’s settings. +- **Service Level Agreement by Severity** + - Applies the Asset’s SLA configuration from settings to the Findings within the Asset. +- **Finding Severity Breakdown** + - A graph of the Findings within the Asset, organized by severity. +- **Finding Distribution** + - A breakdown of the Findings within the Asset, organized by status (e.g., Active, Mitigated, Static, and Dynamic) +- **All Engagements** + - A list of Engagements contained within the Asset. + +## Asset Lifecycle + +### Create Assets + +There are two ways to create Assets: + +- From the **New Asset** option in the side menu +- From the **New Asset** button at the top of the All Assets list + +## Edit Assets + +Assets can be edited by clicking **Edit Asset** from within the gear menu at the top right of the Asset’s view. The same menu can also be accessed by clicking the ⋮ kebab menu to the left of the Asset in the All Assets view. + +All ensuing fields that can be edited are also available when the Asset is being created. + +![image](images/assets_ss2.png) + +### Delete Assets + +Deleting an Asset can be performed by selecting **Delete Asset** from the Asset’s settings. This action can’t be undone. Assets 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. + +### Reporting and 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. + +### Connectors + +In DefectDojo Pro, Connectors are mapped to different Assets in DefectDojo Pro, making them the primary integration point between DefectDojo and your broader security ecosystem. + +Once a Connector has been attached to an Asset, it will import scan results and create or update Engagements, Tests, and Findings within that Asset. + +For more information about Connectors, click [here](/import_data/pro/connectors/about_connectors/#main-content). + +### CI/CD Pipelines + +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, priority/risk 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. + +### SLAs, Priority, and Risk + +In DefectDojo Pro, Findings inherit their SLA targets, Priority, and Risk from the Asset that contains them. Asset metadata (e.g., business criticality, revenue, etc.) are used to automatically calculate Priority and Risk values. + +This means that the same vulnerability may receive a different Priority or Risk score depending on whether it affects an internal development system or a production asset supporting critical business operations. + +### Jira / Integrators Relationships + +Assets can be mapped directly to [Jira](/issue_tracking/jira/pro__jira_guide/#main-content) or [Integrators](/issue_tracking/pro_integration/integrations_toolreference/#main-content) instances (e.g. GitHub, GitLab, ServiceNow, etc.), which push the Asset’s Findings outward into external ticketing/work-management systems. + +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/pro_hierarchy/priority_sla/#working-with-slas). + +## Asset Nesting + +DefectDojo supports parent-child relationship between two Assets within the same Organization. This can be configured during Asset creation or in the Asset’s settings. + +You can visualize the structure of Assets in DefectDojo and change relationships using the **Asset Hierarchy** option in the sidebar. + +After selecting the Assets to be visualized from the corresponding table, click **View Asset Hierarchy** to generate a flow chart of the relationship between the chosen Assets, if any. + +Further information on the effect of nesting Assets on deduplication, RBAC, and other details, as well as example use cases, can be found [here](/asset_modelling/hierarchy/pro__assets_organizations/#asset-nesting-examples). \ No newline at end of file diff --git a/docs/content/asset_modelling/engagements_tests/PRO__calendar.md b/docs/content/asset_modelling/engagements_tests/PRO__calendar.md index 0509fb09ca4..d6bcafee948 100644 --- a/docs/content/asset_modelling/engagements_tests/PRO__calendar.md +++ b/docs/content/asset_modelling/engagements_tests/PRO__calendar.md @@ -2,7 +2,7 @@ title: "Calendar" description: "How to use the Calendar in DefectDojo Pro" audience: pro -weight: 2 +weight: 9 --- DefectDojo features a built-in Calendar so you can track all prior and active Engagements and Tests within your organization. Any time a User creates a new Engagement or Test and establishes the start and end dates, a corresponding entry will automatically be added to the Calendar. diff --git a/docs/content/asset_modelling/engagements_tests/PRO__engagements.md b/docs/content/asset_modelling/engagements_tests/PRO__engagements.md index 8fcba6738ce..06973a2e490 100644 --- a/docs/content/asset_modelling/engagements_tests/PRO__engagements.md +++ b/docs/content/asset_modelling/engagements_tests/PRO__engagements.md @@ -2,7 +2,7 @@ title: "Engagements" description: "Understanding Engagements in DefectDojo Pro" audience: pro -weight: 2 +weight: 3 --- Organizations → Assets → **ENGAGEMENTS** → Tests → Findings @@ -70,7 +70,7 @@ Engagements sit below Assets and above Tests in the object hierarchy. As such, a ### Create Engagements -Before creating an Engagement, you must first have created an Asset to contain it. +Before creating an Engagement, you must first have [created an Asset](/asset_modelling/engagements_tests/pro__assets/#create-assets) to contain it. There are several ways to create an Engagement: @@ -117,7 +117,11 @@ Changing an Engagement’s status to “Completed” will mean that most write o ### Edit Engagements -Engagements can be edited by clicking **Edit Engagement** from within the gear menu. All ensuing fields that can be edited are also available when the Engagement is being created. +Engagements can be edited by clicking **Edit Engagement** from within the gear menu. The same menu can also be accessed by clicking the ⋮ kebab menu to the left of the Asset in the All Assets view. + +All ensuing fields that can be edited are also available when the Engagement is being created. + +![image](images/engagements_ss99.png) ### Copy Engagements diff --git a/docs/content/asset_modelling/engagements_tests/PRO__tests.md b/docs/content/asset_modelling/engagements_tests/PRO__tests.md index dbe4e3f9629..9eb3c550729 100644 --- a/docs/content/asset_modelling/engagements_tests/PRO__tests.md +++ b/docs/content/asset_modelling/engagements_tests/PRO__tests.md @@ -2,7 +2,7 @@ title: "Tests" description: "Understanding Tests in DefectDojo Pro" audience: pro -weight: 2 +weight: 4 --- Organizations → Assets → Engagements → **TESTS** → Findings