From 93c668ea847e32509264668f103b8b270d0ca9c3 Mon Sep 17 00:00:00 2001 From: michaelbirnstiehl Date: Tue, 17 Dec 2019 17:41:32 -0600 Subject: [PATCH] Sonar-12854 Update documentation for new Security Hotspots page --- .../pages/instance-administration/security.md | 4 +- .../src/pages/user-guide/concepts.md | 2 +- .../sonar-docs/src/pages/user-guide/issues.md | 3 - .../pages/user-guide/metric-definitions.md | 11 ++-- .../sonar-docs/src/pages/user-guide/rules.md | 2 +- .../src/pages/user-guide/security-hotspots.md | 60 ++++++++----------- .../src/pages/user-guide/security-rules.md | 2 +- 7 files changed, 37 insertions(+), 47 deletions(-) diff --git a/server/sonar-docs/src/pages/instance-administration/security.md b/server/sonar-docs/src/pages/instance-administration/security.md index ed04933d0d0..94cd85ba131 100644 --- a/server/sonar-docs/src/pages/instance-administration/security.md +++ b/server/sonar-docs/src/pages/instance-administration/security.md @@ -105,12 +105,12 @@ 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**: 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 Security Hotspots**: Change the status of a Security Hotspot. * **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. Private projects have two additional permissions: -* **Browse**: Access a project, browse its measures, issues and perform some issue edits (confirm/resolve/reopen, assignment, comment). +* **Browse**: Access a project; browse its measures, issues, and Security Hotspots; perform some issue edits (confirm/resolve/reopen, assignment, comment); comment on or change the user assigned to a Security Hotspot. * **See Source Code**: View the project's source code. Note that permissions _are not_ cumulative. For instance, if you want to be able to administer the project, you also have to be granted the Browse permission to be able to access the project (which is the default for Public project). diff --git a/server/sonar-docs/src/pages/user-guide/concepts.md b/server/sonar-docs/src/pages/user-guide/concepts.md index 67d30094e21..0aa26242393 100644 --- a/server/sonar-docs/src/pages/user-guide/concepts.md +++ b/server/sonar-docs/src/pages/user-guide/concepts.md @@ -30,6 +30,6 @@ See also the [SonarQube Platform Overview](/architecture/architecture-integratio | Rule | A coding standard or practice which should be followed. Not complying with coding rules leads to **Bugs**, **Vulnerabilities**, **Security Hotspots**, and **Code Smells**. Rules can check quality on code files or unit tests. | | Remediation Cost | The estimated time required to fix Vulnerability and Reliability Issues. | | Snapshot | A set of **measures** and **issues** on a given project at a given time. A snapshot is generated for each analysis. | -| Security Hotspot | A security-related issue highlighting a piece of code that uses a security-sensitive API (E.G. use of a weak algorithm, connection to a database, ...). Security Hotspots must be manually reviewed to determine if the APIs are being used in ways that introduce Vulnerabilities. | +| Security Hotspot | Security-sensitive pieces of code that need to be manually reviewed. Upon review, you'll either find that there is no threat or that there is vulnerable code that needs to be fixed. | | Technical Debt | The estimated time required to fix all Maintainability Issues / code smells | | Vulnerability | A security-related issue which represents a backdoor for attackers. See also [Security-related rules](/user-guide/security-rules/). | diff --git a/server/sonar-docs/src/pages/user-guide/issues.md b/server/sonar-docs/src/pages/user-guide/issues.md index 08c9cb6f6a5..b268ddd3ec3 100644 --- a/server/sonar-docs/src/pages/user-guide/issues.md +++ b/server/sonar-docs/src/pages/user-guide/issues.md @@ -94,9 +94,6 @@ As a consequence, it is possible that backdating will keep newly raised issues o ### For Bug, Vulnerability and Code Smell New issues are automatically assigned during analysis to the last committer on the issue line if the committer can be correlated to a {instance} user. Note that currently, issues on any level above a file, e.g. directory / project, cannot be automatically assigned. -### For Security Hotspot -Issues are automatically assigned only when the Security Hotspot is transformed into a Vulnerability through the "Detect" action. - ### User Correlation Login and email correlations are made automatically. I.e. if the user commits with her email address and that email address is part of her {instance} profile, then new issues raised on lines where she was the last committer will be automatically assigned to her. diff --git a/server/sonar-docs/src/pages/user-guide/metric-definitions.md b/server/sonar-docs/src/pages/user-guide/metric-definitions.md index 812a7c1b22b..3cb9d02072a 100644 --- a/server/sonar-docs/src/pages/user-guide/metric-definitions.md +++ b/server/sonar-docs/src/pages/user-guide/metric-definitions.md @@ -174,12 +174,13 @@ Number of Security Hotspots Number of new Security Hotspots **Security Review Rating** (`security_review_rating`) -The ratio of the number of Security Hotspots that are in "To Review" or "In Review" status per 1K lines of code. -A = 0–3 "To Review" and "In Review" Security Hotspots per 1K lines of code -B = >3–10 -C = >10–15 -D = >15–25 +The ratio of the number of Security Hotspots that are in "To Review" status per 1K lines of code. + +A = 0–3 "To Review" and "In Review" Security Hotspots per 1K lines of code +B = >3–10 +C = >10–15 +D = >15–25 E = >25 --- diff --git a/server/sonar-docs/src/pages/user-guide/rules.md b/server/sonar-docs/src/pages/user-guide/rules.md index 278bcc1074f..4e200ab644a 100644 --- a/server/sonar-docs/src/pages/user-guide/rules.md +++ b/server/sonar-docs/src/pages/user-guide/rules.md @@ -131,4 +131,4 @@ Impact: **Could the exploitation of the Worst Thing result in significant damage Likelihood: **What is the probability that a hacker will be able to exploit the Worst Thing?** ### Security Hotspots -Security Hotspots are not assigned severities as it is unknown whether there is truly an issue until review by a Security Auditor. When an auditor converts a Security Hotspot into a Vulnerability, severity is assigned based on the identified Vulnerability (see above). +Security Hotspots are not assigned severities as it is unknown whether there is truly an underlying vulnerability until they are reviewed. diff --git a/server/sonar-docs/src/pages/user-guide/security-hotspots.md b/server/sonar-docs/src/pages/user-guide/security-hotspots.md index 29bfb487368..380a54476c2 100644 --- a/server/sonar-docs/src/pages/user-guide/security-hotspots.md +++ b/server/sonar-docs/src/pages/user-guide/security-hotspots.md @@ -4,55 +4,47 @@ url: /user-guide/security-hotspots/ --- ## What is a Security Hotspot? - -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'll either find a Vulnerability that needs to be fixed or that there is no threat. +Security Hotspots highlight security-sensitive pieces of code that need to be manually reviewed. Upon review, you'll either find that there is no threat or that there is vulnerable code that needs to be fixed. ## Why are Security Hotspots Important? +Security Hotspots help you focus your efforts as you 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 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. This helps you to know when you're working on security-sensitive code and to avoid creating Vulnerabilities. +* **Detect security issues** – You can detect vulnerable code and ensure issues are fixed before merging pull requests or releasing your branch. +* **Learn about security** – You can see 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. This helps you to know when you're working on security-sensitive code and to avoid creating vulnerable code. +* **Learn how to fix vulnerable code** – From the Security Hotspots page, you can see why the Hotspot was raised, determine if you've used code in a security-sensitive way, and learn how to fix it if you have. -## Security Hotspot Lifecycle -Security Hotspots have a dedicated lifecycle and must be reviewed by someone with the "Administer Security Hotspots" permission. - -### Status +## Lifecycle +Security Hotspots have a dedicated lifecycle. To make status changes, the user needs the **Administer Security Hotspots** permission. This permission is enabled by default. Users with the **Browse** permission can comment on or change the user assigned to a Security Hotspot. +### Statuses Through the lifecycle, a Security Hotspot takes one of the following statuses: -* **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. +* **To Review** – the default status of new Security Hotspots set by SonarQube. A Security Hotspot has been reported and needs to be checked. +* **Reviewed** – a developer has manually assessed the Security Hotspot and either considered the code not vulnerable or any vulnerability issue that was found has been fixed. A Security Hotspot is only closed if the code containing it is deleted or the rule is deactivated. -### Actions - -You can perform the following actions on Security Hotspots: +## Workflow +Follow this workflow to review Security Hotspots and fix any vulnerable code that you find. -* **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. +### Review Priority +When SonarQube detects a Security Hotspot, it's added to the list of Security Hotspots according to its review priority from High to Low. Hotspots with a High Review Priority are the most likely to contain vulnerable code and need your attention first. -### Workflow +Review Priority is determined by the security category of each security rule. Rules in categories that are ranked high on the OWASP Top 10 and CWE Top 25 standards are considered to have a High Review Priority. Rules in categories that aren't ranked high or aren't mentioned on the OWASP Top 10 or CWE Top 25 standards are rated as Medium or Low. -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. +### Reviewing Hotspots +When reviewing a Hotspot, you should: -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. +1. Review the **What's the risk** tab to understand why the Security Hotspot was raised. +1. From the **Are you vulnerable** tab, read the **Ask Yourself Whether** section to determine if the code is used in a security-sensitive way. +1. From the **How can you fix it** tab, follow the **Recommended Secure Coding Practices** to fix your code if you've determined it's unsafe. -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). +After following these steps, set the Security Hotspot to one of the following: -Once a Vulnerability is **Open**ed at a Security Hotspot location, the following occurs: +* **Fixed** – if you found vulnerable code and have modified it to follow secure coding practices. +* **Safe** – if the code already follows secure coding practices and doesn't need to be modified. +* **Needs additional review** – if you need another user's review to make sure the Security Hotspot doesn't contain vulnerable code. -1. The Security Hotspot is assigned to the appropriate developer, and the developer makes a fix. -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**. +### Review History -A reviewed Security Hotspot can be reopened as a Vulnerability at any point if it's determined to be a true issue. +The **Review history** tab shows the history of the Security Hotspot including the status it's been assigned and any comments the reviewer had regarding the Hotspot. \ No newline at end of file diff --git a/server/sonar-docs/src/pages/user-guide/security-rules.md b/server/sonar-docs/src/pages/user-guide/security-rules.md index cd1a80152c9..198644192bf 100644 --- a/server/sonar-docs/src/pages/user-guide/security-rules.md +++ b/server/sonar-docs/src/pages/user-guide/security-rules.md @@ -11,7 +11,7 @@ But for security-related rules, the story is a little different. For instance, a That's why security-related rules cast a wider net than you may be used to seeing. The idea is that the rule will flag anything suspicious, and leave it to the human security auditor to cull the false positives and sent the real issues for remediation. -Security Hotspots are a special type of issue that identify sensitive areas of code that should be reviewed by a Security Auditor to determine if they are truly Vulnerabilities. See Security Audits and Reports for detail on Security Hotspots and the audit process. +Security Hotspots are a special type of issue that identify sensitive areas of code that need to be reviewed to determine if they contain vulnerable code. See [Security Hotspots](/user-guide/security-hotspots/) for more information. ## Where security-related rules come from The vast majority of security-related rules originate from established standards: [CWE](http://cwe.mitre.org/), [SANS Top 25](http://www.sans.org/top25-software-errors/), and [OWASP Top 10](https://www.owasp.org/index.php/Top_10-2017_Top_10). To find rules that relate to any of these standards, you can search rules either by tag or by text. The standards that a rule relates to will be listed in the **See** section at the bottom of the rule description. -- 2.39.5