Merge pull request #222 from redhat-appstudio/embargo-processing

Handling private issues

docs/modules/ROOT/nav-how-to-guides.adoc

@@ -14,7 +14,11 @@
 *** xref:how-to-guides/testing_applications/proc_creating_custom_test.adoc[Creating a custom integration test]
 ** Managing environments
 *** xref:how-to-guides/managing-environments/con_overview_of_environments.adoc[Overview of {ProductName} environments]
-*** xref:how-to-guides//managing-environments/proc_creating_your_own_environment.adoc[Creating your own environment]
+*** xref:how-to-guides/managing-environments/proc_creating_your_own_environment.adoc[Creating your own environment]
+** Managing applications
+*** xref:how-to-guides/managing-applications/proc-managing_applications.adoc[Managing a security fix]
+** Managing workspaces
+*** xref:how-to-guides/managing-workspaces/proc-creating_a_team_workspace.adoc[Creating a team workspace]
 ** Securing your supply chain
 *** xref:how-to-guides/Secure-your-supply-chain/proc_inspect_sbom.adoc[Inspecting SBOMs]
 *** xref:how-to-guides/Secure-your-supply-chain/proc_inspect-slsa-provenance.adoc[Downloading your SLSA provenance]

docs/modules/ROOT/pages/getting-started/getting_started_in_cli.adoc

@@ -14,15 +14,19 @@ To log in to {ProductName} by using the CLI, complete the following steps:
 . Select the checkbox next to *I agree to the Terms and Conditions*.
 . Select *Get started with OpenShift Developer Sandbox*.
 . In the webpage banner, select *Proxy login command*.
-. Click the *copy icon* to copy the command and your unique token. 
-. Open your terminal and paste the command that you copied in the previous step. This command runs `oc login --token=[your token]`. 
+. Click the *copy icon* to copy the command and your unique token.
+. Open your terminal and paste the command that you copied in the previous step. This command runs `oc login --token=[your token] [appstudio api url]`.
 
 .Verification
 
 To verify that `oc login` worked correctly, complete the following steps:
 
 . Run `cd ~/.kube`.
-. Run `ls` and verify that there is a file named `config`. 
+. Run `ls` and verify that there is a file named `config`.
+
+== Switching workspaces
+
+To use the CLI tool with a workspace other than your default personal workspace, append `/workspaces/<workspace-name>` to the AppStudio API url used in your `oc login` command in step 6.
 
 == oc commands for {ProductName}
 

docs/modules/ROOT/pages/how-to-guides/managing-applications/proc-managing_applications.adoc

@@ -1,85 +1,88 @@
-= Managing applications in a secure development environment
+= Managing a security fix for your application
 
-This feature enables you to copy a selected application to a different workspace, where you can define a different set of collaborators. This is beneficial for working on secure fixes without broadcasting those changes to all team members in the original application.
+Sometimes, you need to address an **embargoed security issue** in your application. So as not to disclose aspects of the security vulnerability prematurely, you will want to prepare a fix in private or with a limited set of collaborators. This document guides you on how to make a private copy of your git repository and clone your application to a private workspace where you can prepare a fix and invite other collaborators only on a need-to-know basis, so that you can control who is aware of the issue while you develop the fix.
 
-Key capabilities of this feature include:
+Key steps include:
 
 * **Clone affected application:** Cloning affected applications into a private workspace, enabling developers to tackle security issues without exposing sensitive information.
+* **Prepare the fix:** Preparing the fix with source code in your private git mirror and builds in your private workspace.
+* **Release the fix:** Releasing the build from your private workspace and "upstreaming" your patch from your private git mirror back to your team's normal development repo.
 
-* **Re-create application with limited visibility:** Re-creating applications while minimizing the awareness of their existence, ensuring a secure environment for working on security fixes.
-
-
-== Cloning applications to a dedicated workspace
-You can clone applications to a dedicated workspace to address security vulnerabilities, test new features, and enhance the application without disrupting the production environment. 
+== Cloning applications to a private workspace
+Cloning an application involves replicating the application's code and configuration into a dedicated private workspace, ensuring that sensitive information remains isolated and protected.
 
 .**Prerequisite**
 
-* You have the maintainer role for the application you are working with.
-* You have access to App Studio.
-* You have downloaded RHTAP link:https://github.com/redhat-appstudio/rhtap-cli/releases[pre-built CLI].
-* You have a desired destination workspace created where you want to clone your application.
-
+* You have the xref:getting-started/roles_permissions/[maintainer role] or greater in the original workspace where the embargoed issue was identified.
+* You have downloaded the link:https://github.com/redhat-appstudio/rhtap-cli/releases[RHTAP CLI].
 
 .**Procedure**
 
-. Log in to the original workspace where the application was previously being developed using the link:https://redhat-appstudio.github.io/docs.appstudio.io/Documentation/main/getting-started/getting_started_in_cli/[`oc` CLI] tool.
-. To clone the application from one workspace to another, run the following command:
+. Create a link:https://docs.github.com/en/repositories/creating-and-managing-repositories/duplicating-a-repository[Private Mirror] of the corresponding repository for any components that will receive fixes related to embargoed information. This step is crucial to safeguard sensitive data and prevent unauthorized access.
+
++
+NOTE: Creating a private fork of the public link:https://docs.github.com/en/repositories/creating-and-managing-repositories/duplicating-a-repository[GitHub repository] is not possible.
+
+. xref:how-to-guides/managing-workspaces/proc-creating_a_team_workspace.adoc[Submit a request for a new workspace] dedicated to work on the embargoed issue. This workspace will serve as the private environment for cloning the affected application. Don't expose information about the vulnerability in your choice of a name for the workspace. If you had previously created a private workspace and is no longer in use for another embargoed process, you can re-use it as long as you re-restrict the User Access appropriately. Your personal workspace can also be used; make sure to review User Access.
+. Log in to the original workspace where the application was previously being developed using the `oc` CLI tool. (See xref:getting-start/getting_started_in_cli/[Getting started with CLI].) Append `/workspaces/<original-tenant-workspace>` to the AppStudio API url used in the `oc login` command to target a particular workspace other than your default user workspace.
+. To export records the application from the original workspace with details changed to refer to your new private workspace, run the following command:
 
 +
 [source,bash]
 ----
-./rhtap export application <name_of_your_application> --from <source_tenant_workspace> --to <target_tenant_workspace>
+./rhtap export application <name_of_your_application>  --from <original-tenant-workspace> --to <private-workspace> --as-prebuilt-images --skip <impacted component git url>
 ----
 
-NOTE: To show the command usage information, run: `rhtap export application --help`.
++
+NOTE: Ensure that you have excluded the impacted component from which you have created a private mirror in step 1.
 
-== Cloning applications to a secure workspace
-Clone an application to a secure workspace for addressing embargoed issues. Cloning an application involves replicating the application's code and configuration into a dedicated secure workspace, ensuring that sensitive information remains isolated and protected.
+. Confirm that the YAML file has been generated under the `./data` directory. This file contains the necessary information for importing the application into the new workspace.
+. Log in to the newly created private workspace using the `oc` CLI tool. Append `/workspaces/<private-workspace>` to the AppStudio API url used in the `oc login` command to target the new private workspace.
+. Apply the generated YAML file to the new private workspace by using the following command:
 
-.**Prerequisite**
++
+[source,bash]
+----
+oc apply -f ./data/<path-to-yaml>
+----
 
-* You are the maintainer of the application in the original workspace where the embargoed issue was identified.
+. Within the RHTAP UI, in the private workspace, import the private mirror as a new component in the application that you just created in step 7.
 
-* You have downloaded RHTAP link:https://github.com/redhat-appstudio/rhtap-cli/releases[pre-built CLI].
+At this point, you should have a clone of your application in the new private workspace, with all of its components mirrored from the original workspace, except the impacted component, which is now linked to the new private Git mirror repository.
 
-* You have created a corresponding private mirror repository for any components that contain embargoed information.
+== Preparing the security fix
 
-* You have a desired destination workspace created where you want to clone your application.
+.**Prerequisite**
 
+* You have cloned your application to a private workspace and have replaced the impacted component with a private mirror.
 
 .**Procedure**
 
-. Optional: Create a link:https://docs.github.com/en/repositories/creating-and-managing-repositories/duplicating-a-repository[Private Mirror] of the corresponding repository if any components within the application contain embargoed information. This step is crucial to safeguard sensitive data and prevent unauthorized access. 
-
-+
-NOTE: Creating a private fork of the public link:https://docs.github.com/en/repositories/creating-and-managing-repositories/duplicating-a-repository[GitHub repository] is not possible.
-
-. link:https://redhat-appstudio.github.io/docs.appstudio.io/Documentation/main/getting-started/get-started/[Submit a request] for a new workspace to work on the embargoed issue. This workspace will serve as a secure environment for cloning the affected application.
-
-. Log in to the original workspace where the application was previously being developed using the `oc` CLI tool.
+. Verify that pull requests to your private mirror create PipelineRuns in the private workspace and that integration tests run correctly.
+. Prepare the fix to your security issue as a pull request against your private mirror.
+. Invite reviewers from your security department or select members from your team to review the patch and confirm that it fixes the embargoed security issue, by link:https://redhat-appstudio.github.io/docs.appstudio.io/Documentation/main/getting-started/get-started/#adding-collaborators-to-your-workspace[granting them collaborator rights in your workspace].
+. When you are satisfied that the fix is ready, wait until the embargo disclosure time before releasing your fix.
 
-. To clone the application from the original workspace to the secure workspace, run the following command:
+== Releasing the security fix
 
-+
-[source,bash]
-----
-./rhtap export application <name_of_your_application>  --from <original-tenant-workspace> --to <secure-workspace> --as-prebuilt-images --skip <impacted component>
-----
-
-+
-NOTE: Ensure that you have excluded the impacted component from which you have created a private mirror in step 1.
-
-. Confirm that the YAML file has been generated under the link:https://github.com/redhat-appstudio/rhtap-cli/tree/main/data/20231003121403[`./rhtap/data` directory]. This file contains the necessary information for importing the application into the new workspace.
+.**Prerequisite**
 
-. Log in to the newly created secure workspace using the `oc` CLI tool.
+* You have prepared a fix in a private git mirror and private workspace.
+* You have reviewed the fix with representatives from your security department and select members of your team on a need-to-know basis.
+* The date for lifting the embargo has arrived.
 
-. Apply the generated YAML file to the new workspace by using the following command:
+.**Procedure**
 
-+
-[source,bash]
-----
-oc apply -f <path-to-yaml>
-----
+. In the private workspace, use the UI to identify the pullspec of the image bearing the fix, pinned to digest.
+. In your team's normal workspace (not the private workspace), use the CLI to identify a `Snapshot` that you want to use as a basis for your new release. A common choice is "the most recently released Snapshot", which you can find by picking through your history of Releases sorted by creation date to find the relevant Snapshot identifier.
+. Use `oc` to extract the Snapshot that you want to use as a basis for your new release to a local yaml file with `oc get snapshots <that snapshot id> -o yaml > snapshot.yaml`
+. Edit the extracted file to construct a new `Snapshot` that replaces the impacted components pullspec with the pullspec of the image bearing the fix, pinned to digest. You can discard all annotations and labels and you should give the Snapshot a new `name`.
+. Create that new Snapshot in the system with `oc apply -f snapshot.yaml`.
+. Review your integration test pipelines to confirm that the `Snapshot` is valid and can be released.
+. Create a `Release` resource referencing the specified `Snapshot`. Follow a similar procedure as outlined above. Export the existing `Release` as a starting point. Modify it to reference the new `Snapshot` and make any necessary adjustments.
+. In your team's normal workspace (not the private workspace), use the UI to watch the progress of the `Release`. When completed, your fix is live and available to your customers.
+. Extract the commit(s) from your private mirror and apply them back to the main Git repository used by your team for normal development.
 
-. Within the RHTAP UI, import the impacted component into the same application that the user has just imported. This ensures that the application is fully functional in the secure workspace.
+IMPORTANT: Ensure to apply the patch(es) from your private mirror to the Git repository that your team normally uses for managing development. Failure to do so results in security regressions in subsequent releases from your team.
 
+NOTE: It is possible that during the time that the issue is under embargo, other changes have been merged in the other components of your application. Those changes are built and integrated in your team's original workspace, but the components in the new private workspace are pinned to old versions of your components. They do not rebuild as new changes are merged. This is due to the `--as-prebuilt-images` flag you passed to the `rhtap export ...` command. In order to ensure that your in-progress change will work with the latest state of your application during development, you may want to periodically re-export the components from your original workspace and re-apply them to your private workspace in order to test that your in-progress change continues to work against the latest revision of the other components.

docs/modules/ROOT/pages/how-to-guides/managing-workspaces/proc-creating_a_team_workspace.adoc

@@ -0,0 +1,32 @@
+= Creating a team workspace
+
+When you first login to {ProductName}, you are granted a personal workspace dedicated to your username. But, sometimes, you want a workspace to organize work for your *team*, not just yourself.
+
+Because workspace creation is tied to SSO login identities in {ProductName}, in order to create a team workspace you need to create and login as an SSO identity that bears the same name as the team
+
+Key steps include:
+
+* **Create an SSO account for the team:** A prerequisite, giving {ProductName} the information it needs to create the team workspace.
+* **Login to {ProductName} and join the waitlist:** Triggering the creation of the workspace.
+* **Add team members to the shared workspace:** Allowing the team to get down to work.
+
+.**Prerequisite**
+
+* You are link:https://www.redhat.com/wapps/ugc/sso/logout[logged out] of the {ProductName} SSO provider.
+
+.**Procedure**
+
+. As in xref:getting-started/get-started.adoc[Getting started], visit https://console.redhat.com/preview/hac/application-pipeline[{ProductName}].
+. When prompted to login, select the link to register for a new account.
+. Follow the account creation steps.
+
+NOTE: For the login name, choose a name that reflects the identity of your team. This will become your team's workspace name.
+
+NOTE: For the email address, choose an address that you can access. Use a team mailing list, or a modified form of your personal email like `<your_username>+<team_name>@<domain>.com`.
+
+. Once the account is created, use it to log in to https://console.redhat.com/preview/hac/application-pipeline[{ProductName}].
+. As in xref:getting-started/get-started.adoc[Getting started], join the waitlist.
+. Once approved, visit the *User Access* section of the user interface to grant the xref:getting-started/roles_permissions.adoc[owner role] to your normal user identity.
+. link:https://www.redhat.com/wapps/ugc/sso/logout[Log out] and log back in as your normal user identity, and confirm you have access to the team workspace via the workspace switcher.
+
+NOTE: Once your normal user identity is granted admin, you should be able to add and manage other team members' access as your normal user identity by using the *User Access* section of the user interface.