SONAR-12027 update docs for Hotspot Actions

server/sonar-docs/src/pages/instance-administration/security.md

@@ -102,7 +102,7 @@ Project permissions are available from the project-level Administration menu: **
 Project visibility may be toggled between public or private. Making a project private hides its source code and measures from the `Anyone` group. For both public and private projects, four different permissions can be set:
 
 * **Administer Issues**: Change the type and severity of issues, resolve issues as being "Won't Fix" or "False Positive" (users also need "Browse" permission).
-* **Administer Security Hotspots**: "Detect" (convert) a Vulnerability from a "Security Hotspot", reject, clear, accept or reopen a "Security Hotspot" (users also need "Browse" permission).
+* **Administer Security Hotspots**: With Security Hotspots, you can **Open as a Vulnerability**, **Set as In Review**, **Resolve as Reviewed**. With a Security Hotspot that's been opened as a Vulnerabilty, you can **Reset as To Review** or **Resolve as Reviewed**.
 * **Administer**: Access project settings and perform administration tasks (users also need "Browse" permission).
 * **Execute Analysis**: Execute analyses (project, view, report, developer), and to get all settings required to perform the analysis, even the secured ones like the scm account password, the jira account password, and so on.
 

server/sonar-docs/src/pages/user-guide/security-hotspots.md

@@ -5,49 +5,54 @@ url: /user-guide/security-hotspots/
 
 ## What is a Security Hotspot?
 
-Unlike Vulnerabilities, Security Hotspots aren't necessarily issues that are open to attack. However, Security Hotspots highlight security-sensitive pieces of code that someone focused on security needs to review. Upon review, that security-focused developer or reviewer might find that a Security Hotspot is in fact a Vulnerability that needs to be fixed. 
+Unlike Vulnerabilities, Security Hotspots aren't necessarily issues that are open to attack. Instead, Security Hotspots highlight security-sensitive pieces of code that need to be manually reviewed. Upon review, you might be find a Vulnerability at a Security Hotspot location that needs to be fixed or that there is no threat. 
 
 ## Why are Security Hotspots Important?
 
-Security Hotspots help focus the efforts of developers or reviewers who are manually checking security-sensitive code. Reviewing Security Hotspots allows you to:
+Security Hotspots help focus the efforts of developers who are manually checking security-sensitive code. Reviewing Security Hotspots allows you to:
 
-* **Fix security issues** – Reviewing Security Hotspots gives you the opportunity to detect true vulnerabilities and ensure issues are fixed before merging pull requests or releasing your branch.
-* **Learn about security** – {instance} explains why your code was identified as a Security Hotspot and the link between your Hotspots and well-known attacks or weaknesses such as SQL Injection, Weak Cryptography, or Authentication. Knowing this makes developers aware of when they're working on security-sensitive code and helps them avoid creating Vulnerabilities.
+* **Fix security issues** – Reviewing Security Hotspots gives you the opportunity to detect vulnerabilities and ensure issues are fixed before merging pull requests or releasing your branch.
+* **Learn about security** – {instance} explains why your code was identified as a Security Hotspot and the link between your Security Hotspots and well-known attacks or weaknesses such as SQL Injection, Weak Cryptography, or Authentication. Knowing this makes you aware of when you're working on security-sensitive code and helps you avoid creating Vulnerabilities.
 
 ## Security Hotspot Lifecycle
-Security Hotspots have a dedicated lifecycle and must be reviewed by a user with the "Administer Security Hotspots" permission. 
+Security Hotspots have a dedicated lifecycle and must be reviewed by someone with the "Administer Security Hotspots" permission. 
 
 ### Status
 
 Through the lifecycle, a Security Hotspot takes one of the following statuses:
 
-* **Open** - set by {instance} on new Security Hotspots
-* **Resolved** (Won't Fix) - set automatically by {instance} when a reviewer accepts the fix done by a developer on a Manual Vulnerability or when a reviewer clears an open Hotspot or manual Vulnerability.
-* **To Review** - set automatically when a developer requests a review on a manual Vulnerability.
-* **Reopened** - set when a developer dismisses an open manual Vulnerability or when a reviewer manually reopens a resolved Security Hotspot in order to run a new audit on it.
+* **To Review** – the default status of new Security Hotspots set by {instance}. A Security Hotspot has been reported and needs to be checked.
+* **In Review** – the Security Hotspot is being checked to make sure there isn't a vulnerability in the code.
+* **Reviewed** – the Security Hotspot has been checked and no security issue was found.
 
 A Security Hotspot is only closed if the code containing it is deleted. A Security Hotspot's status will be "Removed" if the rule in the project's Quality Profile identifying it is removed.
 
 ### Actions
 
-Security Hotspots allow the following actions:
+You can perform the following actions on Security Hotspots:
 
-* **Detect** - Confirms a Security Hotspot as a true issue and manually opens a Vulnerability. Requires "Administer Security Hotspots" permission on the project.
-* **Clear** - Marks a Security Hotspot or manually opened Vulnerability as being without issue and shouldn't be fixed. Requires "Administer Security Hotspots" permission on the project.
-* **Request Review** - Request that a reviewer analyzes changes made to fix a manually opened Vulnerability.
-* **Reject** - After review, reject the fix for a manually opened Vulnerability and return it to an open issue. Requires "Administer Security Hotspots" permission on the project.
+* **Resolve as Reviewed** - There is no vulnerability in the code.
+* **Set as In Review** - A review is in progress to check for a vulnerability
+* **Reset as To Review** - The Security Hotspot needs to be analyzed again.
+* **Open as Vulnerability** - There's a Vulnerability in the code that must be fixed.
 
 ### Workflow
 
-If a reviewer with "Administer Security Hotspots" permission determines a Hotspot is actually a Vulnerability, the reviewer changes the status from its current state (probably **Open**) to **Detect**. This converts the Security Hotspot to a Vulnerability, and the developer who last touched the line will receive "new issue" notifications (if she's signed up to get them).
+When {instance} detects a Security Hotspot, it is set as **To Review**. From here, you can perform the following actions on the Security Hotspot:
+* **Open as a Vulnerablility** if you find a Vulnerability in the code at the Security Hotspot location that must be fixed.
+* **Resolve as Reviewed** if you don't find a Vulnerability in the code at the Security Hotspot location.
+* **Set as In Review** if you want to flag the Security Hotspot to show that you are checking it or about to check it for Vulnerabilities. This is an optional step in the workflow. 
 
-Once a Vulnerability is *Detect*ed at a Security Hotspot location, the following occurs:
+If you set a Security Hotspot to **In Review**, it can either be marked:
+* **Open as Vulnerability** if you find a Vulnerability in the code that must be fixed.
+* **Resolve as Reviewed** if you don't find a Vulnerability in the code.
+
+When you determine there is a Vulnerability at a Security Hotspot location and select **Open as a Vulnerability**, its status changes from **To Review** or **In Review** to **Open**. This converts the Security Hotspot to a Vulnerability, and the developer who last touched the line of code will receive "new issue" notifications (if she's signed up to get them).
+
+Once a Vulnerability is **Open**ed at a Security Hotspot location, the following occurs:
 
 1. The Security Hotspot is assigned to the appropriate developer, and the developer makes a fix.
-2. The developer must then **Request Review** *via the UI*. The request moves the Vulnerability back to Security Hotspot. 
-3. The reviewer either **Accepts** or **Rejects** the fix. 
-	* Accepting the fix marks the Security Hotspot "Won't Fix." 
-	* Rejecting the fix turns the Security Hotspot back into a Vulnerability and puts it back in the developer's queue.
+2. The developer then marks the Vulnerability **Resolve as Reviewed** *via the UI* which moves the Vulnerability back to being a Security Hotspot. 
+3. The Security Hotspot is then marked as **Reviewed** and it's status is **Fixed**. 
 
-### Marking a Hotspot "Won't Fix"
-The `Won't Fix` designation indicates that a Hotspot has been reviewed and there is no way, as of now, to exploit this piece of code to create an attack.
+A reviewed Security Hotspot can be reopened as a Vulnerability at any point if it's determined to be a true issue.