PHP静态分析的自定义规则：针对项目特有反模式或安全漏洞的检测
大家好！今天我们来聊聊一个非常重要的主题：PHP静态分析的自定义规则。静态分析作为一种在不实际执行代码的情况下发现错误和潜在问题的技术，在提升代码质量、增强安全性和减少维护成本方面发挥着关键作用。而自定义规则，则允许我们针对特定项目的反模式、安全漏洞或其他特定需求，进行更加精准和有效的检测。
1. 静态分析的基础与优势
首先，我们简单回顾一下静态分析的基本概念。静态分析工具会解析源代码，建立抽象语法树（AST），然后利用各种算法和规则来检查代码中的潜在问题。这些问题可能包括：
- 语法错误: 显而易见的语法错误，例如拼写错误、缺少分号等。
- 类型错误: PHP虽然是弱类型语言，但仍然存在类型相关的错误，例如尝试对非对象调用方法。
- 潜在的性能问题: 例如循环内的数据库查询、重复的计算等。
- 安全漏洞: 例如SQL注入、跨站脚本攻击（XSS）等。
- 代码风格违规: 例如命名不规范、代码冗余等。
- 逻辑错误: 例如死循环、条件判断错误等。
相比于动态测试（例如单元测试、集成测试），静态分析的优势在于：
- 覆盖范围广: 静态分析可以扫描整个代码库，而动态测试通常只能覆盖部分代码路径。
- 早期发现问题: 可以在开发早期发现问题，避免问题蔓延到生产环境。
- 无需运行代码: 不需要实际运行代码，因此可以发现一些难以通过动态测试触发的问题。
- 自动化: 可以自动化执行，集成到CI/CD流程中。
2. 为什么需要自定义规则？
虽然现有的静态分析工具（例如PHPStan、Psalm等）已经提供了丰富的内置规则，但仍然存在一些情况下，我们需要自定义规则：
- 项目特定的反模式: 每个项目都有其独特的代码风格、架构和业务逻辑。某些在通用情况下没有问题的代码，在特定项目中可能构成反模式，例如特定的数据处理方式、特定的业务流程等。
- 针对特定安全漏洞的检测: 一些安全漏洞可能与项目的特定实现方式有关，通用的安全扫描工具无法识别。例如，某个项目使用了特定的加密算法，但存在已知的漏洞。
- 强制执行团队规范: 确保团队成员遵循统一的代码规范，例如特定的命名约定、注释风格等。
- 提升代码可读性和可维护性: 通过自定义规则，可以强制执行一些提高代码可读性和可维护性的最佳实践。
3. 自定义规则的实现方式
不同的静态分析工具提供了不同的方式来实现自定义规则。这里我们以PHPStan为例，介绍如何创建自定义规则。
PHPStan使用两种主要的方式来定义规则：
- 基于类的规则 (Class Rules): 这种方式允许你访问更深层的代码结构，例如类、方法、属性等。适用于需要分析类之间的关系、方法调用、属性访问等情况。
- 基于节点的规则 (Node Rules): 这种方式允许你访问抽象语法树（AST）的节点。适用于需要分析代码的具体语法结构，例如表达式、语句、运算符等情况。
3.1 基于类的规则 (Class Rules) 的示例
假设我们的项目有一个特定的反模式：避免在控制器中使用 die() 或 exit() 函数。 我们希望创建一个规则来检测这种情况。
首先，我们需要创建一个类来实现 PHPStanRulesRule 接口。
<?php
namespace AppRules;
use PhpParserNode;
use PhpParserNodeStmtClassMethod;
use PHPStanAnalyserScope;
use PHPStanRulesRule;
class NoDieOrExitInControllerRule implements Rule
{
private string $controllerNamespace;
public function __construct(string $controllerNamespace)
{
$this->controllerNamespace = $controllerNamespace;
}
public function getNodeType(): string
{
return ClassMethod::class;
}
/**
* @param ClassMethod $node
* @param Scope $scope
* @return array<string>
*/
public function processNode(Node $node, Scope $scope): array
{
$classReflection = $scope->getClassReflection();
if ($classReflection === null) {
return [];
}
if (strpos($classReflection->getName(), $this->controllerNamespace) !== 0) {
return [];
}
foreach ($node->getStmts() as $stmt) {
if ($stmt instanceof PhpParserNodeStmtExpression) {
$expr = $stmt->expr;
if ($expr instanceof PhpParserNodeExprExit_) {
return ["Controller should not use die() or exit()"];
}
}
}
return [];
}
}代码解释:
NoDieOrExitInControllerRule类实现了PHPStanRulesRule接口。getNodeType()方法指定了该规则要检查的节点类型，这里是ClassMethod，表示类的方法。processNode()方法是规则的核心逻辑。它接收一个ClassMethod节点和一个Scope对象作为参数。$scope->getClassReflection()获取当前类的反射信息。- 我们检查当前类是否位于指定的控制器命名空间下。
- 遍历方法中的所有语句，如果遇到
PhpParserNodeExprExit_节点，则表示使用了die()或exit()函数，返回一个错误信息。
接下来，我们需要在 phpstan.neon 文件中注册这个规则。
includes:
- vendor/phpstan/phpstan/conf/bleedingEdge.neon
parameters:
controllerNamespace: AppHttpControllers
paths:
- app
excludePaths:
- app/Exceptions
- config
- database
- resources
- routes
- storage
rules:
- AppRulesNoDieOrExitInControllerRule:
controllerNamespace: '%controllerNamespace%'配置解释:
includes：包含 PHPStan 的默认配置。parameters：定义参数，controllerNamespace用于指定控制器所在的命名空间。paths：指定要分析的代码目录。rules：注册自定义规则，并传递参数。
现在，当我们运行 phpstan analyse 命令时，如果控制器中使用了 die() 或 exit() 函数，PHPStan 就会报告错误。
3.2 基于节点的规则 (Node Rules) 的示例
假设我们想检测项目中是否存在直接使用 $_GET、$_POST 或 $_REQUEST 超全局变量的情况。 这通常被认为是不安全的，因为没有经过适当的验证和过滤。
<?php
namespace AppRules;
use PhpParserNode;
use PhpParserNodeExprVariable;
use PHPStanAnalyserScope;
use PHPStanRulesRule;
class NoDirectSuperglobalsRule implements Rule
{
public function getNodeType(): string
{
return Variable::class;
}
/**
* @param Variable $node
* @param Scope $scope
* @return array<string>
*/
public function processNode(Node $node, Scope $scope): array
{
$superglobals = ['_GET', '_POST', '_REQUEST'];
if (in_array($node->name, $superglobals, true)) {
return ["Direct use of superglobal variable ${$node->name} is not allowed. Use a validated input source instead."];
}
return [];
}
}代码解释:
NoDirectSuperglobalsRule类实现了PHPStanRulesRule接口。getNodeType()方法指定了该规则要检查的节点类型，这里是Variable，表示变量。processNode()方法是规则的核心逻辑。它接收一个Variable节点和一个Scope对象作为参数。- 我们检查变量名是否是
_GET、_POST或_REQUEST。 - 如果是，则返回一个错误信息，建议使用经过验证的输入源。
同样，我们需要在 phpstan.neon 文件中注册这个规则。
includes:
- vendor/phpstan/phpstan/conf/bleedingEdge.neon
parameters:
paths:
- app
excludePaths:
- app/Exceptions
- config
- database
- resources
- routes
- storage
rules:
- AppRulesNoDirectSuperglobalsRule现在，当我们运行 phpstan analyse 命令时，如果代码中直接使用了 $_GET、$_POST 或 $_REQUEST 变量，PHPStan 就会报告错误。
4. 更复杂规则的构建
以上只是两个简单的示例。实际项目中，我们可能需要构建更复杂的规则，例如：
- 检测特定的函数调用方式: 例如，如果项目使用了自定义的日志记录函数，我们可以创建一个规则来确保所有日志消息都包含必要的上下文信息。
- 检测特定的数据结构使用: 例如，如果项目使用了特定的数据传输对象（DTO），我们可以创建一个规则来确保所有 DTO 属性都进行了类型声明。
- 检测特定的安全模式: 例如，可以检查是否使用了不安全的随机数生成器，或者是否正确地处理了用户上传的文件。
构建更复杂的规则通常需要对 PHPStan 的 API 和 AST 结构有更深入的了解。可以参考 PHPStan 的官方文档和示例代码，学习如何使用 Scope 对象获取类型信息、如何遍历 AST 节点、如何访问节点属性等。
5. 工具选择与配置
除了 PHPStan，还有其他一些 PHP 静态分析工具可供选择，例如 Psalm。选择合适的工具取决于项目的具体需求和团队的偏好。
在配置静态分析工具时，需要注意以下几点：
- 选择合适的规则集: 默认的规则集可能过于严格或过于宽松。需要根据项目的实际情况进行调整。
- 配置排除路径: 排除一些不需要分析的代码目录，例如 vendor 目录、测试目录等。
- 配置参数: 根据规则的要求，配置必要的参数。
- 集成到 CI/CD 流程: 将静态分析工具集成到 CI/CD 流程中，可以确保每次代码提交都会进行静态分析，及时发现问题。
6. 编写可维护的自定义规则
编写可维护的自定义规则至关重要，这能确保规则在项目演进过程中保持有效性和准确性。以下是一些建议：
- 清晰的命名: 使用清晰且具有描述性的命名，以便其他开发者理解规则的目的和作用。
- 详细的注释: 在代码中添加详细的注释，解释规则的逻辑和实现细节。
- 单元测试: 为自定义规则编写单元测试，确保规则能够正确地检测到目标问题。
- 模块化设计: 将复杂的规则分解为更小的、可重用的模块。
- 持续维护: 定期检查和更新自定义规则，以适应项目代码的变化和新的安全漏洞。
表格：PHP静态分析工具对比
| 特性 | PHPStan | Psalm |
|---|---|---|
| 类型检查 | 严格类型检查，支持泛型 | 严格类型检查，支持泛型 |
| 规则定制 | 灵活的规则定制机制，易于扩展 | 灵活的规则定制机制，易于扩展 |
| 性能 | 速度较快 | 速度较慢，但准确性更高 |
| 社区支持 | 活跃的社区，丰富的扩展库 | 活跃的社区，丰富的扩展库 |
| 易用性 | 配置简单，易于上手 | 配置相对复杂，需要一定的学习成本 |
| 错误报告 | 详细的错误报告，易于理解 | 详细的错误报告，易于理解 |
| 自动修复 | 支持自动修复一些简单的问题 | 支持自动修复一些简单的问题 |
| IDE 集成 | 支持多种 IDE，例如 PhpStorm, VS Code | 支持多种 IDE，例如 PhpStorm, VS Code |
| 适用场景 | 中小型项目，需要快速的分析速度 | 大型项目，需要更高的准确性 |
7. 结论
自定义规则是 PHP 静态分析的一个强大特性，可以帮助我们针对特定项目的反模式、安全漏洞或其他特定需求，进行更加精准和有效的检测。通过合理地使用自定义规则，我们可以显著提升代码质量、增强安全性和减少维护成本。
不断学习，持续改进
静态分析是一个不断发展的领域。我们需要不断学习新的技术和工具，持续改进我们的静态分析规则，以适应不断变化的项目需求和安全威胁。