跳到主要内容
版本：v0.21

PHP SDK 安全和状态

SDK 会读取不受信任的项目文件，并可在启用修复时更改它们。请将扫描视为一项特权操作，为其设置明确目标、受控存储，以及每项发现的审查路径。

进程全局配置​

Scanner 将其配置和当前报告保存在静态状态中。流式设置方法返回新的 Scanner 实例，但会修改共享的进程状态。

$first = new Scanner();
$second = $first->setPathScan('/srv/project-a');

// Both objects observe the same Scanner configuration.

在每个 PHP 进程中一次只运行一次扫描。对于后台作业、并发请求或租户隔离，请使用新的 CLI 进程。长期运行的工作进程必须在每次运行前应用完整配置，并避免重用先前作业的状态。

run() 会在扫描开始时重置报告。它不会重置更广泛的扫描器配置。不要依赖对象构造来恢复默认值。

文件操作​

交互运行和静默运行之间的默认提示行为不同。请在无人值守代码中明确选择一个操作：

$report = (new Scanner())
    ->setPathScan('/srv/app')
    ->setSilentMode()
    ->setAutoSkip()
    ->run();

对于任何会更改文件的操作，请调用 enableBackups() 并将 setPathBackups() 设置为目标之外的可写目录。请将隔离区、白名单、反混淆、报告、日志、持久化发现和检查点置于扫描项目之外，以免扫描器检查自身输出。

在启用自动清理、隔离或删除前：

  1. 针对应用程序的代表性副本运行仅报告扫描。
  2. 检查每次运行的 coverage、findings 和 diagnostics。
  3. 使用运行生产扫描的同一账户测试备份和恢复过程。
  4. 将目标路径限制在已批准的项目根目录中。

路径和权限​

从受信任配置传递绝对路径。在调用 setPathScan()、setPathReport() 或任何其他路径设置方法前，请规范化并授权从请求派生的路径。SDK 使用 Path::get() 规范化路径，但规范化不会强制执行应用程序的授权边界。

使用仅能读取目标和写入受控输出所需的最小文件系统权限运行扫描器。不要以能够扫描或删除预期部署根目录之外文件的账户运行 Web 请求。

网络行为和离线操作​

核心代码扫描使用嵌入定义。完整性验证和 Maltrail 域名定义可使用出站 HTTPS。扫描器将成功获取的远程数据存储在扫描目标之外的操作系统缓存中。

当环境阻止出站流量时，请捕获并保留报告诊断。更新失败时，缓存定义可能仍处于活动状态；报告会在 signature_indexes 中记录可用元数据。当不存在网络路由时，请不要假定诊断数组为空。

失败策略​

将 run() 返回的 false 视为操作错误。将不完整的覆盖范围、诊断和警告视为审查信号。请存储报告及其扫描时间戳、目标标识、来自 Scanner::getVersion() 的扫描器版本和任何外部作业标识符。

SDK 通过 getLastError() 提供捕获的错误消息。请将其记录在受保护的应用程序日志中。不要将目标路径、报告内容或原始错误文本暴露给不受信任的用户。