Skip to content

Standards and best practices for SonarQube usage

Overview

SonarQube is an open source software to perform code scans, identify code vulnerabilities, bugs and detect code smells and log them into a centralized database. SonarQube is a continuous code quality integration tool which also provides dashboards and other tools to be able to manage the code efficiently.

  1. With respect to Project/Team, SonarQube provides a standardized policy for continuous code improvement.

  2. It provides visibility on code quality levels across multiple projects with support for large variety of mainstream languages.

  3. Provides automated code quality improvements over the human driven approach followed in numerous projects.

  4. Maintains uniform code quality standards across multiple projects.

Best practices for SonarQube Setup

1. Project Keys and names

Project key is an unique identifier for the project. Example: if project A and next project B is analyzed with the same ID, then data of B will overwrite result stored for project A.

  • Allowed characters are : letters, digits, dash, underscore, period or colon ( with at least one non-digit).
  • Recommendation is to make the project key a combination of the azure project and the repo name separated by an underbar. _.
  • Example, if the repo exists in the mLife-Platform azure project and the repo name is MyRepo, the project key would be mLife-Platform_MyRepo

Project name is a display name that will be displayed on the web interface.

  • Default value is same as project key
  • Recommendation is to make the change the Project name equal to the Azure Repo name.
  • Example, if the repo exists in the mLife-Platform azure project and the repo name is MyRepo, the project name is just MyRepo

2. Apply Quality Gates.

Quality Gate is a set of conditions a project must meet before it can qualify for a release. Quality gate should be customized to meet the requirements relevant to a project. Standardize quality gates across Enterprise applications and teams.

Sonar Way Quality Gate

The "Sonar way" Quality Gate is provided by SonarSource and is activated by default. Every project not specifically associated to a quality gate will be associated to this one by default. Sonar Way focuses on new code, thus implement Clean As You Code concept.

Sonar Way is the recommended quality gate

Best practices on quality gates

  1. Code quality standards should be homogenized across all teams within an organization. Define high-level expectation of code quality within an organization. Identify key metrics that are applicable to all the projects based on project specifications. Standardize policy for code improvement, which can be inherited by all the teams under it.
  2. Technological implementation differs from one application to another. Metrics which are relevant for a project may not be relevant for another. Users can choose to add or customize thresholds specific to a project in this case.
  3. Deployments are available at the develop/main branch. Quality gates are enforced at these branches to ensure quality deployment. Lower branches created during development can include SonarQube scanner tasks in their pipeline and to view Sonar results. This will not result in failed deployment.
  4. Ensure metrics meet the project's quality management goals.
  5. Quality gates should be adjusted to provide clear feedback to developers looking at their project page.
  6. Quality gates conditions must use differential values, rather than absolute values. For e.g. lines of code greater than 1000 is inappropriate.
  7. Avoid single optimization targets -- High thresholds like 95% code coverage for the unit test cases\" or \"Code duplication smaller than 2%\" can induce junk code by developers to fulfil targets. Ensure more realistic thresholds.

Agreed upon team-wide quality gate threshold conditions If the code meets any of the listed quality thresholds, it will fail the quality gate.

1.   Method Cognitive Complexity is greater than 20
2.   Maintainability Rating on new Code less than B grade by SonarQube
3.   Coverage on New Code is less than 70% 
4.   Reliability Rating on New Code less than A grade by SonarQube
5.   Security Rating on New code less than A grade by SonarQube

Suggested team-wide quality gate threshold conditions (shared by Paul Leska) If the code meets any of the listed quality thresholds, it will fail the quality gate.

1.   Method Cognitive Complexity is greater than 20
2.   Comments are less than 25%
3.   Coverage on New Code is less than 70% 
4.   Method Cyclomatic complexity is greater than 25
5.   Maintainability Rating on new Code less than B grade by SonarQube
6.   New Code Smells is greater than 25
7.   New critical issues are greater than 5
8.   New major issues are greater than 10
9.   New vulnerabilities are greater than 5
10.  Reliability Rating on New Code less than A grade by SonarQube
11.  Security Rating on New code less than A grade by SonarQube
12.  Skipped unit tests is greater than 0
13.  Technical Debt Ratio is greater than 25%
14.  Unit Test Success is less than 100%
15.  Vulnerabilities is greater than 25

3. Apply Quality Profiles.

Quality profiles define sets of rules that when violated should raise issues.

Best practices on quality profiles

  1. Setup and Standardize Quality Profile-- SonarQube has default sets of rules for different languages that are available (Sonar way). It is recommended to customize the tool by specifying own set of rules, per coding standards and conventions of the project through a custom profile. As a best practice, consider creating a new profile (you can populate it by copying the contents of Sonar way) and use it instead. Copy default profile and fine-tune the contents.
  2. It is recommended to have as few Quality Profiles as possible to ensure consistency across projects, you can define as many Quality Profiles as necessary to fit specific needs.
  3. For an organization, set up a base profile, then create a child profile. Once it\'s created, you can change child profile to inherit from the root base profile and add missing rules. It is recommended to have a core set of rules and create child profiles so that the rules are specific to the in-use technology.
  4. Default Quality Profiles are not editable, so you won\'t be able to customize the Sonar way to your needs. The Sonar way becomes a baseline against which you can track your own Quality Profiles.
  5. Check for Deprecated Rules section of the rules interface. This section is your first warning that a profile contains deprecated rules and gives the total number of instances of deprecated rules that are currently active in profiles, and a breakdown of deprecated count per profile.
  6. If you are not using built-in profile like Sonar way, then new rules added as part of SonarQube update won't be available in the customized profiles. To check on the new rules added, compare default profile with the profile currently being used by using 'Available Since' search facet or 'latest new rules section' on the profile interface.

4. Apply Rules

SonarQube executes rules on the source code to generate issues. Admin users have an option to add/remove tags and extend the description of an existing rule by clicking on a it. Additionally, custom rules can be added from the available templates, by selecting 'show templates only' option and selecting a template from the custom rules option. Only custom rules can be edited or deleted.

Best practices on coding rules-

  1. A standard set of rules should be defined at the organization level. Teams can inherit these rules and individually choose to add own rules that are relevant to them.
  2. Avoid examples that make references to real companies or organizations. It should be replaced with neutral names instead. a. e.g. \$fp = file_get_contents "http//www.real-company.com";
  3. When a reference is made to a standards specification, add any related tags such as security, bug, etc. Also, add the relevant standard-related tag/label.
  4. Rule type should be appropriately classified into bug, code smell, vulnerability, and hotspot.
  5. Rules can have 0-n tags, although most rules should have at least one.
  6. Issue description should be precise and on the line of code that needs correction. Avoid using a narrative and additional messages.

  7. For Bug, Vulnerability, and Code Smell rules

    a. Rule descriptions should contain the following sections - Rationale (unlabeled) - explaining why this rule makes sense - Noncompliant Code Example - providing some examples of issues - Compliant Solution - demonstrating how to fix the previous issues - Exceptions (optional) - listing and explaining some specific use cases where no issues are logged even though some might be expected - See (optional) - listing references and/or links to external standards like MISRA, SEI, CERT, etc. - Deprecated (optional): listing replacement rules with links

    b. Titles should be concise and if possible, titles should be written in plural form

    c. Any piece of code in the rule title should be double-quoted.

    d. For Noncompliant Title: - File should not have too many lines of code - Don\'t use \"System.(out/err)\" - Parameters in an overriding virtual function should either use the same default arguments as the function they override, or not specify any default arguments

    e. Compliant Solutions: - Files should not have too many lines of code - \"System.(out/err)\" should not be used to log messages - Overriding virtual functions should not change parameter defaults f.\ Code samples for COBOL should be in upper case.

    g. Issue messages should contain the remediation message for bug and quality rules. For potential-bug rules, it should make it explicit that a manual review is required. 

    h. Any piece of code in the rule message should be double-quoted (and not single-quoted)

    i. An issue message should always end with a period (\'.\') since it is an actual sentence, unless it ends with a regular expression, in which case the regular expression should be preceded by a colon and should end the message.

  8. For Hotspot rules

    a. The title should start with a verb in the present participle form (-ing). The title should end with \"is security-sensitive\"

    b. Noncompliant Title Avoid creation of cookies without the \"secure\" flag

    c. Compliant Solution Creating cookies without the \"secure\" flag is security-sensitive

    d. Rule descriptions should include - Rationale (unlabeled) - explaining why this rule makes sense. - Ask Yourself Whether - set of questions that the developer should ask herself/himself to decide on missing implementation based on the context of an application. - Recommended Secure Coding Practices - describing all the ways to mitigate the risk.

5. Set SonarQube Exclusions

SonarQube results may not be relevant for certain type of files. In order to overcome this, SonarQube allows to precisely configure what exactly needs to be analyzed. It has options to completely or partially exclude files/directories from issue detection, duplication detection and code coverage.

Best practices on narrowing the focus

  1. Consider excluding generated code and source code from libraries, etc that can lead to more noise and issues marked on the generated code.
  2. Consider SonarQube narrowing techniques to exclude files, ignore issues, and skipping modules only when the issues generated from SonarQube doesn't seem relevant for certain type of objects.

6. Set 'New code definition' at branch level for all projects.

New Code is the changes from a previous version, a specific analysis, a reference branch, or within a specific period. This helps keep focus on the code that's been changed since the new code definition. You can define new code definition at Global, Project or Branch level. It is recommended to define the new code definition at the branch level.

7. Configure Additional Plugins as required.

Enable support for additional code analyzers and languages (ex: YAML, TypeScript, Python, OWASP) in SonarQube by installing new Plugins from Admin dashboard as per project needs. Sonar releases an enhanced set of rules periodically for the existing languages with the flexibility to plugins.

8. Integrate SonarQube with Active Directory to enable enterprise authentication.

9. Configure Continuous Integration systems to fire SonarQube analysis after each commit.

10. Use pull request analysis feature of SonarQube developer Edition.

New issues introduced by Pull Request can be viewed in the SonarQube interface and resolved before merging with the target branch. This feature is available starting in Developer Edition.

11. Change Control Board based Governance model for Enterprise SonarQube.

12. Choose Portfolio Management feature of SonarQube Enterprise version.

SonarQube Enterprise Edition has advanced features to group projects to match internal hierarchy. Portfolios give insights into the health of all the projects across departments.

13. Use Reporting features to view key metrics.

Reporting plugins are available for SonarQube that can be installed from the marketplace to generate docx and xlsx report files with all issues.

SonarQube Enterprise Edition provides advanced features - PDF Executive Reports to generate, export and schedule reports in PDF format. Enterprise edition is also equipped with dedicated reports to track application security against categories of the OWASP and SANS top 25 standards. It will help Stakeholders view key metrics across projects.

14. Set up Notification feature

Users with Quality Profile Administer rights will receive notification by default when the built-in quality profiles are updated. It is recommended to add users to a group which has quality profile administration rights to receive notification on changes to quality profiles.

Users need to subscribe to get notifications on completion of each analysis, as the admin users cannot proactively subscribe other users. For example, users can subscribe to 'New quality gate status' notification to be notified when a quality gate fails. It is recommended to inform users to use the SonarQube notification feature and subscribe to notifications individually.

15. Set user permissions

To make changes (create, edit or delete) the project, quality gates and quality profiles users must be granted the Administer Quality Profiles and Gates permission. Other permissions to browse, view source code, administer issues can be granted to groups at project level.

  • Users with approval permissions like SMEs or Product Architects can be added as administrators. Any changes to Quality Profiles and Quality Gates can be handled by users in this group.

  • Team members proposing changes to Quality profiles and Quality gates needs to seek approval (email or other communication mode). Quality Profiles related to languages should be approved by SME for the language. Quality Gates should be approved by from the project team members, Architects (Product Architect, Quality and Portfolio Architect).

Best practices for SonarQube Users

  • IDE integration - Include SonarLint as part of the IDE. Developer can identify code vulnerabilities in early stages of development. It will start notifying developers as they type code and get recommendations to improve.

    Best practices on IDE integration

    1. Configure SonarLint rulesets from preferences to ensure that the same rules are applied in the SonarQube server and code.
    2. Consider using SonarLint Smart notification feature available as part of SonarQube Developer Edition. Developers using connected mode in SonarLint can receive notifications from SonarQube on Quality Gate status and analysis issues in IDE itself.

  • Pipeline integration - Azure DevOps has an extension for SonarQube available in the visual studio marketplace. SonarQube extension has tasks that can be incorporated into the build definitions to integrate SonarQube analysis. This extension provides a dedicated SonarQube endpoint that defines the SonarQube server to be used. SonarQube Server can then be declared as a service endpoint in Azure DevOps.

    Pipeline Integration standards

    1. To integrate SonarQube within pipeline, at least steps 'Prepare analysis configuration' and 'Run code analysis' are required for a .NET project and at least step 'Prepare analysis configuration' is required for a java project. Step 'Publish quality gate result' is optional.
    2. 'Prepare analysis configuration' task should be before any MS Build/Maven/Gradle or Visual Studio build tasks.
    3. 'Run code analysis' task should be after 'Visual Studio Test' task.
    4. 'Publish quality gate result' should be after the 'Run code analysis' task for a .NET project and after Maven/Gradle task for a java project.
    5. Keep 'Integrate with MS Build'/'Integrate with Maven or Gradle' option checked in 'prepare analysis configuration' task and specify at least the project key. For other project types choose 'use standalone server'
    6. For analyzing a .NET solution, check the 'Code coverage enabled' checkbox in the 'Visual Studio Test' task to process code coverage and have it imported into SonarQube.
    7. 'Run code analysis' task can also be achieved by enclosing the build tasks within the dotnet scanner scripts. A project key is required for this purpose which can be requested from the Energizers team and eventually via an automated Sonar key Request Support ticket form. This key should be used in the script for running the dotnet scanner commands.

  • Ensure proper team communication and dashboard monitoring. Management users can monitor dashboards and broadcast regular notices with information received from SonarQube about the project's evolution, highlights, lowlights, etc.

Access SonarQube from Azure DevOps Pipelines

  • Navigate to the pipeline associated with the branch. Click on the recently run pipeline description.

  • Extensions tab displays the SonarQube Analysis Report.

  • Click on the detailed SonarQube report to view the results.

Setup SonarQube in Azure DevOps Pipelines

Azure DevOps has an extension for SonarQube available in the visual studio marketplace. SonarQube extension has tasks that can be incorporated into the build definitions to integrate SonarQube analysis. This extension provides a dedicated SonarQube endpoint that defines the SonarQube server to be used. SonarQube Server can then be declared as a service endpoint in Azure DevOps.

Extension has three tasks

  1. Prepare analysis configuration -- This task is mandatory and configures the required settings prior to executing a build.
  2. Run Code analysis -- This task performs source code analysis.
  3. Publish quality gate result -- This task is optional, and it displays the quality gate status in build summary.

Steps to setup SonarQube with Azure DevOps

  1. Install SonarQube Azure DevOps extension from marketplace.
  2. Add pipeline service connection for SonarQube. Project Settings -> Pipelines -> Service Connection -> New Service Connection -> SonarQube

  3. Give the Server URL, name, and authentication token. Token can be retrieved from SonarQube -> My Account -> Security -> Generate Token

  4. Add individual users or add users to the default group to grant permissions to the service connection.

  5. Configure build definition of pipeline to include steps provided by extension

    a. Prepare analysis configuration Provide project name, project key and service endpoint name

    b. Build project Before including 'Run code analysis' task, include task to build the source project and the test project.

    c. Run code analysis task Add this task towards the end of the build task.

    d. Publish Quality Gate Result This task will display the quality gate result in the build summary.

    e. Instead of the 'Run code analysis' task, script can also be included in the pipeline to run sonar-scanner against the code. Enclose the build tasks within the dotnet scanner script as shown
    Refer to Azure DevOps integration

Requesting rules to be disabled globally

  • The request should be created through a support ticket
  • The request should be reviewed by a SME in the corresponding technology
  • There should be a traceability record kept for the changes made in the rules
  • The rule can be disabled locally for a project also
  • This can be done by going to project's Administration > General Settings > Analysis Scope > Issues

  • Add ignore rule as follows

    • To ignore rule id specified in KEY on all files

    KEY = csharpsquid:S1155 PATH = **/* - Rule id can be found in the rule definition

References

SonarQube official documentation. SonarQube basics, setup, architecture, integration and other SonarQube related details can be understood in detail from the SonarQube official documentation.