README

关于

phpcs-security-audit 是一组 PHP_CodeSniffer 规则，用于查找 PHP 代码中与安全相关的漏洞和弱点。

它目前包含核心 PHP 规则以及 Drupal 7 特定规则。

该工具还会检查与 CMS/框架相关的 CVE 问题和安全公告。这使您可以在静态代码分析期间跟踪组件的版本。

该项目作为 PHP_CodeSniffer 扩展的主要原因是能够轻松集成到持续集成系统中。它还允许发现一些面向对象分析（如 PHPMD）无法检测到的安全漏洞。

phpcs-security-audit 最初由 Pheromone（后来更名为 Floe Design + Technologies）支持，并由 Jonathan Marcil 编写。

安装

需要 PHP 5.4 或更高版本的 PHP CodeSniffer 3.1.0 或更高版本。

最简单的安装方法是使用 Composer

#WARNING: this currently doesn't work up until the v3 package is released
#See Contribute section bellow for git clone instruction
composer require --dev pheromone/phpcs-security-audit

这将安装 DealerDirect Composer PHPCS 插件，该插件将注册 Security 标准与 PHP_CodeSniffer。

现在运行

./vendor/bin/phpcs -i

如果一切顺利，您应该在已安装的编码标准列表中看到 Security。

如果您想将其与 Jenkins 集成，请访问 http://jenkins-php.org/ 获取大量帮助。

用法

只需将标准设置为 Security 或指向任何 XML 规则集文件，以及要扫描的文件夹。

phpcs --extensions=php,inc,lib,module,info --standard=./vendor/pheromone/phpcs-security-audit/example_base_ruleset.xml /your/php/files/

指定扩展很重要，例如，PHP 代码在 Drupal 中的 .module 文件中。

要快速查看输出示例，可以使用提供的 tests.php 文件。

$ phpcs --extensions=php,inc,lib,module,info --standard=./vendor/pheromone/phpcs-security-audit/example_base_ruleset.xml ./vendor/pheromone/phpcs-security-audit/tests.php

FILE: tests.php
--------------------------------------------------------------------------------
FOUND 18 ERRORS AND 36 WARNINGS AFFECTING 44 LINES
--------------------------------------------------------------------------------

  6 | WARNING | Possible XSS detected with . on echo
  6 | ERROR   | Easy XSS detected because of direct user input with $_POST on echo
  9 | WARNING | Usage of preg_replace with /e modifier is not recommended.
 10 | WARNING | Usage of preg_replace with /e modifier is not recommended.
 10 | ERROR   | User input and /e modifier found in preg_replace, remote code execution possible.
 11 | ERROR   | User input found in preg_replace, /e modifier could be used for malicious intent.
   ...

Drupal 注意事项

对于 Drupal AdvisoriesContrib，您需要将 /etc/php5/cli/php.ini 修改为

short_open_tag = On

以消除 "在此文件中未找到 PHP 代码" 的警告。

请注意，仅支持从 drupal.org 下载的 Drupal 模块。如果您使用的是来自其他来源的 contrib 模块，则版本检查可能不会正常工作，并生成警告。

自定义

与正常的 PHP CodeSniffer 规则一样，自定义在项目顶层文件夹中的 XML 文件中提供。

这些全局参数在许多规则中使用

• ParanoiaMode: 将其设置为 0 以减少误报。设置为 1（默认）以提供更多信息。
• CmsFramework: 设置为包含规则和 Utils.php 的文件夹名称（例如 Drupal7），以针对特定框架。

可以在自定义的XML规则集文件（如example_drupal7_ruleset.xml）中设置，从命令行使用--config-set进行永久配置，或者在运行时使用--runtime-set。请注意，XML会覆盖所有CLI选项，所以如果你想使用它，请先删除它。CLI使用方法如下：

phpcs --runtime-set ParanoiaMode 0 --extensions=php --standard=./vendor/pheromone/phpcs-security-audit/example_base_ruleset.xml tests.php

对于某些规则，您可以通过XML文件内的forceParanoia参数强制打开或关闭恐慌模式。

贡献

可以使用git clone安装它，并在同一文件夹中试用。

composer install
./vendor/bin/phpcs --standard=example_base_ruleset.xml --extensions=php tests.php

默认情况下，它应该将PHPCS设置为在当前文件夹中查找。

PHP CodeSniffer Config installed_paths set to ../../../

如果您需要更改此设置（应能正常工作），则需要使用phpcs --config-set installed_paths进行设置，具体请参考PHP_CodeSniffer文档。

主版本可能包含破坏性更改，因此人们最好依靠发行版来获取稳定版本。

这些发行版可以在GitHub上或Packagist上找到。

如果您想创建新的规则，以下是一些指南：

• 请确保ParanoiaMode控制您的嗅探器的详细程度。
  • 如果嗅探器只在某些情况下是有效的安全担忧，请仅在paranoia=true时运行它。
  • 当paranoia=false时，通常会对大多数时间的安全担忧发出警告而不是错误。
  • 当您确信用户输入被使用时，始终会生成错误。
• 相对于错误阴性（缺失的结果），更倾向于错误阳性（令人烦恼的结果）。
  • paranoia=false应解决错误阳性，否则对任何可疑的任何内容发出警告。
• 至少在一个触发您的嗅探器的测试中包含到tests.php中。
  • 将测试保持为一行，它不需要有意义。
• 不要忘记在适用的情况下将您的新嗅探器包含在example_base_ruleset.xml和example_drupal7_ruleset.xml中。

专业化

如果您想支持XML配置之外的特定代码库或框架，可以使用phpcs-security-audit提供的工具来简化过程。

假设您有一个自定义CMS函数，当调用get_param()函数时，它会从$_GET接收用户输入。

您需要在Sniffs/中创建一个新文件夹，该文件夹将是您框架的名称。然后您需要创建一个名为Utils.php的文件，该文件将是实际专门化通用嗅探器的函数。为了指导您，只需从另一个文件夹（如Drupal7/）复制该文件即可。

您将想要更改的主要函数是is_direct_user_input，当您看到get_param()时，您将返回TRUE。

	public static function is_direct_user_input($var) {
		if (parent::is_direct_user_input($var)) {
			return TRUE;
		} else {
			if ($var == 'get_param') {
				return TRUE;
			}
		}
		return FALSE;
	}

不要忘记在您的XML基本配置中设置参数“CmsFramework”的出现次数，以便选择您新添加的工具。

您不需要自己编写嗅探器以使修改有用，因为您正在指定其他规则的用户输入，但您可以使用新创建的目录来这样做。

同样，您还可以通过添加缓解函数来减少错误阳性的数量。这些函数作为安全控制措施（在函数中明确或在副作用中）降低风险。一个很好的例子是htmlentities用于XSS。请参阅Drupal7/Utils.php中的is_XSS_mitigation函数。

如果您实现了任何公共CMS/框架自定义，请提交一个拉取请求以帮助项目成长。

测试

该工具现在支持使用composer test进行单元测试。

要测试特定嗅探器，请使用composer test -- --filter RULENAME（不要包含Sniff部分）。

要创建一个测试，创建一个名为RULENAME的文件夹。在文件夹内，创建一个用于扫描的代码的RULENAMEUnitTest.inc文件和一个用于PHPCS验证发现的RULENAMEUnitTest.php文件。为了让规则支持特定的CMS/框架，它需要一个包含以下内容的inc文件：RULENAMEUnitTest.CMSFRAMEWORK.inc。有关完整示例，请参阅Security/Tests/BadFunctions。

烦恼

与任何安全工具一样，这个工具也有它自己的烦恼。最初将专注于发现漏洞，但后来计划有一个阶段将努力减少烦恼，特别是减少误报的数量。

• 这是为进行安全代码审查的人创建的误报生成器。它可以帮助你了解PHP中哪些函数是弱项，但在CI/CD环境中可能会适得其反。将ParanoiaMode设置为0以大幅减少警告。
• 这个工具大约10年前创建的。其中一些部分可能看起来过时，并且仍然支持旧版本的PHP代码。现实情况是，使用它扫描的许多代码库可能和这个工具一样古老。
• 它很慢。在大型Drupal模块和核心中运行可能需要太多时间（以及RAM，如果需要，请重新配置cli/php.ini以使用512M）。不确定是因为PHPCS中的错误还是这组规则，但最后会进行调查。同时，您可以配置PHPCS以忽略大型贡献模块（并为这些模块运行另一个PHPCS实例，仅用于.info解析）。例如，og可能需要数小时，通常一切都在1-2分钟内运行，有时在5分钟内。您可以尝试使用--parallel=8（或另一个数字）选项来尝试在支持的操作系统上加快速度。可能的解决方案是使用phpcs --ignore=folder来跳过扫描这些部分。
• 对于Drupal警告检查：如果存在一个较低版本的修复版本，则具有多个版本的模块可能是安全的，您仍然会收到错误或警告。请按照Drupal网站上的推荐将所有内容更新到最新版本。