1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
|
---
title: Security Engine Custom Configuration
url: /analysis/security_configuration/
---
*Security Engine Custom Configuration is available as part of the [Enterprise Edition](https://redirect.sonarsource.com/editions/enterprise.html) and [above](https://www.sonarsource.com/plans-and-pricing/).*
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 of attack and APIs that are potential 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 to the security engine that all data going through sanitizers should be considered as safe. This allows you to remove false positives and tailor the security engine to your company.
## 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 tainted data.
* **Passthrough** – Allows you to keep track of tainted data sent to a library outside of the current function. When you pass a tainted value to a library functions outside of 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`
## Analysis Parameters
To customize the SonarQube security engine, you need to 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 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
The `RuleKey` value can be one of the following:
* For Java
* [S3649](https://rules.sonarsource.com/java/RSPEC-3649): SQL Injection
* [S5131](https://rules.sonarsource.com/java/RSPEC-5131): XSS
* [S5146](https://rules.sonarsource.com/java/RSPEC-5146): Open Redirect
* [S5167](https://rules.sonarsource.com/java/RSPEC-5167): HTTP Response Splitting
* [S2083](https://rules.sonarsource.com/java/RSPEC-2083): Path Traversal Injection
* [S2078](https://rules.sonarsource.com/java/RSPEC-2078): LDAP Injection
* [S5145](https://rules.sonarsource.com/java/RSPEC-5145): Log Injection
* [S2076](https://rules.sonarsource.com/java/RSPEC-2076): OS Command Injection
* [S2631](https://rules.sonarsource.com/java/RSPEC-2631): RegExp Injection
* [S5144](https://rules.sonarsource.com/java/RSPEC-5144): Server-Side Request Forgery (SSRF)
* [S2091](https://rules.sonarsource.com/java/RSPEC-2091): XPath Injection
* [S5135](https://rules.sonarsource.com/java/RSPEC-5135): Deserialization Injection
* [S5334](https://rules.sonarsource.com/java/RSPEC-5334): Code Injection
* For PHP
* [S3649](https://rules.sonarsource.com/php/RSPEC-3649): SQL Injection
* [S5131](https://rules.sonarsource.com/php/RSPEC-5131): XSS
* [S5146](https://rules.sonarsource.com/php/RSPEC-5146): Open Redirect
* [S5167](https://rules.sonarsource.com/php/RSPEC-5167): HTTP Response Splitting
* [S2083](https://rules.sonarsource.com/php/RSPEC-2083): Path Traversal Injection
* [S2078](https://rules.sonarsource.com/php/RSPEC-2078): LDAP Injection
* [S5145](https://rules.sonarsource.com/php/RSPEC-5145): Log Injection
* [S2076](https://rules.sonarsource.com/php/RSPEC-2076): OS Command Injection
* [S2631](https://rules.sonarsource.com/php/RSPEC-2631): RegExp Injection
* [S5144](https://rules.sonarsource.com/php/RSPEC-5144): Server-Side Request Forgery (SSRF)
* [S2091](https://rules.sonarsource.com/php/RSPEC-2091): XPath Injection
* [S5135](https://rules.sonarsource.com/php/RSPEC-5135): Deserialization Injection
* [S5334](https://rules.sonarsource.com/php/RSPEC-5334): Code Injection
* [S5335](https://rules.sonarsource.com/php/RSPEC-5335): Include Injection
* For C#
* [S3649](https://rules.sonarsource.com/csharp/RSPEC-3649): SQL Injection
* [S5131](https://rules.sonarsource.com/csharp/RSPEC-5131): XSS
* [S5146](https://rules.sonarsource.com/csharp/RSPEC-5146): Open Redirect
* [S5167](https://rules.sonarsource.com/csharp/RSPEC-5167): HTTP Response Splitting
* [S2083](https://rules.sonarsource.com/csharp/RSPEC-2083): Path Traversal Injection
* [S2078](https://rules.sonarsource.com/csharp/RSPEC-2078): LDAP Injection
* [S5145](https://rules.sonarsource.com/csharp/RSPEC-5145): Log Injection
* [S2076](https://rules.sonarsource.com/csharp/RSPEC-2076): OS Command Injection
* [S2631](https://rules.sonarsource.com/csharp/RSPEC-2631): RegExp Injection
* [S5144](https://rules.sonarsource.com/csharp/RSPEC-5144): Server-Side Request Forgery (SSRF)
* [S2091](https://rules.sonarsource.com/csharp/RSPEC-2091): XPath Injection
[[info]]
| The configuration works per rule. There is no way to share configuration between rules.
## File Format
The configuration is provided through JSON files. Here is a sample JSON file that help to understand the expected JSON format.
**JSON File Format Example for PHP**
```
{
"sources": [
{
"methodId": "My\\Namespace\\ClassName\\ServerRequest::getQuery"
}
],
"sanitizers": [
{
"methodId": "str_replace"
}
],
"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 fonction call.
* `0` for a method call, index `0` beeing the current instance (`this`)
## MethodId
All the custom configurations rely on the accuracy of the `methodIds` provided. For each language, the format of the `methodId` is different.
### MethodId for Java
The `methodId` format is inspired by the bytecode. The easiest way to get a `methodId` is to write a simple piece of Java code, compile it and then look at the bytecode generated using the `javap -c path_to.class` file, and transform it a little. Looking at the following real-life example will help you understand the format.
Let's imagine you want to declare `org.rapidoid.jdbc.JdbcClient.execute(String sql, Object... args)` as a new sink (you don't need to do this because Rapidoid is part of what is covered out of the box).
Write a simple piece of code calling the JdbcClient.execute(...) method. The code doesn't need to actually do anything.
```
import org.rapidoid.http.Req;
import org.rapidoid.jdbc.JdbcClient;
public static void callJDBCMethods(Req req) {
String tainted = req.param("TAINTED");
JdbcClient jdbc = JDBC.api();
dbc.execute(tainted, req); // Noncompliant
}
```
Run the `javap -c` and locate the piece of bytecode corresponding to the call to `JdbcClient.execute`
```
[...]
org/rapidoid/jdbc/JdbcClient.execute:(Ljava/lang/String;[Ljava/lang/Object;)I
[...]
````
* Replace the `/` in the package name with `.`
* Remove the `:`
* Replace the `.` separating the Class name and the Method name with a `#`
The resulting `methodId` is:
```
org.rapidoid.jdbc.JdbcClient#execute(Ljava/lang/String;[Ljava/lang/Object;)I
```
### MethodId for PHP
The `methodId` can be:
* the name of a PHP function
* the fully qualified name of a method following this format: `namespace\\ClassName::methodName`
Example: `Symfony\\Component\\HttpFoundation\\Request::getUser` for the `getUser()` method of the `Request` object provided by `Symfony`
Note: the `methodId` should be related to methods or functions that are part of the analysis scope. Because we recommended to not analyze code of frameworks at the same time that you scan your own source code, defining methods or functions from frameworks will have no effect.
This is linked to the fact that the SonarQube security engine needs to know the runtime type of each variable. The type can't be guessed when objects are created by frameworks' factories. Out of the box, the SonarQube security engine supports the main Symfony and Laravel types.
### MethodId for C#
If you want to declare the constructor `SqlCommand` belonging to the namespace `System.Data.SqlClient` as a sink, the `methodId` should be:
```
System.Data.SqlClient.SqlCommand.SqlCommand(string, System.Data.SqlClient.SqlConnection)
```
You simply need to provide the fully qualified name of the method or constructor plus the types of the arguments.
## Deactivate Core Configuration
You can disable the core configuration per language or per rule using the following:
```
sonar.security.[ConfigType].[RuleRepository].noDefaultConfig=[true|false]
sonar.security.[ConfigType].[RuleRepository].[RuleKey].noDefaultConfig=[true|false]
```
|
