4 years ago · 1d360ec352
--- a/server/sonar-docs/src/pages/extend/adding-coding-rules.md
+++ b/server/sonar-docs/src/pages/extend/adding-coding-rules.md
@@ -150,25 +150,9 @@ Now that you've fleshed out the description, you should have a fairly clear idea

 Sometimes the line between Bug and Code Smell is fuzzy. When in doubt, ask yourself: "Is code that breaks this rule doing what the programmer probably intended?" If the answer is "probably not" then it's a Bug. Everything else is a Code Smell. 

 [[collapse]]
 | ## Vulnerability or hotspot ?
 |
 | The main difference between a hotspot and a vulnerability is the **the need of a review** before deciding whether to apply a fix:
 | 
 | * With a hotspot, a missing protection is highlighted but the overall application's security may not be impacted.
 | * With a vulnerability, something that's wrong which impacts the application's security has been discovered and therefore needs a quick fix.
 | 
 | Another way of looking at hotspots may be [the concept of defense in depth](https://en.wikipedia.org/wiki/Defense_in_depth_(computing)) in which several redundant protection layers are placed in an application so that it becomes more resilient in the event of an attack.
 | 
 | An example is the [RSPEC-2092](https://jira.sonarsource.com/browse/RSPEC-2092) where the use of *cookie secure flag* is recommended to prevent cookies from being sent over non-HTTPS connections but the developer has to do a review because:
 | * HTTPS is the main protection against MITM attacks and so the secure flag is only an additional protection in case of some failures of network security. 
 | * The cookie may be designed to be sent everywhere (non-HTTPS websites included) because it's a tracking cookie or similar.
 |
 | With hotspots we try to give some freedom to users and to educate them on how to choose the most relevant/appropriate protections depending on the context (budget, threats, etc).
 |
 | The difficulty of exploiting a weakness should not be a criterion for specifying a hotspot or a vulnerability.
 |
 | Vulnerabilities and hotspots should not overlap but can be related to the same subject, for example, with the hotspot [RSPEC-2077](https://jira.sonarsource.com/browse/RSPEC-2077) formatted SQL queries are highlighted and we recommend the use of *prepare statements* as an additional protection to prevent SQL-injection vulnerabilities ([RSPEC-3649](https://jira.sonarsource.com/browse/RSPEC-3649)).
 The main differences between vulnerabilities and hotspots are explained on the [security-hotspots](/user-guide/security-hotspots/) page. During the specification of a rule, the following guidelines might also help:
 * The difficulty of exploiting a weakness should not be a criterion for specifying a hotspot or a vulnerability.
 * Vulnerabilities and hotspots should not overlap but can be related to the same subject. For example, with the hotspot [RSPEC-2077](https://jira.sonarsource.com/browse/RSPEC-2077), formatted SQL queries are highlighted and we recommend the use of *prepare statements* as an additional protection to prevent SQL-injection vulnerabilities ([RSPEC-3649](https://jira.sonarsource.com/browse/RSPEC-3649)).


 #### Default severities
--- a/server/sonar-docs/src/pages/user-guide/security-hotspots.md
+++ b/server/sonar-docs/src/pages/user-guide/security-hotspots.md
@@ -4,14 +4,28 @@ url: /user-guide/security-hotspots/
 ---

 ## What is a Security Hotspot?
 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. 
 A Security Hotspot highlights a security-sensitive piece of code that the developer needs to review. Upon review, you'll either find there is no threat or you need to apply a fix to secure the code. 

 Another way of looking at hotspots may be [the concept of defense in depth](https://en.wikipedia.org/wiki/Defense_in_depth_(computing)) in which several redundant protection layers are placed in an application so that it becomes more resilient in the event of an attack.

 ## Vulnerability or Hotspot?
 The main difference between a hotspot and a vulnerability is **the need of a review** before deciding whether to apply a fix:

 * With a Hotspot, a security-sensitive piece of code is highlighted, but the overall application security may not be impacted. It's up to the developer to review the code to determine whether or not a fix is needed to secure the code.
 * With a vulnerability, a problem that impacts the application's security has been discovered that needs to be fixed immediately.

 An example is the [RSPEC-2092](https://jira.sonarsource.com/browse/RSPEC-2092) where the use of *cookie secure flag* is recommended to prevent cookies from being sent over non-HTTPS connections but a review is needed because:
 * HTTPS is the main protection against MITM attacks and so the secure flag is only an additional protection in case of some failures of network security. 
 * The cookie may be designed to be sent everywhere (non-HTTPS websites included) because it's a tracking cookie or similar.

 With hotspots we try to give some freedom to users and to educate them on how to choose the most relevant/appropriate protections depending on the context (budget, threats, etc).

 ## 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:
 While the need to fix individual hotspots depends on the context, you should view Security Hotspots as an essential part of improving an application's robustness. The more fixed hotspots there are, the more secure your code is in the event of an attack. Reviewing Security Hotspots allows you to:

 * **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.
 * **Understand the risk** – Understanding when and why you need to apply a fix in order to reduce an information security risk (threats and impacts).
 * **Identify protections** – While reviewing Hotspots, you'll see how to avoid writing code that's at risk, determine which fixes are in place, and determine which fixes still need to be implemented to fix the highlighted code.
 * **Identify impacts** – With hotspots you'll learn how to apply fixes to secure your code based on the impact on overall application security. Recommended secure coding practices are included on the Hotspots page to assist you during your review.

 ## 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.
@@ -20,15 +34,13 @@ Security Hotspots have a dedicated lifecycle. To make status changes, the user n
 Through the lifecycle, a Security Hotspot takes one of the following statuses:

 * **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.
 * **Reviewed** – a developer has manually assessed the Security Hotspot and decided whether or not to apply a fix.

 ## Workflow  
 Follow this workflow to review Security Hotspots and fix any vulnerable code that you find.
 Follow this workflow to review Security Hotspots and apply any fixes needed to secure your code.

 ### 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. 
 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 code that needs to be secured and require your attention first. 

 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.

@@ -36,15 +48,15 @@ Review Priority is determined by the security category of each security rule. Ru
 When reviewing a Hotspot, you should:

 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 **Are you at risk** tab, read the **Ask Yourself Whether** section to determine if you need to apply a fix to secure the code highlighted in the Hotspot.
 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.

 After following these steps, set the Security Hotspot to one of the following:

 * **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.
 * **Fixed** – if you have applied a fix to secure the code highlighted by the Hotspot.
 * **Safe** – if the code is already secure and doesn't need to be fixed. (for example, other more relevant protections are already in place).
 * **Needs additional review** – if you need another user's review.

 ### Review History

 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.  
 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.  
--- a/server/sonar-docs/src/pages/user-guide/security-reports.md
+++ b/server/sonar-docs/src/pages/user-guide/security-reports.md
@@ -6,17 +6,16 @@ url: /user-guide/security-reports/
 *Security Reports are available as part of the [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html) and [above](https://www.sonarsource.com/plans-and-pricing/).*

 ## What do Security Reports show?
 Security Reports quickly give you the big picture on your application's security, with breakdowns of just where you stand in regard to each of the [OWASP Top 10](https://www.owasp.org/index.php/Top_10-2017_Top_10), and [SANS Top 25](https://www.sans.org/top25-software-errors) categories, and [CWE](http://cwe.mitre.org/)-specific details.
 Security Reports quickly give you the big picture on your application's security, with breakdowns of just where you stand in regard to each of the [OWASP Top 10](https://www.owasp.org/index.php/Top_10-2017_Top_10), and [SANS Top 25](https://www.sans.org/top25-software-errors) categories, and [CWE](https://cwe.mitre.org/)-specific details.

 The Security Reports are fed by the analyzers, which rely on the rules activated in your quality profiles to raise security issues. If there are no rules corresponding to a given OWASP category activated in your Quality Profile, you will get no issues linked to that specific category and the rating displayed will be A. That won't mean you are safe for that category, but that you need to activate more rules (assuming some exist).

 ## What's the difference between a Security Hotspot and a Vulnerability?
 Vulnerabilities are points in the code which are open to attack. Security Hotspots highlight security-sensitive pieces of code that need to be manually reviewed to ensure the sensitive piece of code is being used in the safest manner. Security hotspots also help educate developers on security issues. 

 For more details, see [Security Hotspots](/user-guide/security-hotspots/)

 ## Why are some Security Hotspot and Vulnerability rules very similar?
 They are overlapping on purpose. The Security Hotspot rule is supposed to include all matches of the Vulnerability rules, and cases where the taint analysis engine is not able to detect vulnerabilities. For example, switching from one language to another (XML, JNI, etc...) or using some third party libraries will prevent the taint analysis from finding vulnerabilities. A Vulnerability rule highlights security threats only when it has a high level of confidence, which means that it will always miss some of them. Whereas a Security Hotspot rule guides secure code reviews by showing code where those issues might lurk, even if it could not detect any vulnerability.
 For more details, see [Security Hotspots page](/user-guide/security-hotspots/) and to sum-up:
 * With a Hotspot, a security-sensitive piece of code is highlighted, but the overall application security may not be impacted. It's up to the developer to review the code to determine whether or not a fix is needed to secure the code.
 * With a vulnerability, a problem that impacts the application's security has been discovered that needs to be fixed immediately.
 

 ## Why don't I see any Vulnerabilities or Security Hotspots?
 You might not see any Vulnerabilities or Security Hotspots for the following reasons:
--- a/server/sonar-docs/src/pages/user-guide/security-rules.md
+++ b/server/sonar-docs/src/pages/user-guide/security-rules.md
@@ -2,58 +2,37 @@
 title: Security-related Rules
 url: /user-guide/security-rules/
 ---
 The {instance} Quality Model has three different types of rules: Reliability (bug), Vulnerability (security), and Maintainability (code smell) rules. But divided another way, there are only two types: security rules, and all the rest. The distinction between these two groups is not so much in what they catch but in where they come from and in the standards imposed on them.
 The {instance} Quality Model has four different types of rules: Reliability (bug), Maintainability (code smell), Security (vulnerability and hotspot) rules. There are a lot of expectations about security, so below we explain some key concepts and how the security rules differ from others.

 ## What to expect from security-related rules
 To be clear, the standard for most rules implemented in {instance} language plugins is very strict: no false positives. For normal rules, you should be able to be confident that whatever is reported to you as an issue really is an issue.
 As with other types of rules, we try to raise no false positives: you should be confident that anything reported to you as an issue is really an issue.

 But for security-related rules, the story is a little different. For instance, a lot of security guidelines talk about how "sensitive" data should be handled (e.g. not logged, not stored un-encrypted, &etc.). But since it's not really possible in a rule to tell which data is sensitive and which isn't, the choice becomes: maintain the no-false-positives standard and don't implement security-related rules, or implement security-related rules with a different standard.
 Under the hood SonarQube is based on different representations of the source code and technologies in order to be able to detect any kind of security issue:
 * **Security-injection rules**: there is a vulnerability here when the inputs handled by your application are controlled by a user (potentially an attacker) and not validated or sanitized, when this occurs, the flow from sources (user-controlled inputs) to sinks (sensitive functions) will be presented. To do this, SonarQube uses well-known taint analysis technology on source code which allows, for example, the detection of:
  * [CWE-89](https://cwe.mitre.org/data/definitions/89.html): SQL Injection
  * [CWE-79](https://cwe.mitre.org/data/definitions/79.html): Cross-site Scripting
  * [CWE-94](https://cwe.mitre.org/data/definitions/94.html): Code Injection
 * **Security-configuration rules**: here there is a security issue because the wrong parameter (eg: invalid cryptographic algorithm or TLS version) when calling a sensitive function has been set or when a check (eg: check_permissions() kind of function) was not done or not in the correct order, this problem is likely to appear often when the program is executed (no injected/complex attacks are required unlike in the previous category):
  * [CWE-1004](https://cwe.mitre.org/data/definitions/1004.html): Sensitive Cookie Without 'HttpOnly' Flag
  * [CWE-297](https://cwe.mitre.org/data/definitions/297.html): Improper Validation of Certificate with Host Mismatch
  * [CWE-327](https://cwe.mitre.org/data/definitions/327.html): Use of a Broken or Risky Cryptographic Algorithm

 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.
 These security issues are then divided into two categories: vulnerabilities and hotspots (see the main differences on the [Security Hotspots](/user-guide/security-hotspots/) page). Security Hotspots have been introduced for security protections that have no direct impact on the overall application's security. Most injection rules are vulnerabilities, for example, if a SQL injection is found, it is certain that a fix (input validation) is required, so this is a vulnerability. On the contrary, the *httpOnly* flag when creating a cookie is an additional protection desired (to reduce the impact when XSS vulnerabilities appear) but not always possible to implement or relevant depending on the context of the application, so it's a hotspot. 

 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.
 With Hotspots, we want to help developers understand information security risks, threats, impacts, root causes of security issues, and the choice of relevant software protections. In short, we really want to educate developers and help them develop secure, ethical, and privacy-friendly applications.

 ## 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. 
 ## Which security-standards are covered?
 Our security rules are classified according to well-established security-standards such as:
 * [CWE](https://cwe.mitre.org/): SonarQube is a CWE compatible product [since 2015](https://cwe.mitre.org/compatible/questionnaires/33.html).
 * [SANS Top 25](https://www.sans.org/top25-software-errors/)
 * [OWASP Top 10 ](https://www.owasp.org/index.php/Top_10-2017_Top_10)

 ### CWE
 CWE stands for Common Weakness Enumeration. According to the [CWE FAQ](http://cwe.mitre.org/about/faq.html#A.1):
 The standards to which a rule relates will be listed in the **See** section at the bottom of the rule description. More generally, you can search for a rule on [rules.sonarsource.com](https://rules.sonarsource.com/):
 * [Java-vulnerability-issue-type](https://rules.sonarsource.com/java/type/Vulnerability): all vulnerability rules for Java language.
 * [Java-hotspots-issue-type](https://rules.sonarsource.com/java/type/Security%20Hotspot): all security-hotspot rules for Java language.
 * [Java-tag-injection](https://rules.sonarsource.com/java/tag/injection): all security-injection rules for Java language.

 > Common Weakness Enumeration (CWE™) is a formal list or dictionary of common software weaknesses that can occur in software's architecture, design, code or implementation that can lead to exploitable security vulnerabilities. CWE was created to serve as a common language for describing software security weaknesses; serve as a standard measuring stick for software security tools targeting these weaknesses; and to provide a common baseline standard for weakness identification, mitigation, and prevention efforts.
 ## How to propose new security-rules?
 Security is a lively world where new types of attacks and vulnerabilities appear very often, so we welcome any suggestions for new security-rules. You can read the [adding coding rules](/extend/adding-coding-rules/) page to see how to develop a new rule or propose a new one [on our community forum](https://community.sonarsource.com/c/suggestions/rules/13).

 The CWE is a hierarchy of weakness descriptions. The lowest level in the hierarchy is a "Weakness Base", which describes a granular weakness. Above Weakness Bases, are Weakness Classes and Categories. In general, rules are linked to Weakness Bases or Classes. 

 Tools which meet certain requirements can be certified as [CWE Compatible](http://cwe.mitre.org/compatible/). Those requirements are:

 * You must be able to search for CWE-related rules using a CWE identifier. To do so in the {instance} platform, simply drop the CWE identifier (e.g. CWE-595) in the search text input on the rules page and run the search.
 * Rules must be accurately linked to their related CWE items. To see the CWE mapping for a {instance} rule, consult the rule's See section at the bottom of the rule description.
 * You must be able to identify the relevant CWE from an Issue. To do so in the {instance} platform, consult the related rule.
 * The product documentation must include a description of CWE and CWE Compatibility.
 * The version of CWE supported must be listed. The {instance} language plugins support version 2.8.
 * In addition to searching rules by CWE id's, you can also search by the "cwe" rule tag.

 To see which CWE items are covered for a language, consult the links below.

 * [C](https://rules.sonarsource.com/c/tag/cwe)/[C++](https://rules.sonarsource.com/cpp/tag/cwe)
 * [Java](https://rules.sonarsource.com/java/tag/cwe) 
 * [Objective-C](https://rules.sonarsource.com/objective-c/tag/cwe)
 

 ### SANS Top 25

 The [SANS Top 25](http://www.sans.org/top25-software-errors/) list is a collection of the 25-most dangerous errors listed in the CWE, as compiled by the [SANS organization](http://www.sans.org/). The current SANS list is divided into three categories: Insecure Interaction Between Components, Risky Resource Management, and Porous Defenses.

 The tags used for SANS correspond to its categories: sans-top25-insecure, sans-top25-risky, sans-top25-porous.

 To find rules relating to SANS Top 25, you can perform a text search for the category, or the relevant CWE item, or perform a rule tag search.

 ### OWASP Top 10
 OWASP stands for Open Web Application Security Project. According to its site, it is:

 > A [501(c)(3)](http://www.irs.gov/Charities-&-Non-Profits/Charitable-Organizations/Exemption-Requirements-Section-501(c)(3)-Organizations) worldwide not-for-profit charitable organization focused on improving the security of software. Our mission is to make software security [visible](https://www.owasp.org/index.php/Category:OWASP_Video), so that [individuals and organizations](https://www.owasp.org/index.php/Industry:Citations) worldwide can make informed decisions about true software security risks.

 The [OWASP Top 10](https://www.owasp.org/index.php/Top_10-2017_Top_10) is a list of broad categories of weaknesses, each of which can map to many individual rules.

 The tags used for OWASP correspond to the weakness categories: owasp-a1, owasp-a2, owasp-a3, owasp-a4, owasp-a5, owasp-a6, owasp-a7, owasp-a8, owasp-a9, owasp-a10.

 To find rules relating to OWASP Top 10, you can perform a text search for the category, or perform a rule tag search.
 Regarding the security-injection rules mentioned above, it's possible to [extend the taint analysis configuration](/analysis/security_configuration/) to allow the SonarQube engine to use new sources, sanitizers, validators and sinks of the homemade-frameworks that you use. Security Engine Custom Configuration is available as part of the Enterprise Edition and above.