Latest | Analyzing source code | Security engine custom configuration

Security engine custom configuration

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.

Rules

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:

Java

S2076: OS commands should not be vulnerable to command injection attacks
S2078: LDAP queries should not be vulnerable to injection attacks
S2083: I/O function calls should not be vulnerable to path injection attacks
S2091: XPath expressions should not be vulnerable to injection attacks
S2631: Regular expressions should not be vulnerable to Denial of Service attacks
S3649: Database queries should not be vulnerable to injection attacks
S5131: Endpoints should not be vulnerable to reflected cross-site scripting (XSS) attacks
S5135: Deserialization should not be vulnerable to injection attacks
S5144: Server-side requests should not be vulnerable to forging attacks
S5145: Logging should not be vulnerable to injection attacks
S5146: HTTP request redirections should not be open to forging attacks
S5147: NoSQL operations should not be vulnerable to injection attacks
S5883: OS commands should not be vulnerable to argument injection attacks
S5334: Dynamic code execution should not be vulnerable to injection attacks
S6096: Extracting archives should not lead to zip slip vulnerabilities
S6173: Reflection should not be vulnerable to injection attacks
S6287: Applications should not create session cookies from untrusted input
S6350: Constructing arguments of system commands from user input is security-sensitive
S6384: Components should not be vulnerable to intent redirection
S6390: Thread suspensions should not be vulnerable to Denial of Service attacks
S6398: JSON operations should not be vulnerable to injection attacks
S6399: XML operations should not be vulnerable to injection attacks
S6547: Environment variables should not be defined from untrusted input
S6549: Accessing files should not lead to filesystem oracle attacks

PHP

S2076: OS commands should not be vulnerable to command injection attacks
S2078: LDAP queries should not be vulnerable to injection attacks
S2083: I/O function calls should not be vulnerable to path injection attacks
S2091: XPath expressions should not be vulnerable to injection attacks
S2631: Regular expressions should not be vulnerable to Denial of Service attacks
S3649: Database queries should not be vulnerable to injection attacks
S5131: Endpoints should not be vulnerable to reflected cross-site scripting (XSS) attacks
S5135: Deserialization should not be vulnerable to injection attacks
S5144: Server-side requests should not be vulnerable to forging attacks
S5145: Logging should not be vulnerable to injection attacks
S5146: HTTP request redirections should not be open to forging attacks
S5334: Dynamic code execution should not be vulnerable to injection attacks
S5335: Include expressions should not be vulnerable to injection attacks
S5883: OS commands should not be vulnerable to argument injection attacks
S6173: Reflection should not be vulnerable to injection attacks
S6287: Applications should not create session cookies from untrusted input
S6350: Constructing arguments of system commands from user input is security-sensitive

S2076: OS commands should not be vulnerable to command injection attacks
S2078: LDAP queries should not be vulnerable to injection attacks
S2083: I/O function calls should not be vulnerable to path injection attacks
S2091: XPath expressions should not be vulnerable to injection attacks
S2631: Regular expressions should not be vulnerable to Denial of Service attacks
S3649: Database queries should not be vulnerable to injection attacks
S5131: Endpoints should not be vulnerable to reflected cross-site scripting (XSS) attacks
S5135: Deserialization should not be vulnerable to injection attacks
S5144: Server-side requests should not be vulnerable to forging attacks
S5145: Logging should not be vulnerable to injection attacks
S5146: HTTP request redirections should not be open to forging attacks
S5334: Dynamic code execution should not be vulnerable to injection attacks
S5883: OS commands should not be vulnerable to argument injection attacks
S6096: Extracting archives should not lead to zip slip vulnerabilities
S6173: Reflection should not be vulnerable to injection attacks
S6287: Applications should not create session cookies from untrusted input
S6350: Constructing arguments of system commands from user input is security-sensitive
S6399: XML operations should not be vulnerable to injection attacks
S6639: Memory allocations should not be vulnerable to Denial of Service attacks
S6641: Connection strings should not be vulnerable to injections attacks

Python

S2076: OS commands should not be vulnerable to command injection attacks
S2078: LDAP queries should not be vulnerable to injection attacks
S2083: I/O function calls should not be vulnerable to path injection attacks
S2091: XPath expressions should not be vulnerable to injection attacks
S2631: Regular expressions should not be vulnerable to Denial of Service attacks
S3649: Database queries should not be vulnerable to injection attacks
S5131: Endpoints should not be vulnerable to reflected cross-site scripting (XSS) attacks
S5135: Deserialization should not be vulnerable to injection attacks
S5144: Server-side requests should not be vulnerable to forging attacks
S5145: Logging should not be vulnerable to injection attacks
S5146: HTTP request redirections should not be open to forging attacks
S5147: NoSQL operations should not be vulnerable to injection attacks
S5334: Dynamic code execution should not be vulnerable to injection attacks
S5496: Server-side templates should not be vulnerable to injection attacks
S6287: Applications should not create session cookies from untrusted input
S6350: Constructing arguments of system commands from user input is security-sensitive

Elements

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 str where 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 str does 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 java.sql.Statement#execute.

MethodId

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.

Java JSON file example

{
  "S3649": {
    "sources": [
      {
        "methodId": "my.package.ServerRequest#getQuery()Ljava/lang/String;"
      }
    ],
    "sanitizers": [
      {
        "methodId": "my.package.StringUtils#stringReplace(Ljava/lang/String;Ljava/lang/String;)Ljava/lang/String;",
        "args": [
          2 
        ]
      }
    ],
    "validators": [
      {
        "methodId": "my.package.StringUtils#equals(Ljava/lang/String;)Z",
        "args": [
          1
        ]
      }
    ],
    "passthroughs": [
      {
        "methodId": "my.package.RawUrl#<init>(Ljava/lang/String;)V",
        "isWhitelist": true,
        "args": [
          1
        ]
      }
    ],
    "sinks": [
      {
        "methodId": "my.package.MySql#query(Ljava/lang/String;)V",
        "args": [
          1
        ]
      },
      {
        "methodId": "my.package.SqlStatement#execute",
        "isMethodPrefix": true,
        "args": [
          0,
          1
        ]
      },
      {
        "methodId": "my.package.SqlStatement#run(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)V",
        "interval": {
          "fromIndex": 1
        }
      }
    ]
  },
  "S5131": {
    "sources": [
      {
        "methodId": "my.package.ServerRequest#getQueryString()Ljava/lang/String;"
      }
    ],
    "sinks": [
      {
        "methodId": "my.package.Server#write(",
        "isMethodPrefix": true,
        "interval": {
          "fromIndex": 1
        }
      }
    ]
  },
  "common": {
    "sources": [
      {
        "methodId": "my.package.Input#getUserInput()Ljava/lang/String;"
      }
    ]
  }
}

The args is the index of the parameter that can receive a tainted variable. Index starts:

1 for a function call.
0 for a method call, index 0 being the current instance (this). The args field must be a non-empty array of non-negative integers, and it is a mandatory field for sanitizers and validators.

PHP JSON file example

{
  "S3649": {
    "sources": [
      {
        "methodId": "My\\Namespace\\ClassName\\ServerRequest::getQuery"
      }
    ],
    "sanitizers": [
      {
        "methodId": "str_replace",
        "args": [
          3
        ]
      }
    ],
    "validators": [
      {
        "methodId": "My\\Namespace\\Validator\\inArray::isValid",
        "args": [
          1
        ]
      }
    ],
    "passthroughs": [
      {
        "methodId": "My\\Namespace\\RawUrl::RawUrl",
        "isWhitelist": true,
        "args": [
          1
        ]
      }
    ],
    "sinks": [
      {
        "methodId": "mysql_query",
        "args": [
          1
        ]
      },
     {
        "methodId": "My\\Namespace\\SqlStatement::execute",
        "isMethodPrefix": true,
        "args": [
          0,
          1
        ]
      },
      {
        "methodId": "My\\Namespace\\SqlStatement::run",
        "interval": {
          "fromIndex": 1
        }
      }
    ]
  },
  "S5131": {
    "sources": [
      {
        "methodId": "My\\Namespace\\ClassName\\ServerRequest::getQueryString"
      }
    ],
    "sinks": [
      {
        "methodId": "My\\Namespace\\ClassName\\Server::write",
        "isMethodPrefix": true,
        "interval": {
          "fromIndex": 1
        }
      }
    ]
  },
  "common": {
    "sources": [
      {
        "methodId": "My\\Namespace\\ClassName\\Input::getUserInput"
      }
    ]
  }
}

The args is the index of the parameter that can receive a tainted variable. Index starts:

1 for a function call.
0 for a method call, index 0 being the current instance (this). The args field must be a non-empty array of non-negative integers, and it is a mandatory field for sanitizers and validators.

C# JSON file example

{
  "S3649": {
    "sources": [
      {
        "methodId": "My.Namespace.ServerRequest.GetQuery()"
      }
    ],
    "sanitizers": [
      {
        "methodId": "My.Namespace.StringUtils.StringReplace(string, string)",
        "args": [
          0
        ]
      }
    ],
    "validators": [
      {
        "methodId": "My.Namespace.StringUtils.Regex.Matches(string)",
        "args": [
          0
        ]
      }
    ],
    "passthroughs": [
      {
        "methodId": "My.Namespace.RawUrl.RawUrl(string)",
        "isWhitelist": true,
        "args": [
          1
        ]
      }
    ],
    "sinks": [
      {
        "methodId": "My.Namespace.MySql.Query(string)",
        "args": [
          1
        ]
      },
      {
        "methodId": "My.Namespace.SqlStatement.Execute",
        "isMethodPrefix": true,
        "args": [
          0,
          1
        ]
      },
      {
        "methodId": "My.Namespace.SqlStatement.Run(string, string, string)",
        "interval": {
          "fromIndex": 1
        }
      }
    ]
  },
  "S5131": {
    "sources": [
      {
        "$comment": "The following method id is a getter on the 'QueryString' property",
        "methodId": "My.Namespace.ServerRequest.QueryString.get"
      }
    ],
    "sinks": [
      {
        "methodId": "My.Namespace.Server.Write(",
        "isMethodPrefix": true,
        "interval": {
          "fromIndex": 1
        }
      }
    ]
  },
  "common": {
    "sources": [
      {
        "methodId": "My.Namespace.Input.GetUserInput()"
      }
    ]
  }
}

The args is the index of the parameter that can receive a tainted variable. Index starts:

1 for a function call.
0 for a method call, index 0 being the current instance (this). The args field must be a non-empty array of non-negative integers, and it is a mandatory field for sanitizers and validators.

Python JSON file example

{
  "S3649": {
    "sources": [
      {
        "methodId": "my.namespace.ServerRequest.get_query"
      }
    ],
    "sanitizers": [
      {
        "methodId": "str_replace",
        "args": [
          1
        ]
      }
    ],
    "validators": [
      {
        "methodId": "my.namespace.regex.matches",
        "args": [
          1
        ]
      }
    ],
    "passthroughs": [
      {
        "methodId": "my.namespace.RawUrl",
        "isWhitelist": true,
        "args": [
          1
        ]
      }
    ],
    "sinks": [
      {
        "methodId": "mysql_query",
        "args": [
          1
        ]
      },
      {
        "methodId": "my.namespace.SqlStatement.execute",
        "isMethodPrefix": true,
        "args": [
          0,
          1
        ]
      },
      {
        "methodId": "my.namespace.SqlStatement.run",
        "interval": {
          "fromIndex": 1
        }
      }
    ]
  },
  "S5131": {
    "sources": [
      {
        "methodId": "my.namespace.ServerRequest.get_query_string"
      }
    ],
    "sinks": [
      {
        "methodId": "my.namespace.Server.write(",
        "isMethodPrefix": true,
        "interval": {
          "fromIndex": 1
        }
      }
    ]
  },
  "common": {
    "sources": [
      {
        "methodId": "my.namespace.Input.get_input"
      }
    ]
  }
}

The args is the index of the parameter that can receive a tainted variable. Index starts:

1 for a function call.
0 for a method call, index 0 being the current instance (this). The args field must be a non-empty array of non-negative integers, and it is a mandatory field for sanitizers and validators.

(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:

sonar.security.[ConfigType].[RuleRepository].[RuleKey]=[FileName]

The ConfigType value can be one of the following:

sources
sanitizers
passthroughs
sinks

The 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

The 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.

JSON File Format Example for PHP

You need to create a configuration for each rule. There is no way to share a configuration between rules.

{
  "sources": [
    {
      "methodId": "My\\Namespace\\ClassName\\ServerRequest::getQuery"
    }
  ],
  "sanitizers": [
    {
      "methodId": "str_replace",
      "args": [
        3
      ]
    }
  ],
  "validators": [
    {
     "methodId": "My\\Namespace\\Validator\\inArray::isValid",
     "args": [
        1
      ]
    }
  ],
 "passthroughs": [
    {
      "methodId": "rawurldecode",
      "args": [
        1
      ]
    }
  ],
  "sinks": [
    {
      "methodId": "mysql_query",
      "args": [
        1
      ]
    },
    {
      "methodId": "My\\Namespace\\SqlStatement::execute",
      "isMethodPrefix": true, // this is to say that all the methods starting with execute on the SqlStatement object will be considered
      "args": [
        0,
        1
      ]
    },
    {
      "methodId": "My\\Namespace\\SqlStatement::run",
      "interval": {
        "fromIndex": 1 // every parameter from the number 1 will be considered
      }
    }
  ]  
}

The args is the index of the parameter that can receive a tainted variable. Index starts:

1 for a function call.
0 for a method call, index 0 being the current instance (this) . The args field must be a non-empty array of non-negative integers, and it is a mandatory field for sanitizers and validators.

Deactivating the core configuration

Was this page helpful?

Security engine custom configuration

On this page

.css-4ebt6d{position:relative;--tw-text-opacity:1;color:rgb(0 0 0 / var(--tw-text-opacity));}Rules.css-abpesc{width:2rem;display:none;margin-left:0.5rem;fill:#5F656D;}.css-abpesc:hover{fill:#290042;}

Elements

MethodId

Creating your custom configuration JSON file

Configuration file format.css-p7dib0{width:1.75rem;display:none;margin-left:0.5rem;fill:#5F656D;}.css-p7dib0:hover{fill:#290042;}

(Deprecated) Customizing through analysis parameters

JSON formatting example

Deactivating the core configuration

Rules

Configuration file format