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 3.1.0 或更高版本的 PHP CodeSniffer。

最简单的安装方法是使用 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 ../../../

如果出于任何原因您需要更改此设置（应能直接使用）您将需要按照PHP_CodeSniffer文档中所述使用phpcs --config-set installed_paths。

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

这些发布包可在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基本配置中设置param "CmsFramework"的 occurrence 以选择您新添加的实用工具。

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

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

如果您实现了任何公共CMS/框架定制，请提交一个pull request以帮助项目成长。

测试

现在该工具支持使用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 忽略大贡献模块（并为仅对这些模块的 .info 解析运行另一个 PHPCS 实例）。例如，og 可能需要数小时，通常一切运行在 1-2 分钟内，有时在 5 分钟左右。你可以尝试使用 --parallel=8（或另一个数字）选项来尝试加快支持 OS 的速度。可能的解决方案是使用 phpcs --ignore=folder 跳过扫描这些部分。
• 对于 Drupal 咨询检查：如果一个模块有多个版本，如果存在一个较低的已修复版本，则该模块可能是安全的，你仍然会收到错误或警告。请按照 Drupal 网站上推荐的最新版本更新所有内容。