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 应用，它就会开始
将每个 HTTP 请求与 150+ 种攻击模式进行扫描，按置信度对每个匹配项评分，
并将其写入你的数据库——内置仪表盘、Slack 告警、地理信息增强以及
fail2ban/阻止列表导出。任何请求都不会被阻止。把它想象成监控摄像头，
而不是锁：它准确地向你展示谁在探测你的路由、频率如何，以及使用了
什么技术。

> 从生产应用中提取，并在真实流量中经过实战检验。1,857 个测试，除 Laravel
> 本身外没有运行时依赖，检测不需要互联网连接。
>
> 要升级？请参阅 [UPGRADING.md](https://github.com/jay123anta/laravel-threat-detection/blob/main/UPGRADING.md)。想贡献？请参阅 [CONTRIBUTING.md](https://github.com/jay123anta/laravel-threat-detection/blob/main/CONTRIBUTING.md)。

## 不到一分钟即可开始```bash
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 中添加）——完整代码片段见下方快速开始。 就这样；检测已生效。```bash php artisan threat-detection:doctor # confirms it is actually recording

---

## 它适合放在哪里：IDS vs WAF vs 边缘

这个包是一个**被动的、应用层 IDS**——它只观察和记录，不拦截。它的定位是*与* WAF 或边缘服务*并存*，而不是取代它们。每一层都能看到其他层看不到的东西：

| | **本包**（应用 IDS） | **WAF**（mod_security、Cloudflare WAF） | **边缘 / CDN**（Cloudflare） |
|---|:---:|:---:|:---:|
| 拦截恶意请求 | ❌ 仅记录 | ✅ | ✅ |
| 完整的应用上下文（精确路由、解码后的载荷、已认证用户） | ✅ | ⚠️ 部分 | ❌ |
| 内置仪表盘 + 数据库中的威胁日志 | ✅ | ⚠️ 因产品而异 | ⚠️ 仅边缘 |
| 应用特定的检测（例如 Aadhaar / PAN / IFSC 个人身份信息） | ✅ 自定义模式 | ❌ | ❌ |
| 可离线运行 / 无需外部服务 | ✅ | ⚠️ 视情况而定 | ❌ |
| 在流量到达应用之前将其拦截 | ❌ | ✅ 边缘 | ✅ |
| 安装 | 一条 `composer require` | 中–高 | 低–中 |
| 成本 | 免费，MIT | 因产品而异 | 免费套餐 + 付费 |

**简而言之：** 边缘/WAF 是你门上的锁；而这是*内部*的监控摄像头，凭借应用上下文，它能准确告诉你：谁在哪个路由上尝试了什么、尝试了多少次。用它来为真实决策提供依据——fail2ban 封禁、速率限制、地理封锁——这些数据是你的边缘层永远看不到的。

### 它刻意不是什么

- **不是 WAF。** 它从不拦截、过滤或修改请求。要强制执行，请使用 Cloudflare、mod_security 或真正的 WAF。（没有可交接的边缘层？[运维侧辅助工具](#acting-on-the-data-operator-side-blocking)会暴露本包的判定结果，这样你就可以编写自己的五行拦截中间件——执行代码始终属于你，而不是本包。）
- **不能替代安全编码。** 参数化查询、输入验证和输出转义才是你真正的防线。本包假设你的代码已经安全，并为你提供*可见性*，而非保护。
- **不是边缘服务。** 如果你能在前面部署 Cloudflare，那就部署——然后再加上本包，以获得边缘服务看不到的应用层细节。
- **不是完整的检测器，也不可能做到。** 模式匹配只能捕获*看起来像*已知攻击的攻击。一种全新的技术，或者一种被改写到足够程度的熟悉技术，都会在未被记录的情况下通过——而且你也不会被告知它通过了。这里的沉默意味着“没有匹配到任何东西”，而绝不是“什么都没发生”。它的价值在于应对那些高频、低成本的流量，这些流量构成了实际打到公开 Laravel 应用上的大部分请求：扫描器、侦察探测、现成的注入字符串、凭据喷洒。把安静的日志视为缺乏证据，而不是没有发生事情的证据。

### 预期它第一天就会标记你自己的内容

未经调优的安装会对合法内容触发告警，你应该在安装之前就了解这一点，而不是安装之后。这些是实测结果，不是假设——测试套件固定了这份确切的列表，使其不会漂移（[`LegitimateTrafficCorpusTest`](https://github.com/jay123anta/laravel-threat-detection/blob/main/tests/Feature/LegitimateTrafficCorpusTest.php)）：

<!-- noise-floor:start -->
| 完全合法的请求 | 未经调优的安装会记录什么 |
|---|---|
| 在搜索框中输入 `how to write a UNION SELECT in postgres` | `SQL Injection UNION` / high |
| 一篇包含 `<script>window.dataLayer=[];</script>` 的博客文章 | `XSS Script Tag` / high |
| 一张粘贴了 `SELECT * FROM users WHERE id = 1` 报错的工单 | `SQLi Variant` / high |
| 解释 `../../etc/passwd` 是经典目录遍历载荷的文档 | `Directory Traversal` / medium |
| 一个收集真实印度手机号和 PAN 的个人资料表单 | `PAN Number Detected` / high |
<!-- noise-floor:end -->

**这些都不是 bug。** 一篇包含 `<script>` 的博客文章，逐字节来看就是一个存储型 XSS 载荷；搜索 `UNION SELECT` 与尝试注入无法区分。除了应用上下文，没有任何东西能区分它们，而没有任何模式引擎能替你提供这种上下文。

提供上下文只需改一行配置——`safe_fields`、`safe_paths`、`content_paths` 或 `relaxed` 模式。参见[减少误报](#reducing-false-positives)。**如果你的应用接受富文本、代码示例或搜索查询，请在评判输出之前先做这件事。** 默认设置刻意选择“嘈杂但诚实”，而不是“安静但不完整”：让一个已知的匹配静音，比发现一个从未触发的匹配要容易得多。

### 那你到底能用它做什么？

关于一个从不拦截的检测器，最常见的问题。四个答案，按投入精力递增排列：

| 你想要 | 使用 | 投入 |
|---|---|---|
| 查看有什么在攻击你 | [仪表盘](#dashboard)或 `threat-detection:stats` | 无需投入，它已经在运行 |
| 在防火墙上封禁惯犯 | [`threat-detection:export-fail2ban`](#artisan-commands)——通过管道传给 cron | 一行 |
| 在 Web 服务器层面拒绝 | [`threat-detection:export-blocklist`](#artisan-commands) → nginx/apache 指令 | 一行 |
| 在应用内拒绝请求 | [运维侧辅助工具](#acting-on-the-data-operator-side-blocking)——`isBlocklisted()`、`isDdosThresholdExceeded()` | 约 10 行你自己的中间件 |
| 实时响应 | [`ThreatDetected` 事件](#threatdetected-event)——Telegram、SIEM、PagerDuty | 一个监听器 |

本包提供情报；你提供拒绝动作。这种分工是刻意的——存在于你应用中的执行代码，是你可以阅读、测试和关闭的代码，这也意味着检测 bug 永远不会让你的网站宕机。


### 与其他 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 或队列 worker**。Redis/Memcached 只是*推荐*用于启用可选的 DDoS 检查（该检查在非原子驱动上会自动禁用）。队列写入是可选加入的，默认关闭。

---

## 工作原理

1. 一个中间件扫描每个传入的 HTTP 请求
2. 请求会与 158 个正则模式进行比对，覆盖 SQL 注入、XSS、RCE、文件遍历、SSRF、LDAP、XPath、SSTI 等
3. 如果匹配到威胁模式，一条记录会写入你的 `threat_logs` 数据库表，包含 IP、URL、威胁类型、严重级别和置信度评分
4. 可选地，对高严重性威胁发送 Slack 告警
5. 请求正常继续——**不会拦截任何东西**

检测不需要互联网连接。

---

## 快速开始

### 1. 安装本包```bash
composer require jayanta/laravel-threat-detection

2. 发布迁移并运行它们

此步骤是必需的。 如果没有它，包将检测到威胁但无法将其存储到数据库中。如果你跳过此步骤，你的 threat_logs 表将不存在，所有检测结果都会被静默丢失（你只会在 storage/logs/laravel.log 中看到错误）。```bash php artisan vendor:publish --tag=threat-detection-migrations php artisan migrate

这将创建两个表：`threat_logs`（存储检测到的威胁）和 `threat_exclusion_rules`（存储误报规则）。

**验证表是否已创建：**```bash
php artisan migrate:status

查找 create_threat_logs_table、add_confidence_to_threat_logs_table 和 create_threat_exclusion_rules_table —— 它们都应显示 Ran。

3. 注册中间件