laravel-threat-detection v1.7.2
被动式 Laravel 中间件，用于检测并记录 SQL 注入、XSS、RCE、bot 扫描器及 175+ 种攻击模式。内置仪表盘、Slack 告警、REST API 和地理位置增强功能。属于 IDS，而非 WAF。
Laravel Threat Detection
面向 Laravel 的安全监控与攻击日志记录。检测并记录 SQL 注入、
XSS、RCE、目录遍历、机器人扫描器以及 /wp-admin 风格的侦察探测——
每个恶意请求都会连同完整的应用上下文记录到你的数据库中。
它是 IDS，不是 WAF：它从不拦截、过滤或修改请求。
你是因为看到类似这样的内容才来到这里的吗？
GET /wp-admin/setup-config.php 404 — on a site that isn't WordPress
GET /.env 404 — someone wants your database password
GET /?id=1' UNION SELECT password FROM 200 — SQL injection against a real route
GET /phpmyadmin/index.php 404 — scanning for an admin panel
这些请求已经在到达你的 Laravel 应用。你的访问日志只显示了 URL 和状态码，除此之外什么都没有——没有解码后的载荷，没有哪个路由被针对， 也没有同一个 IP 是否在这一小时内尝试了其他四十种操作。
这个包回答了这些问题。把它放入任何 Laravel 10–13 应用，它就会开始 针对 150 多种攻击模式扫描每一个 HTTP 请求，按置信度对每个匹配项评分， 并将其写入你的数据库——内置仪表盘、Slack 告警、地理位置信息增强， 以及 fail2ban/阻止列表导出。任何请求都不会被阻止。把它想象成监控摄像头， 而不是锁：它准确地向你展示谁在探测你的路由、频率如何，以及使用了什么技术。
从生产应用中提取，并在真实流量中经过实战检验。2,400+ 项测试，除 Laravel 本身外没有运行时依赖，检测也不需要互联网连接。
要升级？请参阅 UPGRADING.md。想贡献？请参阅 CONTRIBUTING.md。
不到一分钟即可开始
composer require jayanta/laravel-threat-detection
php artisan vendor:publish --tag=threat-detection-migrations
php artisan migrate
然后将中间件添加到你的 web 组中（在 Laravel 11+ 中是在 bootstrap/app.php 中添加一行，在 Laravel 10 中是在 app/Http/Kernel.php 中添加一行）——完整代码片段见下方的快速开始。就这样，检测已生效。
php artisan threat-detection:doctor # confirms it is actually recording
适用场景：IDS vs WAF vs 边缘
本包是一个被动的应用层 IDS——它只监视和记录，不进行拦截。它的定位是与 WAF 或边缘服务并存，而非替代它们。每一层都能看到其他层看不到的东西：
| 本包（应用 IDS） | WAF（ModSecurity + OWASP CRS、Cloudflare WAF） | 边缘 / CDN（Cloudflare） | |
|---|---|---|---|
| 拦截恶意请求 | ❌ 仅记录 | ✅ | ✅ |
| 完整的应用上下文（精确 URL、解码后的载荷、已认证用户） | ✅ | ⚠️ 部分 | ❌ |
| 内置仪表盘 + 数据库中的威胁日志 | ✅ | ⚠️ 因情况而异 | ⚠️ 仅边缘 |
| 应用特定的检测（例如 Aadhaar / PAN / IFSC 个人身份信息） | ✅ 内置 + 自定义 | ⚠️ 需自行编写规则 | ⚠️ 自定义规则，取决于套餐 |
| 可离线运行 / 无需外部服务 | ✅ | ⚠️ 视情况而定 | ❌ |
| 在流量到达服务器之前将其拦截 | ❌ | ⚠️ 仅云 WAF | ✅ |
| 安装配置 | composer require、迁移、一行中间件 | 中–高 | 低–中 |
| 成本 | 免费，MIT | 因情况而异 | 免费套餐 + 付费 |
简而言之： 边缘/WAF 是你门上的锁；而这是内部的安全摄像头，凭借应用上下文，它能准确告诉你：谁在哪个路由上尝试了什么、尝试了多少次。用它来为真实决策提供依据——fail2ban 封禁、速率限制、地理封锁——这些数据是你的边缘层永远看不到的。
它刻意不做的事
- 不是 WAF。 它从不拦截、过滤或修改请求。请使用 Cloudflare、mod_security 或真正的 WAF 来执行拦截。（没有可交接的边缘层？运维侧辅助工具会暴露本包的判定结果，让你可以编写自己的五行拦截中间件——执行代码归你所有，而非本包。）
- 不能替代安全编码。 参数化查询、输入验证和输出转义才是你真正的防线。本包假设你的代码已经安全，并为你提供可见性，而非保护。
- 不是边缘服务。 如果你能在前面部署 Cloudflare，那就部署——然后再加上本包，以获取边缘服务无法看到的应用层细节。
- 不是完整的检测器，也不可能做到。 模式匹配只能捕获看起来像已知攻击的攻击。一种新颖的技术，或一种被改写得足够多的熟悉技术，都会在未被记录的情况下通过——而且你也不会被告知它通过了。这里的沉默意味着“没有匹配到”，而绝不是“什么都没发生”。它的价值在于应对那些构成实际攻击公开 Laravel 应用的大部分流量：扫描器、侦察探测、现成的注入字符串、凭据喷洒。把安静的日志视为缺乏证据，而非没有发生。
预期它第一天就会标记你自己的内容
未经调优的安装会误报合法内容，你应当在安装之前而非之后了解这一点。以下数据是实测的，而非假设。下表是 LegitimateTrafficCorpusTest 所固定噪声下限的样本；每一行都列出了该请求所记录的全部内容，而 ReadmeNoiseFloorTest 会在任何一行不再匹配测试套件所测量的结果时使构建失败。
| 完全合法的请求 | 未经调优的安装会记录什么 |
|---|---|
在搜索框中输入 how to write a UNION SELECT in postgres | SQL Injection UNION / 高 |
一篇包含 <script>window.dataLayer=[];</script> 的博客文章 | XSS Script Tag / 高 · Command Chain Injection / 中 |
一张粘贴了 SELECT * FROM users WHERE id = 1 错误的支持工单 | SQLi Variant / 高 · SQL SELECT Query / 低 |
解释 ../../etc/passwd 是经典遍历载荷的文档 | Directory Traversal / 中 · Sensitive File Access / 中 |
| 一个收集真实印度手机号和 PAN 的个人资料表单 | PAN Number Detected / 高 · Bank Account Number Detected / 高 · Mobile Number Detected / 低 |
这些都不是缺陷。 一篇包含 <script> 的博客文章，逐字节来看就是一个存储型 XSS 载荷；搜索 UNION SELECT 与尝试注入无法区分；一个十位手机号也可能是一个合理的银行账号。除了应用上下文，没有任何东西能将它们区分开来，而没有任何模式引擎能为你提供这种上下文。
提供上下文只需一行配置更改：在 safe_fields 中指定合法携带此类内容的字段（或使用 safe_paths，针对嵌套 JSON 中的某个路径），它就不再被扫描。这就是让上表各行安静下来的开关——而这是一个真实的权衡，因为通过该字段传递的攻击也会被忽略。
content_paths 和 relaxed 模式是不同的工具。它们会丢弃低和中危噪声，并刻意继续记录高危匹配——因此按设计它们不会让本表中的高危行安静下来。关于何时该用哪个，请参阅减少误报。
如果你的应用接受富文本、代码示例或搜索查询，请在评判输出之前先做这件事。 默认设置刻意选择嘈杂但诚实，而非安静但不完整：让一个已知匹配安静下来，比发现一个从未触发的匹配要容易。
那么你实际上能用它做什么？
关于一个从不拦截的检测器，最常见的问题。四个答案，按投入递增排列：
| 你想要 | 使用 | 投入 |
|---|---|---|
| 查看什么在攻击你 | 仪表盘 或 threat-detection:stats | 无，它已经在运行 |
| 在防火墙上封禁惯犯 | threat-detection:export-fail2ban — 管道到 cron | 一行 |
| 在 Web 服务器层面拒绝 | threat-detection:export-blocklist → nginx/apache 指令 | 一行 |
| 在应用内拒绝请求 | 运维侧辅助工具 — isBlocklisted()、isDdosThresholdExceeded() | 约 10 行你自己的中间件 |
| 实时响应 | ThreatDetected 事件 — Telegram、SIEM、PagerDuty | 一个监听器 |
本包提供情报；你提供拒绝。这种分工是刻意的——存在于你应用中的执行代码是你可以阅读、测试和关闭的代码，这意味着检测缺陷永远不会让你的网站宕机。
与其他 Laravel 安全包的比较
这些包解决不同的问题，并且能很好地组合使用——这张表是为了帮你选对工具，而非分出胜负。
| 包 | 作用 | 是否拦截？ | 何时使用 |
|---|---|---|---|
| 本包 | 用 150+ 种模式扫描每个请求，记录完整的应用上下文 | ❌ | 你想看到你的应用正在遭受什么攻击 |
spatie/laravel-honeypot | 捕获垃圾邮件机器人的隐藏表单字段 | ✅ 仅表单 | 你的公开表单正在被灌垃圾 |
graham-campbell/security | 从输入中剥离类似 XSS 的标记 | ✅ 会修改 | 你想要简单的输入清理 |
spatie/laravel-csp | 发送 Content-Security-Policy 头 | ✅ 浏览器 | 你想限制浏览器加载的内容 |
laravel/fortify + 速率限制 | 认证节流和锁定 | ✅ | 你需要登录的暴力破解防护 |
| Cloudflare / mod_security | 边缘 WAF，在应用之前拦截 | ✅ | 你想在流量到达之前将其拦截 |
诚实的总结：蜜罐捕获表单垃圾，WAF 在边缘拦截已知恶意流量，CSP 约束浏览器。它们都无法告诉你攻击者针对你的特定路由尝试了什么，并附带解码后的载荷和已认证用户。 这个空白正是本包所填补的——这也是本包刻意不拦截的原因：你可以将它和上述所有工具一起运行，而它们之间不会互相冲突。
环境要求
- PHP 8.2+（Laravel 13 需要 PHP 8.3+）
- Laravel 10.x、11.x、12.x 或 13.x
- Laravel 支持的任何数据库（MySQL、PostgreSQL、SQLite、SQL Server）
- 任何缓存驱动——无需 Redis 或队列工作进程。Redis/Memcached 只是推荐用于启用可选的 DDoS 检查（在非原子驱动上会自动禁用）。队列写入是可选加入的，默认关闭。