sonar.cxx.other.rules
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:
- Definition of rules and register them with the SonarQube Server via an XML file.
- Activate the rules in a Quality Profile.
- Create XML reports with the external tool and transfer them to SonarQube via the SonarScanner (see sonar.cxx.other.reportPaths).
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 add new rules or apply changes to the rules, remove the plugin after the change, restart the SonarQube server, add the plugin back into the plugin directory and restart the SonarQube server again. It is important that no analysis takes place during the server restart, otherwise the issue will be removed and displayed as issues in New Code.
Hint: Starting with SonarQube 9.x LTS, a plugin cache mechanism was introduced that only reloads a plugin and thus the rules of a repository if a change to at least one plugin is detected. A “change” can be if there is a plugin with a new PluginKey in the plugin directory. It also checks whether the hash value of a plugin package has changed. If a change is detected, the plugin and thus the repositories it contains are updated.
In the XML file, the rules must be defined as follows (rules.xsd):
<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>
<!-- Optional deprecated rules keys for this rule. See org.sonar.api.server.rule.RulesDefinition.Rule.deprecatedRuleKeys
If you want to rename the key of a rule register the rule's previous key. This will allow SonarQube to support
"issue re-keying" for this rule. If the key of an existing rule is changed without declaring deprecated keys, existing
issues for this rule, created under the rule's previous key, will be closed and new ones will be created under the
issue's new key. Several deprecated keys can be provided to allow SonarQube to support several key changes across
multiple versions of a plugin.
-->
<deprecatedKey>the-deprecated-rule-key1</deprecatedKey>
<deprecatedKey>the-deprecated-rule-key2</deprecatedKey>
<!-- 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 -->
<descriptionFormat>HTML</descriptionFormat>
<!-- 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>
<!-- There are three possible rule statuses: BETA, READY (default), and DEPRECATED. Sometimes, rules are first issued
in BETA status and then moved to READY. Most rules are in READY status; READY to be used in production. When Sonar
developers realize that a rule no longer makes sense, they first deprecate the rule, then eventually drop it.
-->
<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 "severity" -->
<priority>BLOCKER</priority>
</rule>
</rules><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>Issue are then read in via the sensor sonar.cxx.other.reportPaths.
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 the rules twice as described above?
- 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.
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.
First start with a plugin change detected contains:
2023.05.17 17:02:12 INFO web[][o.s.s.p.DetectPluginChange] Detect plugin changes
2023.05.17 17:02:14 INFO web[][o.s.s.s.GeneratePluginIndex] Generate scanner plugin index
2023.05.17 17:02:14 INFO web[][o.s.s.s.RegisterMetrics] Register metrics
2023.05.17 17:02:14 INFO web[][o.s.s.r.RegisterRules] Register rules
2023.05.17 17:02:19 INFO web[][o.s.s.q.b.BuiltInQProfileRepositoryImpl] Load quality profiles
2023.05.17 17:02:19 INFO web[][o.s.s.q.RegisterQualityProfiles] Register quality profiles
2023.05.17 17:02:20 INFO web[][o.s.s.q.RegisterQualityProfiles] Update profile cxx/Sonar way
2023.05.17 17:02:20 INFO web[][o.s.s.s.RegisterPermissionTemplates] Register permission templates
2023.05.17 17:02:20 INFO web[][o.s.s.s.RenameDeprecatedPropertyKeys] Rename deprecated property keys
2023.05.17 17:02:20 INFO web[][o.s.s.s.RegisterPlugins] Register plugins
All following starts without plugin change contains:
2023.08.21 14:07:35 INFO web[][o.s.s.p.DetectPluginChange] Detect plugin changes
2023.08.21 14:07:36 INFO web[][o.s.s.p.DetectPluginChange] No plugin change detected
There should be no sonar.cxx.other.reportPaths error in the file:
2023.06.01 07:43:47 INFO web[][o.s.s.r.RegisterRules] Register rules
2023.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.