Security engine custom configuration
Security Engine Custom Configuration is available as part of the Enterprise Edition and above.
The security engine tracks the path that data follows through your code. It detects when data that's potentially manipulated by a malicious user reaches a sensitive piece of code where an attack can occur.
Those potentially malicious data are also called tainted data because they are tainted by user inputs.
SonarQube's security engine already knows a lot of APIs that are potential sources or targets of attack. While we do our best to identify publicly available APIs, we can't know everything about your homemade frameworks particularly when it comes to sanitizing your data. Because of this, SonarQube allows you to customize the security engine to add your own sources, sanitizers, passthroughs, and sinks (see the Elements section below for more on these elements).
For example, you may want to:
- Add a source to add support for a framework that SonarQube doesn't cover out of the box.
- Use a custom sanitizer to tell the security engine that all data going through sanitizers should be considered safe. This allows you to remove false positives and tailor the security engine to your company.
You can customize elements for Java, PHP, C#, and Python rules in the security engine. Click the languages below to expand a list of customizable rules for that language:
You can add the following elements to your custom configuration:
- Source – Where you get user data. You should always consider user data tainted and vulnerable to injection attacks. Example: Calling
HttpServletRequest#getParam("foo")will return tainted content.
- Sanitizer – Finds and removes malicious content from one or more potentially tainted arguments. Example:
DatabaseUtils#sqlEscapeString(String str)returns a modified version of
strwhere characters used in an SQL injection attack are removed.
- Validator - Marks one or more arguments as safe from malicious content. Example:
String#matches(String str)can be used to verify that
strdoes not contain any content which may be used in an injection attack.
- Passthrough – Allows you to keep track of tainted data sent to a library outside the current function. When you pass a tainted value to a library function outside the current function, SonarQube automatically assumes it's being passed to a sanitizer. If the tainted data isn't being passed to a sanitizer, you can set up a passthrough to keep track of the data.
- Sink – A piece of code that can perform a security-sensitive task. Data should not contain any malicious content once it reaches a sink. Example: Running an SQL query with
All custom configurations rely on the accuracy of the
methodIds provided. The
methodId format differs for each language. Click the language you're using below for more information on the format for that language.
Creating your custom configuration JSON file
You need to add your custom configurations to SonarQube using a JSON file. You can apply your custom configuration to a specific project or to all of your projects at the global level in SonarQube:
- Project level – go to Project Settings > General Settings > SAST Engine and add your JSON file to the JAVA/PHP/C#/Python custom configuration field.
- Global level – go to Administration > General Settings > SAST Engine and add your JSON file to the JAVA/PHP/C#/Python custom configuration field.
See the following section for more information on formatting your JSON file.
Configuration file format
Your JSON file should include the rule you're adding a custom element to, the element you are customizing, and the
methodId for each element. Each language needs a separate JSON file but can contain multiple rules. You may use the special rule key
common to apply the given configuration to all the rules. Click your language below to expand an example of a JSON file to help you understand the expected format.
(Deprecated) Customizing through analysis parameters
Customizing the security engine through analysis parameters is deprecated. We recommend adding your custom configuration in SonarQube as shown above. This allows you to create a single configuration file for each language and to easily apply it to multiple projects or globally.
To customize the SonarQube security engine, you can feed security configuration data through parameters given to the SonarScanners. To do this, you should provide JSON files with the value of the new analysis parameters.
The configuration works per rule. You can't share a configuration between rules.
The parameters should use the following syntax:
ConfigType value can be one of the following:
RuleRepository value can be one of the following:
javasecurity: if you want to customize the Java Security Engine
phpsecurity: if you want to customize the PHP Security Engine
roslyn.sonaranalyzer.security.cs: if you want to customize the C# Security Engine
pythonsecurity: if you want to customize the Python Security Engine
RuleKey value should be one of the values shown in the Rules section above.
JSON formatting example
Configuration is provided using JSON files. Click the heading below to expand an example PHP JSON file to help you understand the expected format.
Deactivating the core configuration
You can disable the core configuration per language or per rule using the following:
© 2008-2023, SonarSource S.A, Switzerland. Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution-NonCommercial 3.0 United States License. SONARQUBE is a trademark of SonarSource SA. All other trademarks and copyrights are the property of their respective owners.