trafficinc/fireline
GitHub: trafficinc/fireline
Fireline 是一款运行在 PHP 应用层的轻量级 Web 应用防火墙，用于在请求被应用处理前拦截常见的恶意流量。
Stars: 2 | Forks: 0
# Fireline
Fireline 是一个低配置的 PHP Web 应用防火墙请求拦截器。它被设计为在应用程序请求之前加载，并在应用程序处理之前拦截明显的恶意流量。
Fireline 目前会检查：
- 客户端 IP 地址
- 查询字符串
- User agent
- GET、POST、cookie、header、JSON 以及选定的原始 body 值
- SQL 注入、XSS、查询滥用和机器人模式
## 何时使用 Fireline
Fireline 是一个轻量级的**应用层防火墙**，在您的 PHP 应用程序的 **OSI 模型第 7 层**运行。
它适用于：
* 保护旧版或自定义的 PHP 应用程序
* 在没有服务器级防火墙访问权限的共享主机上增加安全性
* 过滤针对表单、API、登录页面和管理面板的恶意请求
* 拦截常见的 SQL 注入、XSS、扫描器、机器人和格式错误请求的模式
* 跨多个 PHP 应用程序提供共享的安全层
* 在旧的应用程序代码进行安全加固或现代化改造期间提供临时保护
当 Cloudflare WAF、ModSecurity 或其他服务器级防火墙不可用时，Fireline 尤为有用。它应该作为额外的防御层使用，而不能替代预处理语句（prepared statements）、验证、输出转义、身份验证、CSRF 防护、更新以及安全的应用程序设计。
## 要求
- PHP 7.1 或更高版本以实现运行时兼容性
- PHP 8.1 或更高版本以使用内置的开发工具
- `ext-json`
- 可写的 `storage/logs/fireline.log`
使用全局安装的 Composer 安装依赖项：
```
composer install
```
## 安装方法
Fireline 应在应用程序处理请求之前加载。首选的部署方式是：
- 在主机允许的情况下，将 `fireline` 包保留在公共 Web 根目录之外。
- 仅在公共 Web 根目录中放置一个小的引导文件。
- 配置 PHP 使用 `auto_prepend_file`，或在应用程序前端控制器的顶部调用 Fireline。
- 确保 `storage/logs`、`storage/replay` 和 `storage/metrics` 可由 PHP 进程写入。
示例布局：
```
project/
fireline/
public/
fireline.php
```
在部署前使用 Composer 安装依赖项：
```
composer install --no-dev --optimize-autoloader
```
如果您的布局不同，请将 [config-webroot/fireline.php](config-webroot/fireline.php) 复制到 Web 根目录并更新其包含路径。
### 共享主机
对于 cPanel、Plesk 和类似的共享主机，请在本地或主机终端运行 Composer 后，上传该包和 `vendor/` 目录。
示例布局：
```
/home/account/fireline/
/home/account/public_html/fireline.php
/home/account/public_html/index.php
```
对于 `public_html` 中的 `.user.ini`：
```
auto_prepend_file = /home/account/public_html/fireline.php
```
对于 `.htaccess` 或 Apache PHP 配置：
```
php_value auto_prepend_file "/home/account/public_html/fireline.php"
```
某些共享主机会将 `.user.ini` 的更改缓存几分钟。如果请求没有立即被检查，请等待 PHP-FPM 重新加载设置，或使用主机控制面板重启 PHP。
如果主机不允许在 `public_html` 之外存放文件，请将该包放在受保护的目录中，并阻止对其的直接 Web 访问。尽可能将回放（replay）、指标和日志保留在公共对外服务的路径之外。
### VPS 或云 VM
在 VM 上，将 Fireline 放在站点代码旁边，并配置 PHP-FPM 或 Apache 预先加载引导文件。
示例布局：
```
/var/www/fireline/
/var/www/example.com/public/fireline.php
/var/www/example.com/public/index.php
```
Apache 虚拟主机：
```
php_admin_value auto_prepend_file "/var/www/example.com/public/fireline.php"
```
PHP-FPM 池：
```
php_admin_value[auto_prepend_file] = /var/www/example.com/public/fireline.php
```
Nginx 本身不设置 PHP ini 值。请使用 PHP-FPM 池、启用的按目录 `.user.ini`，或者从应用程序的前端控制器调用 Fireline。
### 容器
在 Docker 或其他容器构建中，在镜像构建期间安装 Fireline，并将日志、回放文件和指标写入挂载的卷。
```
COPY fireline /app/fireline
RUN cd /app/fireline && composer install --no-dev --optimize-autoloader
COPY public/fireline.php /app/public/fireline.php
```
PHP ini：
```
auto_prepend_file = /app/public/fireline.php
```
如果您希望日志、指标或回放数据在容器替换后依然存在，请挂载持久化存储：
```
/app/fireline/storage/logs
/app/fireline/storage/replay
/app/fireline/storage/metrics
```
### 反向代理和负载均衡器
当应用程序位于 Cloudflare、AWS/GCP/Azure 负载均衡器、Nginx、HAProxy 或其他受信任的代理之后时，请配置 `trusted_proxies`。除非 `REMOTE_ADDR` 是受信任的，否则 Fireline 会忽略 `X-Forwarded-For`。
```
'trusted_proxies' => [
'10.0.0.0/8',
'172.16.0.0/12',
'192.168.0.0/16',
],
```
对于诸如 Cloudflare 之类的公共代理网络，请使用提供商发布的 IP 范围并保持更新。在面向互联网的源站上，不要信任所有转发的 IP header。
## Web 使用方式
Web 根目录下的 `fireline.php` 文件会加载并运行 Fireline：
```
run();
```
如果 Fireline 检测到需要拦截的请求，它会记录该事件，发送：
```
HTTP/1.1 403 Forbidden
```
并在应用程序继续运行之前退出。
## 框架集成
### Laravel 中间件
创建一个在应用程序控制器之前运行的中间件：
```
inspectCurrentRequest();
if ($decision->shouldBlock()) {
ResponseHandler::block($decision);
exit;
}
return $next($request);
}
}
```
尽早将其注册到 `web` 中间件组中，或作为全局中间件注册。如果您想进行 Laravel 原生的配置加载，请将 Fireline 设置发布到 `config/fireline.php` 中。
### Symfony Kernel 请求监听器
注册一个具有高优先级的 `kernel.request` 监听器，使其在控制器之前运行：
```
*/
private $config;
public function __construct(array $config = [])
{
$this->config = $config;
}
public function onKernelRequest(RequestEvent $event): void
{
if (method_exists($event, 'isMainRequest') && !$event->isMainRequest()) {
return;
}
$decision = (new WafEngine($this->config))->inspectCurrentRequest();
if ($decision->shouldBlock()) {
$event->setResponse(new Response('Blocked', 403));
}
}
}
```
`config/services.yaml`：
```
services:
App\EventListener\FirelineRequestListener:
arguments:
$config: '%fireline.config%'
tags:
- { name: kernel.event_listener, event: kernel.request, method: onKernelRequest, priority: 512 }
```
为了获得尽可能早的覆盖范围，依然可以在 Symfony 前面使用 `auto_prepend_file`。
### WordPress 引导或插件
最早的 WordPress 防护依然是使用 `auto_prepend_file`，因为它会在 WordPress 加载之前运行。为了便于管理，可以创建一个小插件：
```
run();
}, 0);
```
将其放置在：
```
wp-content/plugins/fireline-waf/fireline-waf.php
```
在 WordPress 中激活它。当您需要 Fireline 在任何 WordPress 引导代码运行之前检查请求时，请改用 `auto_prepend_file`。
### 通用前端控制器应用
对于 Slim、自定义 MVC 应用和其他前端控制器项目，请在启动应用程序容器或路由器之前，在 `public/index.php` 的顶部调用 Fireline：
```
run();
require dirname(__DIR__) . '/app/bootstrap.php';
$app->run();
```
这不如 `auto_prepend_file` 自动化，但在主机不允许更改 PHP ini 时非常有效。
## 生产环境检查清单
在生产流量上启用 Fireline 之前：
- 运行 `composer install --no-dev --optimize-autoloader`。
- 仅在需要更改默认值时，将 `config.php.example` 复制为 `config.php`。
- 验证 PHP 用户对 `storage/logs`、`storage/replay` 和 `storage/metrics` 的权限。
- 在 Fireline 目录下运行 `php fire.php config:check`。
- 初始时将 `paranoia_level` 设置为 `medium`，或者对于对误报容忍度极低的应用程序设置为 `low`。
- 在依赖转发的客户端 IP header 之前配置 `trusted_proxies`。
- 在调优期间启用 `replay_enabled`，然后保护或轮换回放文件，因为它们包含规范化的请求数据。
- 当需要跨请求调优数据时，设置 `metrics_path`。
- 部署后，测试一个正常请求和一个明显的被拦截请求，例如 `?q=javascript:alert(1)`。
## 配置
Fireline 无需配置文件即可工作。要覆盖默认设置，请将 [config.php.example](config.php.example) 复制到 Fireline 目录中的 `config.php`。
```
false,
'strict_mode' => false,
'ip_by_country' => false,
'whitelist' => false,
'trusted_proxies' => [],
'max_fields' => 200,
'max_headers' => 100,
'max_header_length' => 8192,
'max_body_length' => 1048576,
'max_value_length' => 8192,
'inspect_json' => true,
'inspect_headers' => true,
'inspect_raw_body' => true,
'metrics_path' => null,
'score_threshold' => null,
'regex_threshold' => null,
'safe_cache_threshold' => null,
];
```
配置选项：
- `bypass_firewall`：设置为 `true` 时禁用所有过滤。
- `strict_mode`：在查询过滤之前规范化查询字符串。
- `ip_by_country`：使用 `src/GeoLite2-Country.mmdb` 和 [src/Compares/ip_block_by_country.php](src/Compares/ip_block_by_country.php) 启用国家拦截。
- `whitelist`：使用 [src/Compares/ips_white_list.php](src/Compares/ips_white_list.php) 启用 IP 白名单模式。启用后，将不再使用 IP 黑名单模式。
- `trusted_proxies`：允许提供 `X-Forwarded-For` 的代理 IP 或 CIDR 范围。
- `max_fields`：拦截请求前允许提取的最大字段数。
- `max_headers`：拦截请求前允许的最大 HTTP header 数量。
- `max_header_length`：单个 header 值允许的最大字节数。
- `max_body_length`：拦截请求前允许的最大原始请求 body 字节数。
- `max_value_length`：每个请求值检查的最大字符数。
- `inspect_json`：检查 `application/json` 请求的 JSON 请求 body。
- `inspect_headers`：检查 HTTP header，但不包括 `Cookie`，因为 cookie 会被单独检查。
- `inspect_raw_body`：检查非表单和非 JSON 内容类型的原始 body。
- 分段上传（Multipart uploads）通过文件名、客户端 MIME 类型、大小和上传错误等元数据字段进行检查。Fireline 不会读取上传的文件内容，也不会记录临时上传路径。
- `paranoia_level`：检测策略。支持的值为 `low`、`medium`、`high` 和 `strict`。
- `replay_enabled`：设置为 `true` 时写入规范化的回放事件。
- `replay_path`：JSON-lines 回放文件路径。
- `metrics_path`：用于持久化聚合指标的可选 JSON 文件路径。
- `score_threshold`：拦截请求所需的字段分数。
- `regex_threshold`：运行条件 regex 规则前所需的分数。
- `safe_cache_threshold`：有资格进行短期安全指纹缓存的最大分数。
## 架构
当前引擎遵循分阶段的检查流水线：
1. 单独提取请求字段。
2. 拒绝超出配置限制或包含格式错误编码的请求。
3. 将每个字段规范化一次。
4. 构建路由/字段/形状指纹。
5. 检查短暂的安全和威胁缓存。
6. 运行低成本的预过滤器和启发式算法。
7. 运行关键字扫描。
8. 仅在出现可疑信号后才运行 regex 规则。
9. 评分并做出决定。
10. 记录并拦截，或者允许应用程序继续。
公共 `FireLine` 类仍保留用于现有的集成，但内部会委托给 `Fireline\Engine\WafEngine`。
### 旧版兼容性
历史遗留的 `Filters\*` 和 `Handlers\*` 类仍可用于较旧的集成。它们是兼容性包装器；新的集成应该使用 `FireLine` 或 `Fireline\Engine\WafEngine`。用于 SQL、XSS、查询、机器人和 IP 检查的兼容性过滤器现在委托给分阶段引擎或保护类，因此行为与当前的请求流水线保持一致。
受信任的代理示例：
```
'trusted_proxies' => [
'127.0.0.1',
'10.0.0.0/8',
],
```
除非站点位于您控制的反向代理或负载均衡器之后，否则请将 `trusted_proxies` 留空。
## 路由模型
可选的路由模型位于 [config/routes.php](config/routes.php) 中。当已知路由接收到与预期类型或长度不匹配的字段形状时，它们会增加异常分数。
```
return [
'/login' => [
'post.username' => [
'type' => 'alnum',
'max_length' => 64,
'allowed_chars' => 'alnum',
'denied_tokens' => ['union', 'select', 'sleep', 'script'],
],
'post.password' => [
'type' => 'opaque',
'max_length' => 256,
],
'get.q' => [
'type' => 'text',
'max_length' => 256,
'allowed_chars' => 'free_text',
],
],
];
```
支持的字段类型有 `alpha`、`alnum`、`int`、`integer`、`numeric`、`email`、`slug`、`url`、`text` 和 `opaque`。
路由字段可以定义：
- `min_length`、`max_length` 和 `avg_length`
- `allowed_chars`：`alpha`、`alnum`、`slug`、`free_text` 或有界 regex
- `shape`：来自 `ShapeModel::shape()` 的规范化形状
- `required_tokens`：预期会出现的 token
- `denied_tokens`：应增加异常分数的特定于路由的 token
路由模型是评分信号，而不是独立的拦截规则。
## 偏执级别
偏执级别提供了易于采用的默认设置：
- `low`：针对高误报敏感性的保守拦截。
- `medium`：默认的平衡模式。
- `high`：更激进的评分和更早的 regex 检查。
- `strict`：适用于可以容忍更多拦截的应用程序的激进模式。
显式的 `score_threshold`、`regex_threshold` 和 `safe_cache_threshold` 值将覆盖级别默认值。
规则也会声明一个 `paranoia` 级别。Fireline 仅运行等于或低于配置级别的规则，因此 `low` 模式使用置信度最高的规则，而 `strict` 模式包含每一条规则。
## 可解释性
每一个决定都可以生成面向开发者的解释：
```
$decision = $waf->inspectCurrentRequest();
echo $decision->explain(25);
```
示例：
```
Blocked:
- rule:SQL_BOOLEAN_OPERATOR (+6)
- encoding_heuristics (+4)
- route_model (+7)
Final Score: 17
Threshold: 15
```
当结构化数据更容易显示或存储时，请使用 `$decision->explanation()`。
## 回放
回放模式将规范化的请求字段、匹配的规则、分数和决定存储为 JSON 行。诸如密码、token、API key、机密和授权值等敏感字段在写入回放数据之前会被脱敏处理。在配置中启用它：
```
'replay_enabled' => true,
'replay_path' => __DIR__ . '/storage/replay/traffic.ndjson',
```
在规则或评分更改后回放存储的流量：
```
use Fireline\Replay\ReplayRunner;
$result = (new ReplayRunner())->replay(__DIR__ . '/storage/replay/traffic.ndjson');
foreach ($result['regressions'] as $regression) {
print_r($regression);
}
```
回放使用存储的规范化字段，并使用当前引擎对它们重新评分，这有助于在部署前捕获新的拦截、漏报、分数增加和误报回归。回放元数据包括阈值、偏执级别、选定的配置值和活动的规则集指纹，以便可以区分配置更改和规则更改当元数据不同时，回放输出会报告更改的元数据组，例如 `thresholds`、`config` 或 `rules`。无效的回放行会被单独计数，因此损坏的捕获文件是可见的。回放摘要还包含决定更改计数和分数增量聚合，因此即使流量未超过拦截阈值，广泛的调优偏差也是可见的。
同样的回放检查也可以从 CLI 中使用：
```
php fire.php replay:run storage/replay/traffic.ndjson
```
使用 `--ci` 在发现回放回归时返回非零退出代码：
```
php fire.php replay:run storage/replay/traffic.ndjson --ci
```
当自动化需要完整的回放结果时使用 `--json`：
```
php fire.php replay:run storage/replay/traffic.ndjson --json
```
为 CI 产物或规则审查说明编写 JSON 回放报告：
```
php fire.php replay:run storage/replay/traffic.ndjson --output storage/replay/report.json
php fire.php replay:run storage/replay/traffic.ndjson --output storage/replay/report.json --force
```
除非提供了 `--force`，否则不会覆盖现有的报告文件。
从回放数据构建路由模型候选：
```
php fire.php baseline:build storage/replay/traffic.ndjson 10
php fire.php baseline:build storage/replay/traffic.ndjson 10 --json
php fire.php baseline:build storage/replay/traffic.ndjson 10 --json --report
php fire.php baseline:export storage/replay/traffic.ndjson 10 storage/models/routes.generated.php
php fire.php baseline:export storage/replay/traffic.ndjson 10 storage/models/routes.generated.php --dry-run
php fire.php baseline:export storage/replay/traffic.ndjson 10 storage/models/routes.generated.php --force
```
默认情况下，`baseline:build` 会打印一个 PHP `config/routes.php` 片段供审查。当自动化需要直接获取候选模型时使用 `--json`，或者当它还需要回放读取计数和无效行计数时使用 `--json --report`。
使用 `baseline:export` 将审查后的候选模型写入目标 PHP 文件。添加 `--dry-run` 以预览目标位置和回放计数而不进行写入。除非提供了 `--force`，否则不会覆盖现有文件。
验证配置、可写路径和规则元数据：
```
php fire.php config:check
```
## 规则文件
分阶段的 WAF 规则集存储在 [config/rules.php](config/rules.php) 中。每条规则包括：
- `id`：在决定、回放和指标中使用的稳定规则标识符。
- `type`：用于 Aho-Corasick 扫描的 `keyword` 或用于条件 regex 确认的 `regex`。
- `pattern`：关键字文本或有界正则表达式。
- `score`：对字段分数的贡献。
- `category`：检测家族，如 `sqli`、`xss`、`lfi`、`rfi`、`webshell`、`scanner`、`php_injection`、`protocol` 或 `upload`。
- `paranoia`：规则活跃的最低策略：`low`、`medium`、`high` 或 `strict`。
- `explanation`、`examples` 和 `false_positives`：用于调优的审查上下文。
关键字规则首先通过 Aho-Corasick 扫描器运行。Regex 规则仅在字段已经可疑且存在它们所需的 token 之后运行。
在编辑规则集之后验证规则元数据和 regex 语法：
```
php fire.php rules:validate
php fire.php rules:validate config/rules.php --json
```
旧版比较列表保留在 [src/Compares](src/Compares) 中，用于兼容性包装器和保护列表：
- `bots.php`：`BotGuard` 使用的被拦截的 user agent。
- `ips.php`：`IpGuard` 使用的被拦截的 IP 或部分 IP 字符串。
- `ips_white_list.php`：启用白名单模式时允许的 IP 和 CIDR 范围。
- `ip_block_by_country.php`：启用国家拦截时被拦截的国家 ISO 代码。
历史上的 SQL、XSS 和查询比较文件已被移除。兼容性过滤器现在将检测委托给分阶段引擎，因此新的规则工作应该在 `config/rules.php` 中进行。
## 日志记录
被拦截的请求会记录到：
```
storage/logs/fireline.log
```
日志以 JSON 行的形式写入。每个被拦截的请求都是一个 JSON 对象：
```
{"level":"warn","event":"fireline.blocked_request","timestamp":"2026-05-13T12:00:00-04:00","unix_time":1778688000,"remote_addr":"203.0.113.10","method":"GET","route":"/products","request_uri":"/products?id=1","filter":"get","field":"get.id","score":30,"matched_score":30,"reason":"field_score_threshold","value":"1 union select password from users","normalized":"1 union select password from users","user_agent":"Mozilla/5.0","referer":"https://example.com/"}
```
事件字段：
- `level`：对于被拦截的请求始终为 `warn`。
- `event`：始终为 `fireline.blocked_request`。
- `timestamp`：ISO-8601 时间戳。
- `unix_time`：Unix 时间戳。
- `remote_addr`：来自 PHP 的 `REMOTE_ADDR`。
- `method`：HTTP 请求方法。
- `route`：解析的请求路径。
- `request_uri`：来自 PHP 的请求 URI。
- `filter`：拦截请求的字段来源，如 `get`、`post`、`cookie`、`header`、`json`、`raw`、`ip` 或 `bot`。
- `field`：超过阈值的被检查的确切字段。
- `score`：总决定分数。
- `matched_score`：确切拦截字段的分数。
- `reason`：决定原因。
- `value`：经过清理和脱敏后的匹配值。
- `normalized`：经过清理和脱敏后的规范化匹配值。
- `user_agent`：来自 PHP 的 user agent。
- `referer`：来自 PHP 的 referer。
攻击者控制的字段在记录之前会进行清理：
- 控制字符被替换为空格。
- 诸如 `password`、`token`、`api_key`、`secret` 和 `authorization` 等常见的机密参数会被脱敏。
- 记录的值最多为 1000 个字符。
如果日志目录或文件不存在，Fireline 会尝试创建它。如果日志文件不可写，Fireline 会抛出异常。请确保 `storage/logs` 可由 PHP 进程写入。
## 性能分析与指标
Fireline 记录轻量级的进程内指标，用于调优规则和缓存行为。
```
use Fireline\Telemetry\RuleMetrics;
$snapshot = RuleMetrics::snapshot();
```
快照包括：
- `counters`：规则执行计数、规则匹配计数、误报计数和缓存写入。
- `timings`：带有 `count`、`total_ms` 和 `max_ms` 的扫描器和 regex 计时数据。
- `cache_hit_ratios`：安全/威胁缓存命中率。
- `slowest_rules`：按最慢的最大执行时间排序的计时数据。
示例：
```
RuleMetrics::increment('rule.SQL_UNION_SELECT.executed');
RuleMetrics::timing('rule.SQL_UNION_SELECT', 0.14);
RuleMetrics::falsePositive('SQL_UNION_SELECT');
```
当前的检测跟踪：
- 关键字扫描器计时
- 关键字规则匹配计数
- Regex 规则执行计数
- Regex 规则匹配计数
- Regex 规则计时
- 请求限制评估和违规
- 安全/威胁缓存命中和未命中
- 安全/威胁缓存写入
- 手动误报计数器
要在多个 Web 请求之间持久化指标，请设置 `metrics_path`：
```
'metrics_path' => __DIR__ . '/storage/metrics/fireline-metrics.json',
```
指标文件存储聚合快照。每个被检查的请求都会贡献其当前的指标增量，而格式错误或不完整的指标文件在下一次写入时会被视为空快照。
然后从 CLI 检查持久化的聚合数据：
```
php fire.php metrics:show storage/metrics/fireline-metrics.json
php fire.php metrics:show storage/metrics/fireline-metrics.json --json
php fire.php metrics:export storage/metrics/fireline-metrics.json storage/metrics/export.json
```
## CLI 和开发命令
运行测试：
```
composer test
```
运行冒烟测试：
```
composer run smoke
```
运行 PHP 语法检查：
```
composer run lint
```
验证规则元数据和 regex 语法：
```
composer run rules:validate
```
验证配置、可写路径和规则：
```
composer run config:check
```
运行完整的本地验证套件：
```
composer run check
```
`fire.php` CLI 提供了 `help`、`replay:run`、`baseline:build`、`baseline:export`、`config:check`、`rules:validate`、`metrics:show`、`metrics:export` 和 `metrics:reset`。
显示当前的进程内指标快照：
```
php fire.php metrics:show
php fire.php metrics:show --json
php fire.php metrics:show storage/metrics/fireline-metrics.json --summary
php fire.php metrics:export storage/metrics/fireline-metrics.json storage/metrics/export.json
php fire.php metrics:reset storage/metrics/fireline-metrics.json
```
## 故障排除
### 请求未被拦截
- 确认 `auto_prepend_file` 指向复制的 Web 根目录下的 `fireline.php`。
- 确认 PHP 已通过 `phpinfo()` 或主机控制面板加载了该设置。
- 确认 Web 根目录下的 `fireline.php` 包含了指向 `fireline/index.php` 的正确路径。
- 确认 `bypass_firewall` 未设置为 `true`。
- 添加一个临时测试查询（例如 `?q=javascript:alert(1)`），并验证是否返回 `403 Forbidden` 响应。
### 启用 Fireline 后站点返回 PHP 错误
- 确认已通过 `composer install --no-dev --optimize-autoloader` 安装了 Composer 依赖项。
- 确认 `fireline.php` 使用了与部署的目录布局相匹配的绝对包含路径。
- 确认 PHP 运行时版本为 PHP 7.1 或更高版本。
### 所有流量似乎都来自代理
将 `trusted_proxies` 设置为您的反向代理的 IP 或 CIDR 范围。除非 `REMOTE_ADDR` 受信任，否则 Fireline 会忽略 `X-Forwarded-For`。
### 合法流量被拦截
- 在审查事件时，将 `paranoia_level` 降低到 `low` 或提高 `score_threshold`。
- 检查 `storage/logs/fireline.log` 中的匹配字段、分数、原因和规范化值。
- 临时启用回放，重现该请求，并在规则或路由模型更改后对其进行回放。
- 审查路由模型中故意允许自由文本、URL、代码片段或搜索语法的字段。
### 国家拦截意外生效
如果启用国家拦截时 GeoIP 数据库丢失或不可读，则拦截机制将默认拒绝（fail closed）。确认 [src/GeoLite2-Country.mmdb](src/GeoLite2-Country.mmdb) 存在且可读。
### 日志未被写入
- 确认 `storage/logs/fireline.log` 存在。
- 确认它可由 Web 服务器用户写入。
- 确认 PHP 有权在 `storage/logs` 中进行写入。
### 指标或回放文件未被写入
- 确认 `metrics_path` 或 `replay_path` 指向一个可写的目录。
- 确认已通过 `replay_enabled => true` 启用回放。
- 将这些文件保留在公共 Web 访问之外，因为它们可能包含规范化的请求数据。
标签：AppImage, DOE合作, ffuf, OpenVAS, PHP, SQL注入防护, Web应用防火墙, XSS防护, 恶意流量过滤