You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[](https://github.com/FloeDesignTechnologies/phpcs-security-audit/releases)
[](https://github.com/FloeDesignTechnologies/phpcs-security-audit/commits/master)
@@ -24,7 +24,7 @@ The tool also checks for CVE issues and security advisories related to the CMS/f
24
24
25
25
The main reason for this project being an extension of PHP_CodeSniffer is to have easy integration into continuous integration systems. It also allows for finding security bugs that are not detected with some object oriented analysis (such as [PHPMD](http://phpmd.org/)).
26
26
27
-
phpcs-security-audit in its beginning was backed by Pheromone (later on named Floe design + technologies) and written by [Jonathan Marcil](https://twitter.com/jonathanmarcil).
27
+
phpcs-security-audit in its beginning was backed by Pheromone (later on named Floe Design + Technologies) and written by [Jonathan Marcil](https://twitter.com/jonathanmarcil).
28
28
29
29
30
30
@@ -34,7 +34,7 @@ Install
34
34
Requires [PHP CodeSniffer](http://pear.php.net/package/PHP_CodeSniffer/) version 3.1.0 or higher with PHP 5.4 or higher.
35
35
36
36
The easiest way to install is using [Composer](https://getcomposer.org/):
37
-
```bash
37
+
```
38
38
#WARNING: this currently doesn't work up until the v3 package is released
39
39
#See Contribute section bellow for git clone instruction
This will also install the [DealerDirect Composer PHPCS plugin](https://github.com/Dealerdirect/phpcodesniffer-composer-installer/) which will register the `Security` standard with PHP_CodeSniffer.
44
44
45
45
Now run:
46
-
```bash
46
+
```
47
47
./vendor/bin/phpcs -i
48
48
```
49
49
@@ -96,21 +96,51 @@ Customize
96
96
As with the normal PHP CodeSniffer rules, customization is provided in the XML files that are in the top folder of the project.
97
97
98
98
These global parameters are used in many rules:
99
-
* ParanoiaMode: set to 1 to add more checks. 0 for less.
100
-
* CmsFramework: set to the name of a folder containings rules and Utils.php (such as Drupal7, Symfony2).
99
+
* ParanoiaMode: set to 0 to reduce false positive. set to 1 (default) to be a lot more verbose.
100
+
* CmsFramework: set to the name of a folder containings rules and Utils.php (such as Drupal7) to target a specific framework.
101
101
102
-
They can be set in a custom ruleset `phpcs.xml[.dist]`XML file or from the command line for permanent config with `--config-set` or at runtime with `--runtime-set`. Note that the XML overrides all CLI options so remove it if you want to use it. The CLI usage is as follows:
103
-
```bash
102
+
They can be set in a custom ruleset XML file (such as `example_drupal7_ruleset.xml`), from the command line for permanent config with `--config-set` or at runtime with `--runtime-set`. Note that the XML overrides all CLI options so remove it if you want to use it. The CLI usage is as follows:
By default it should set PHPCS to look in the current folder:
119
+
```
120
+
PHP CodeSniffer Config installed_paths set to ../../../
121
+
```
122
+
123
+
If for any reason you need to change this (should work out of the box) you will need to `phpcs --config-set installed_paths` as explained in [PHP_CodeSniffer docs](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Configuration-Options#setting-the-installed-standard-paths).
112
124
113
-
If you want to fork and help or just do your own sniffs you can use the utilities provided by phpcs-security-audit rules in order to facilitate the process.
125
+
Master can contain breaking changes, so people are better off relying on releases for stable versions.
126
+
127
+
Those release packages are available [here on GitHub](releases) or on [Packagist](https://packagist.org/packages/pheromone/phpcs-security-audit).
128
+
129
+
Some guidelines if you want to create new rules::
130
+
* Ensure that `ParanoiaMode` controls how verbose your sniff is:
131
+
* If the sniff is only some of the time a valid security concern, run it when `paranoia=true` only.
132
+
* Warnings are generally issued instead of Errors for most-of-the-time concerns when `paranoia=false`.
133
+
* Errors are always generated when you are sure about user input being used.
* `paranoia=false` should solve false positive, otherwise warn on anything remotely suspicious.
136
+
* Include at least one test that triggers your sniff into `tests.php`.
137
+
* Keep the test as a one liner, it doesn't need to make sense.
138
+
* Don't forget to include your new sniff in the `example_base_ruleset.xml` and `example_drupal7_ruleset.xml` when it applies.
139
+
140
+
141
+
#### Specialize
142
+
143
+
If you want to support a specific code base or framework beyond XML configuration, you can use the utilities provided by phpcs-security-audit to facilitate the process.
114
144
115
145
Let's say you have a custom CMS function that is taking user input from `$_GET` when a function call to `get_param()` is done.
116
146
@@ -135,49 +165,28 @@ Don't forget to set the occurrence of param "CmsFramework" in your XML base conf
135
165
136
166
You are not required to do your own sniffs for the modification to be useful, since you are specifying what is a user input for other rules, but you could use the newly created directory to do so.
137
167
138
-
If you implement any public cms/framework customization please make a pull request to help the project grows.
168
+
In the same fashion, you can also reduce the number of false positive by adding mitigation functions. Those are functions that serve as security controls (either explicitly in the function or by a side effect) that lower the risks. A good example is `htmlentities` for XSS. See `is_XSS_mitigation` function in `Drupal7/Utils.php`.
139
169
170
+
If you implement any public CMS/Framework customization please make a pull request to help the project grows.
140
171
141
-
Contribute
142
-
----------
143
-
It is possible to install with a `git clone` and play with it in the same folder.
By default it should set PHPCS to look in the current folder:
150
-
```
151
-
PHP CodeSniffer Config installed_paths set to ../../../
152
-
```
174
+
The tool now support unit testing with `composer test`.
153
175
154
-
If for any reason you need to change this (should work out of the box) you will need to `phpcs --config-set installed_paths` as explained in [PHP_CodeSniffer docs](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Configuration-Options#setting-the-installed-standard-paths).
155
-
156
-
Master can contain breaking changes, so people are better off relying on releases for stable versions.
157
-
158
-
Those release packages are available [here on GitHub](releases) or on [Packagist](https://packagist.org/packages/pheromone/phpcs-security-audit).
176
+
To test for a specific sniff, use `composer test -- --filter RULENAME` (without the `Sniff` part).
159
177
160
-
Some guidelines if you want to create new rules::
161
-
* Ensure that `ParanoiaMode` controls how verbose your sniff is:
162
-
* If the sniff is only some of the time a valid security concern, run it when `paranoia=true` only.
163
-
* Warnings are generally issued instead of Errors for most-of-the-time concerns when `paranoia=false`.
164
-
* Errors are always generated when you are sure about user input being used.
* `paranoia=false` should solve false positive, otherwise warn on anything remotely suspicious.
167
-
* Include at least one test that triggers your sniff into `tests.php`.
168
-
* Keep the test as a one liner, it doesn't need to make sense.
169
-
* Don't forget to include your new sniff in the `example_base_ruleset.xml` and `example_drupal7_ruleset.xml` when it applies.
178
+
To create a test, create a folder with RULENAME. Inside, have a `RULENAMEUnitTest.inc` file for the code to be scanned and `RULENAMEUnitTest.php` file for the PHPCS validation of findings. For the rule to support a given CMS/Framework, it needs to have a inc file with the following: `RULENAMEUnitTest.CMSFRAMEWORK.inc`. See `Security/Tests/BadFunctions` for a complete example.
170
179
171
180
172
181
Annoyances
173
182
----------
174
183
175
184
As with any security tool, this one comes with it's share of annoyance. At first a focus on finding vulnerabilities will be done, but later it is planned to have a phase where efforts will be towards reducing annoyances, in particular with the number of false positives.
176
185
177
-
* It's a generator of false positives. This can actually help you learn what are the weak functions in PHP. Paranoia mode will fix that by doing a major cut-off on warnings when set to 0.
186
+
* It's a generator of false positives created for people doing secure code reviews. It can help you learn what are the weak functions in PHP but can be counter productive in CI/CD environments. Set `ParanoiaMode` to `0` for a major cut-off on warnings.
178
187
* This tool was created around 10 years ago. Some of its parts might look outdated, and support for old PHP code will still be present. The reality is that many code base scanned with it might be as old as the tool.
179
188
* It's slow. On big Drupal modules and core it can take too much time (and RAM, reconfigure `cli/php.ini` to use 512M if needed) to run. Not sure if it's because of bugs in PHPCS or this set of rules, but will be investigated last. Meanwhile you can configure PHPCS to ignore big contrib modules (and run another instance of PHPCS for `.info` parsing only for them). An example is og taking hours, usually everything runs under 1-2 minutes and sometimes around 5 minute. You can try using the `--parallel=8` (or another number) option to try and speed things up on supported OSes. Possible work-around is to use `phpcs --ignore=folder` to skip scanning of those parts.
180
-
* For Drupal advisories checking: a module with multiple versions might be secure if a lesser fixed version exists and you'll still get the error or warning. Keep everything updated at latest as recommended on Drupal's website.
189
+
* For Drupal advisories checking: a module with multiple versions might be secure if a lesser fixed version exists and you'll still get the error or warning. Keep everything updated on latest as recommended on Drupal's website.
0 commit comments