Extending the code analysis
This description is only valid for cxx plugin version 1.x
Note: Defining rules in extensions/rules folder in SonarQube Server is no longer supported by the cxx plugin
If you're using a patched or not-yet-supported version of an integrated code checker (like Cppcheck), you probably want to see those new checks in SonarQube, too. To do this, you have 2 different approachs available.
- Define those rules using the XML format described further below in a temporary file.
- Paste the content of file into the relevant configuration property in the SonarQube Server. For example for cppcheck.
- Restart the SonarQube Server (This is the drawback of this method).
- Make sure the newly added rules are visible in the quality profile; enable them
- Run the analysis
| Property | Description |
|---|---|
| sonar.cxx.clangsa.customRules | ClangSA Rules |
| sonar.cxx.clangtidy.customRules | Clang-Tidy Rules |
| sonar.cxx.compiler-gcc.customRules | Compiler-GCC Rules |
| sonar.cxx.compiler-vc.customRules | Compiler-VC Rules |
| sonar.cxx.cppcheck.customRules | Cppcheck Custom Rules |
| sonar.cxx.drmemory.customRules | Dr Memory Analysis Rules |
| sonar.cxx.pclint.customRules | PClint Custom Rules |
| sonar.cxx.rats.customRules | RATS Custom Rules |
| sonar.cxx.valgrind.customRules | Valgrind Custom Rules |
| sonar.cxx.vera.customRules | Vera++ Custom Rules |
| sonar.cxx.other.rules | Unsupported Code Checker Custom Rules, see below |
The format of rules file is expected to be the following (RulesDefinitionXmlLoader):
V0.9.6 and later:
<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. -->
<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>It is also possible to add hyperlinks to the description, use <a> tags.
<description>
<![CDATA[<a href="http://example.com/xyz.html">Link</a>]]>
</description>Deprecated but still supported:
<rules>
<rule key="RULE_ID">
<name><![CDATA[ ... put here the human readable name of this rule ... ]]></name>
<configKey><![CDATA[RULE_ID@$(EXTERNALSENSORCLASS)]]></configKey>
<category name=" ... category type ... " />
<description><![CDATA[ ... put here the human readable description of this rule ... ]]></description>
</rule>
</rules>Starting with the version 0.9.4 it is also possible to define SQALE characteristics for other rules. To define the SQALE characteristics an extra XML file has to be defined and assigned to sonar.cxx.other.sqales. Assign the XML file on SonarQube Server side to the configuration property on the page 'C++ settings / (2) Code analysis' and restart the SonarQube Server to enable it (same as with rule definitions). The XML file must fit the XML schema for SQALE characteristics. For more complex examples have a look to the folder SQALE.
Example:
<sqale>
<chc>
<key>PORTABILITY</key>
<name>Portability</name>
<chc>
<key>COMPILER_RELATED_PORTABILITY</key>
<name>Compiler related portability</name>
<chc>
<rule-repo>other</rule-repo>
<rule-key>key</rule-key>
<prop>
<key>remediationFunction</key>
<txt>linear_offset</txt>
</prop>
<prop>
<key>remediationFactor</key>
<val>5</val>
<txt>mn</txt>
</prop>
<prop>
<key>offset</key>
<val>10</val>
<txt>mn</txt>
</prop>
</chc>
</chc>
</chc>
</sqale>Example of Levels 1 and 2 of a SQALE Quality Model:
This method allows the creation of rules on the fly, no need to for SonarQube Server restart. To do this follow these steps.
- Locate the relevant custom rule for the code checker you want to extend.
- Press create and fill in the details
- Enable the rule and run a new analysis
These rules can be created using the rest api, see https://github.com/jmecsoftware/QualityProfileEditorPlugin as an example
If you're using a code checker which is not supported by the cxx plugin, this feature is for you. It allows to feed violations into SonarQube in a code checker agnostic way. To do this follow the steps below:
-
Create a XML file describing the rules and place it in code analysis settings of the cxx plugin in the SonarQube Server under the property sonar.cxx.other.rules
Use the format described above. You can import multiple custom rules by clicking the Add value and save the settings -
Run your checker and create a report
-
Transform the report such that it conform to the following RNG schema:
<element name="results" xmlns="http://relaxng.org/ns/structure/1.0"> <zeroOrMore> <element name="error"> <attribute name="file"/> <attribute name="msg"/> <attribute name="id"/> <attribute name="line"> <data type="integer" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes" /> </attribute> <text/> </element> </zeroOrMore> </element>
Where the fields have the following semantics:
| Tag/Attribute | Semantic |
| file | Source file, relative to project path |
| line | Line number where the violation occurres |
| id | The ID of the violated SonarQube rule |
| msg | Description of the violation |
Below you find a list of code analyzers which have already been integrated using this feature and according resources. The setups have been proven to work in one particular environment; you may need to adapt it to make work in yours.
| Tool | Usage |
| cpplint |
|
| Intel Inspector XE 2013 |
|
You can write custom rules based in SSLR and in CXX API, to do this you need to create your own plugin and create a dependency in you pom.xml to the cxx plugin version you are using. And extend your checks with CustomCxxRulesDefinition
<dependency>
<groupId>org.codehaus.sonar-plugins.cxx</groupId>
<artifactId>sonar-cxx-plugin</artifactId>
<type>sonar-plugin</type>
<version>0.9.5-SNAPSHOT</version>
<scope>provided</scope>
</dependency>
public class MyCustomRulesDefinition extends CustomCxxRulesDefinition {
@Override
public String repositoryName() {
return "Repository";
}
@Override
public String repositoryKey() {
return "repo";
}
@SuppressWarnings("rawtypes")
@Override
public Class[] checkClasses() {
return new Class[] { UsingNamespaceCheck.class };
}
}
Follows a normal procedure for any SonarQube plugin, drop in extensions/plugins in you SonarQube Server and restart. After this enable the rules and run a new analysis.
You can use the https://github.com/SonarOpenCommunity/cxx-custom-checks-example-plugin as a base for your rules, kudos @felipebz