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 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 server after saving!

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

<rules>
  <rule>
    <!-- Required key. Max length is 200 characters. -->
    <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:

<rules>
  <rule>
    <key>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>

  <!-- another rules... -->
</rules>

Use rules

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