Add Pro+OS Environments documentation (plus other docs updates)

docs/content/asset_modelling/engagements_tests/OS__engagements.md

@@ -44,11 +44,10 @@ As the containers that organize testing activity, Engagements can store or track
 - Assignee / Lead
 - Associated Tests (e.g., scans, pen tests, manual tests, etc.)
 - Findings and Finding Types (e.g., active, mitigated, risk accepted, duplicate, etc.) 
-- Threat models or risk acceptance info
+- Risk acceptance info
 - Tags
 - Files and notes
 - Jira project settings
-- Environment details (e.g., staging vs. production)
 - Build IDs (if linked to CI/CD)
 - Historical data from past Tests within the Engagement 
 

docs/content/asset_modelling/engagements_tests/OS__environments.md

@@ -0,0 +1,65 @@
+---
+title: "Environments"
+description: "Understanding Environments in OS DefectDojo"
+audience: opensource
+weight: 8
+---
+**Environments** define the operational or deployment context associated with a Test, providing additional details about where the underlying security testing was performed or where its scan data originated.
+
+While Environment names are fully customizable, common examples of Environments include:
+- Development
+- QA
+- Staging
+- Production
+
+Environments are associated with individual Tests rather than directly with Assets or Engagements. This allows different Tests within the same Engagement to represent testing efforts performed in different Environments, and also helps to filter Testing efforts accordingly.
+
+Notably, Environments do not affect Priority scoring or otherwise influence DefectDojo's core data model. 
+
+### Accessing Environments 
+
+Environments are accessible from the Engagements submenu in the sidebar.
+
+### Permissions 
+
+All Users can view the list of existing Environments, regardless of their global role.
+
+However, creating, editing, and deleting Environments is limited to Users with Superuser and Staff status.
+
+## Working with Environments 
+
+### Creating Environments
+
+Environments can be created by clicking the **New Environment** button within the tools menu in the upper-right corner of the Environments view. From there, enter a name for the Environment and click **Submit**. 
+
+Once created, the Environment becomes available for selection when creating or importing Tests.
+
+### Editing Environments 
+
+Environments can be edited by clicking on the Environment name. Edit the name and then click Update. 
+
+Renaming an Environment updates the name displayed for all Tests associated with that Environment. For example, if an Environment named _Production_ is renamed to _Prod_, associated Tests will display Prod as their Environment.
+
+### Deleting Environments 
+
+Environments can be deleted by clicking on the Environment name and clicking **Delete** on the ensuing page. 
+
+Importantly, an Environment cannot be deleted while it is associated with one or more Tests. Environments must be unlinked from all Tests before being deleted.
+
+## Associating Environments with Tests
+
+Environments can be associated with Tests either manually or via DefectDojo’s API. 
+
+### Manual
+
+To associate an Environment with a Test, edit the Test and select the desired Environment from the Environment dropdown menu.
+
+![image](images/osenvironments_ss2.png)
+
+### API
+
+When creating Tests through the DefectDojo API, you can include Environment information in the request and apply it as the Test is created.  This allows automated workflows to capture the context in which testing was performed (e.g., whether scan results originated from a Development, Staging, or Production environment) and store the results in DefectDojo.
+
+By default, the specified Environment must already exist in DefectDojo. However, you can add `auto_create_context: true` to the API payload to automatically create an Environment if it does not already exist. If `auto_create_context` is set to `false` (or unspecified) and the specified Environment does not exist, the request will be rejected. 
+
+For example, an automation pipeline can specify `Staging` as the Environment when creating a Test. If the Environment already exists, it will be associated with the Test. If it does not exist, it can be created automatically when `auto_create_context` is enabled.

docs/content/asset_modelling/engagements_tests/OS__regulations.md

@@ -50,7 +50,7 @@ Regulations can be edited by clicking on the Regulation name. Change any desired
 
 ### Deleting Regulations 
 
-Regulations can be deleted by clicking on the Regulation name and selecting **Delete** on the ensuing page. 
+Regulations can be deleted by clicking on the Regulation name and selecting **Delete** on the ensuing page. Deleting a Regulation while it is still linked to an Asset will remove it from that Asset. 
 
 As noted previously, the ability to create, edit, and delete Regulations is reserved only for Superusers.
 

docs/content/asset_modelling/engagements_tests/OS__tests.md

@@ -210,9 +210,9 @@ In order to add new data to an existing Test, you can either click **Re-Upload S
 
 ![image](images/tests_ss10.png)
 
-While completing the Reimport Scan form, you’ll have the option to update metadata for the scan being reimported, including the version, branch tag, commit hash, and build ID. 
+While completing the Reimport Scan form, you’ll have the option to update metadata for the scan being reimported, including the version, branch tag, commit hash, and build ID. Note that Test metadata such as Environment can't be changed through a reimport pipeline.
 
-These changes are reflected in the Import History section of the Test View, which will also include the same metadata from prior scan imports.
+The updated metadata are reflected in the Import History section of the Test View, which will also include the same metadata from prior scan imports. 
 
 For example, in the below screenshot, the branch tag, build ID, commit hash, and version were all manually updated between the initial import and the subsequent reimport.
 

docs/content/asset_modelling/engagements_tests/PRO__engagements.md

@@ -44,11 +44,10 @@ As the containers that organize testing activity, Engagements can store or track
 - Assignee / Lead
 - Associated Tests (e.g., scans, pen tests, manual tests, etc.)
 - Findings and Finding Types (e.g., active, mitigated, risk accepted, duplicate, etc.) 
-- Threat models or risk acceptance info
+- Threat models (if enabled)
 - Tags
 - Files and notes
 - Jira project settings
-- Environment details (e.g., staging vs. production)
 - Build IDs (if linked to CI/CD)
 - Historical data from past Tests within the Engagement 
 

docs/content/asset_modelling/engagements_tests/PRO__environments.md

@@ -0,0 +1,73 @@
+---
+title: "Environments"
+description: "Understanding Environments in DefectDojo Pro"
+audience: pro
+weight: 8
+---
+**Environments** define the operational or deployment context associated with a Test, providing additional details about where the underlying security testing was performed or where its scan data originated.
+
+While Environment names are fully customizable, common examples of Environments include:
+- Development
+- QA
+- Staging
+- Production
+
+Environments are associated with individual Tests rather than directly with Assets or Engagements. This allows different Tests within the same Engagement to represent testing efforts performed in different Environments, and also helps to filter Testing efforts accordingly.
+
+Notably, Environments do not affect Priority scoring or otherwise influence DefectDojo's core data model.
+
+### Accessing Environments 
+
+Environments are accessible from the Configuration submenu in the sidebar.
+
+![image](images/proenvironments_ss1.png)
+
+### Permissions
+
+All Users can view the list of existing Environments, regardless of their global role.
+
+However, creating, editing, and deleting Environments is limited to Superusers and Users who have been granted the appropriate [Configuration Permission](/admin/user_management/about_perms_and_roles/#configuration-permissions). 
+
+![image](images/proenvironments_ss3.png)
+
+Configuration Permissions are separate from permissions associated with Assets and Organizations. As a result, access to manage Environments can be granted independently of a user's role within a specific Asset or Organization.
+
+## Working with Environments 
+
+### Creating Environments 
+
+Environments can be created by clicking the **New Environment** button. From there, enter a name for the Environment and click **Submit**. 
+
+Once created, the Environment becomes available for selection when creating or importing Tests.
+
+### Editing Environments 
+
+Environments can be edited by clicking the ⋮ kebab icon to the left of the desired Environment and selecting **Edit Environment** from the dropdown menu.
+
+Renaming an Environment updates the name displayed for all Tests associated with that Environment. For example, if an Environment named _Production_ is renamed to _Prod_, associated Tests will display Prod as their Environment.
+
+### Deleting Environments 
+
+Environments can be deleted by clicking the ⋮ kebab icon to the left of the desired Environment and selecting **Delete Environment** from the dropdown menu.
+
+Importantly, an Environment cannot be deleted while it is associated with one or more Tests. Environments must be unlinked from all Tests before being deleted.
+
+## Associating Environments with Tests
+
+Environments are associated with individual Tests rather than directly with Assets or Engagements. This allows different Tests within the same Engagement to represent testing efforts performed in different Environments. 
+
+Environments can be associated with Tests either manually or via DefectDojo’s API. 
+
+### Manual
+
+To associate an Environment with a Test, edit the Test and select the desired Environment from the dropdown menu.
+
+![image](images/proenvironments_ss2.png)
+
+### API
+
+When creating Tests through the DefectDojo API, you can include Environment information in the request and apply it as the Test is created.  This allows automated workflows to capture the context in which testing was performed (e.g., whether scan results originated from a Development, Staging, or Production environment) and store the results in DefectDojo.
+
+By default, the specified Environment must already exist in DefectDojo. However, you can add `auto_create_context: true` to the API payload to automatically create an Environment if it does not already exist. If `auto_create_context` is set to `false` (or unspecified) and the specified Environment does not exist, the request will be rejected. 
+
+For example, an automation pipeline can specify `Staging` as the Environment when creating a Test. If the Environment already exists, it will be associated with the Test. If it does not exist, it can be created automatically when `auto_create_context` is enabled.

docs/content/asset_modelling/engagements_tests/PRO__regulations.md

@@ -50,7 +50,7 @@ Regulations can be edited by clicking the ⋮ kebab icon to the left of the desi
 
 ### Deleting Regulations 
 
-Regulations can be deleted by clicking the ⋮ kebab icon to the left of the desired Regulation and selecting **Delete Regulation** from the dropdown menu.
+Regulations can be deleted by clicking the ⋮ kebab icon to the left of the desired Regulation and selecting **Delete Regulation** from the dropdown menu. Deleting a Regulation while it is still linked to an Asset will remove it from that Asset.
 
 As noted previously, the ability to create, edit, and delete Regulations is reserved only for Superusers.
 

docs/content/asset_modelling/engagements_tests/PRO__tests.md

@@ -182,7 +182,9 @@ In order to add new data to an existing Test, open the Test you’re adding new
 
 ![image](images/tests_ss21.png)
 
-While completing the Reimport Scan form, you’ll have the option to update metadata for the scan being reimported, including the version, branch tag, commit hash, and build ID. These changes are reflected in the Import History section of the Test View, which will also include the same metadata from prior scan imports. 
+While completing the Reimport Scan form, you’ll have the option to update metadata for the scan being reimported, including the version, branch tag, commit hash, and build ID. Note that Test metadata such as Environment can't be changed through a reimport pipeline.
+
+The updated metadata are reflected in the Import History section of the Test View, which will also include the same metadata from prior scan imports. 
 
 For example, in the below screenshot, the branch tag, build ID, commit hash, and version were all manually updated between the initial import and the subsequent reimport.