sonar.cxx.other.rules

Overview

The cxx plugin provides an open interface to integrate any external tool into SonarQube. In principle, the sensor works similar to the Generic Issue Import Format, but bypasses its limitations:

• You can manage the rules within SonarQube; for instance, you can mark them False Positive.
• You can manage the activation of the rules that raise these issues within SonarQube. Rules are visible on the Rules page or reflected in Quality Profiles.

The implementation always works in three steps:

1. Definition of rules and register them with the SonarQube Server via an XML file.
2. Activate the rules in a Quality Profile.
3. Create XML reports with the external tool and transfer them to SonarQube via the SonarScanner (see sonar.cxx.other.reportPaths).

Rule Definition

Create an XML file describing the rules and place it on the SonarQube Server under Administration > Configuration > General Settings > CXX External Analyzers at sonar.cxx.other.rules. Insert the content of the XML file into a field and save the content via Save. Multiple rule definitions can also be inserted for multiple tools.

Important: To activate the rules, you must restart the SonarQube Server after saving!

In the XML file, the rules must be defined as follows:

<rules>
  <rule>
    <!-- Required key. Max length is 200 characters.
    The rule key must be unique across all rules defined under 'other'!
    If several tools are integrated via 'other', a tool-specific prefix is recommended.
    -->
    <key>the-rule-key</key>

    <!-- Required name. Max length is 200 characters. -->
    <name>The purpose of the rule</name>

    <!-- Required description. No max length. -->
    <description>
      <![CDATA[The description]]>
    </description>
    <!-- Optional format of description. Supported values are HTML (default) and MARKDOWN.
         It is also possible to add hyperlinks to the description, use <a> tags in HTML.
    -->
    <descriptionFormat>HTML</descriptionFormat>

    <!-- Optional key for configuration of some rule engines -->
    <internalKey>Checker/TreeWalker/LocalVariableName</internalKey>

    <!-- Default severity when enabling the rule in a Quality profile.  -->
    <!-- Possible values are INFO, MINOR, MAJOR (default), CRITICAL, BLOCKER. -->
    <severity>BLOCKER</severity>

    <!-- Possible values are SINGLE (default) and MULTIPLE for template rules -->
    <cardinality>SINGLE</cardinality>

    <!-- Status displayed in rules console. Possible values are BETA, READY (default), DEPRECATED. -->
    <status>BETA</status>

    <!-- Type as defined by the SonarQube Quality Model. Possible values are CODE_SMELL (default), BUG and VULNERABILITY.-->
    <type>BUG</type>

    <!-- Optional tags. See org.sonar.api.server.rule.RuleTagFormat. The maximal length of all tags is 4000 characters. -->
    <tag>misra</tag>
    <tag>multi-threading</tag>

    <!-- Optional parameters -->
    <param>
      <!-- Required key. Max length is 128 characters. -->
      <key>the-param-key</key>
      <description>
        <![CDATA[the optional description, in HTML format. Max length is 4000 characters.]]>
      </description>
      <!-- Optional default value, used when enabling the rule in a Quality profile. Max length is 4000 characters. -->
      <defaultValue>42</defaultValue>
    </param>
    <param>
      <key>another-param</key>
    </param>

    <!-- Quality Model - type of debt remediation function -->
    <!-- See enum {@link org.sonar.api.server.debt.DebtRemediationFunction.Type} for supported values -->
    <!-- It was previously named 'debtRemediationFunction' which is still supported but deprecated since 5.5 -->
    <!-- Since 5.5 -->
    <remediationFunction>LINEAR_OFFSET</remediationFunction>

    <!-- Quality Model - raw description of the "gap", used for some types of remediation functions. -->
    <!-- See {@link org.sonar.api.server.rule.RulesDefinition.NewRule#setGapDescription(String)} -->
    <!-- It was previously named 'effortToFixDescription' which is still supported but deprecated since 5.5 -->
    <!-- Since 5.5 -->
    <gapDescription>Effort to test one uncovered condition</gapFixDescription>

    <!-- Quality Model - gap multiplier of debt remediation function. Must be defined only for some function types. -->
    <!-- See {@link org.sonar.api.server.rule.RulesDefinition.DebtRemediationFunctions} -->
    <!-- It was previously named 'debtRemediationFunctionCoefficient' which is still supported but deprecated since 5.5 -->
    <!-- Since 5.5 -->
    <remediationFunctionGapMultiplier>10min</remediationFunctionGapMultiplier>

    <!-- Quality Model - base effort of debt remediation function. Must be defined only for some function types. -->
    <!-- See {@link org.sonar.api.server.rule.RulesDefinition.DebtRemediationFunctions} -->
    <!-- It was previously named 'debtRemediationFunctionOffset' which is still supported but deprecated since 5.5 -->
    <!-- Since 5.5 -->
    <remediationFunctionBaseEffort>2min</remediationFunctionBaseEffort>

    <!-- Deprecated field, replaced by "internalKey" -->
    <configKey>Checker/TreeWalker/LocalVariableName</configKey>

    <!-- Deprecated field, replaced by "severity" -->
    <priority>BLOCKER</priority>

  </rule>
</rules>

Example of a rule definition

<rules>
  <rule>
    <key>TOOL.S1442</key>
    <name>"alert(...)" should not be used</name>
    <description>alert(...) can be useful for debugging during development, but ...</description>
    <tag>cwe</tag>
    <tag>security</tag>
    <tag>user-experience</tag>
    <debtRemediationFunction>CONSTANT_ISSUE</debtRemediationFunction>
    <debtRemediationFunctionBaseOffset>10min</debtRemediationFunctionBaseOffset>
  </rule>

  <!-- more rules... -->
</rules>

Use rules

Issue are then read in via the sensor sonar.cxx.other.reportPaths.

Troubleshooting

If after inserting and restarting the SonarQube Server the rules are not displayed in the UI, please check:

• Are your rules defined according to the rule definition above?
• Did you restart the SonarQube Server after saving?
• Make sure that the inserted XML is valid by checking the data with an XML validator (e.g. open it in Firefox).
• All <keys> in the 'other' namespace (across all XML data) must be unique.
• Verify the Web Server log file, see below.

Understanding the Web Server log file

Rules of the 'other' repository are loaded and registered once during server startup.

In case of problems with the rules, check the Web Server log file. Open the file via: Administration > System > Download Logs > Web Server. There should be no sonar.cxx.other.reportPaths error in the file.

2021.06.01 07:43:47 INFO  web[][o.s.s.r.RegisterRules] Register rules
2021.06.01 07:44:26 ERROR web[][o.s.c.s.o.CxxOtherRepository] Cannot load rule definions for 'sonar.cxx.other.rules', ... XML ...

In case of an error, the error message gives information about the cause and which entry is faulty. Normally the server should start anyway. Correct the error in the SonarQube UI and restart the server.