README

免责声明

此规则集基于由 https://github.com/FloeDesignTechnologies/phpcs-security-audit 存储库创建和维护的分支，该存储库由 Jonathan Marcil 创建和维护。包括对父项目的自定义，因为在创建此存储库时，父项目似乎不再积极维护。查看源代码历史记录以查看原始代码和分支后添加的内容。

关于

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/

指定扩展名很重要，例如，在 Drupal 中，PHP 代码位于 .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覆盖了所有命令行选项，所以如果你想使用它，请将其删除。命令行使用方法如下：

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基本配置中设置“CmsFramework”参数的出现次数，以便选择您新添加的实用程序。

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

同样，您还可以通过添加缓解函数来减少错误结果的数量。这些函数是作为安全控制（在函数中明确或通过副作用）来降低风险的。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 忽略大型的贡献模块（并为它们运行另一个 PHPCS 实例，仅用于 .info 解析）。例如，og 可能需要数小时，通常一切运行在 1-2 分钟内，有时在 5 分钟左右。你可以尝试使用 --parallel=8（或另一个数字）选项来尝试在支持的操作系统上加快速度。可能的解决方案是使用 phpcs --ignore=folder 来跳过扫描这些部分。
• 对于 Drupal 建议检查：如果一个模块有多个版本，并且存在一个较低的修复版本，则该模块可能是安全的，你仍然会收到错误或警告。请根据 Drupal 网站上的建议，保持所有内容更新到最新版本。