Skip to content

Extending the code analysis

Jump to bottom
guwirth edited this page Mar 10, 2021 · 36 revisions

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

Deprecated: Extending rules in supported code analysers

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.

Using a xml definition

  1. Define those rules using the XML format described further below in a temporary file.
  2. Paste the content of file into the relevant configuration property in the SonarQube Server. For example for cppcheck. UI Settings
  3. Restart the SonarQube Server (This is the drawback of this method).
  4. Make sure the newly added rules are visible in the quality profile; enable them
  5. Run the analysis

Properties (deprecated with 1.3.2)

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 the rules file

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:https://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>

Deprecated: SQALE characteristics (only V0.9.4, V0.9.5)

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:

Using Template Rules

This method allows the creation of rules on the fly, no need to for SonarQube Server restart. To do this follow these steps.

  1. Locate the relevant custom rule for the code checker you want to extend. Custom Rules Settings
  2. Press create and fill in the details Custom Rules Settings
  3. 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

Usage of unsupported code checkers

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:

  1. 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 UI Settings Use the format described above. You can import multiple custom rules by clicking the Add value and save the settings

  2. Run your checker and create a report

  3. Transform the report such that it conform to the following RNG schema:

    <element name="results" xmlns="http:https://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:https://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
4. Set the property **sonar.cxx.other.reportPath** to point to the location of transformed report (relative to project root) and run one analysis.

Resources

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
  1. Create the rules profile using the profile creator script:
    python cpplint_createrules.py cpplint.py
    This will generate the following files:
    • cpplint.xml: that should be copied to _SonarQube UI_ as per above and _SonarQube Server_ restarted after save
    • cpplint_mod.py: that should be used to check the code

  2. After this you can run the cpplint_mod.py against any source file like this:
    python cpplint_mod.py source.cpp 2> report.txt
    The output file report.txt needs to be converted to the XML format described above. For convenience a Perl script is available here and can be run as follows: perl cpplintReport2checkstyleReport.perl report.txt splint-result-0.xml
Intel Inspector XE 2013
  1. Copy the Intel Inspector rules to sonar web ui, as per above and restart server.
  2. Modify the used SonarQube quality profile to accommodate the newly added rules
  3. Run your test/application using the Intel Inspector and generate a CSV report
  4. Convert the report with: python intelInspectorReport_2_cppcheckReport.py in.csv out.xml The out.xml can be then used during the analysis to feed the Intel Inspector results into _SonarQube_.

Writing your own rules using SSLR, aka custom cxx-rules

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>

Example of a rule

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 };
  }
}

Installation and usage

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.

Sample code

You can use the https://github.com/SonarOpenCommunity/cxx-custom-checks-example-plugin as a base for your rules, kudos @felipebz

            Wiki Home             Issue Tracker             Releases             Contributors             License

Clone this wiki locally