casuya-code/casuya-defence
GitHub: casuya-code/casuya-defence
一套模块化的网站欺骗防御架构，通过多层仿生诱饵陷阱和蜜罐机制主动引偏并消耗自动化攻击者的资源。
Stars: 0 | Forks: 0
# 网络欺骗防御
一个模块化、即插即用的**欺骗架构**，用于防御网站遭受未经授权的扫描、撞库和自动目录遍历攻击。
通过实现虚假路由、递归资源陷阱、生物防御机制和自毁数据资产，此代码库会主动将攻击者从你的真实代码库中引开——让侦察反噬其身。
## 工作原理
### 核心防御层（8 层流水线）
#### 第 0 层：Token 监控器 — `token_monitor.py` / `token_monitor.js`
监控 `assets/honeytokens/` 中的文件。任何针对这些文件的 `GET`、`POST` 或修改请求都会立即触发响应：
1. **防火墙立即封锁攻击者的 IP。**
2. **endpoint 动态随机化文件内容**，提供已损坏的垃圾数据。
3. **触发加密的安全警报 webhook** 发送给您的运维团队。
#### 第 1 层：手枪虾 — `pistol_shrimp.py` / `pistol_shrimp.js`
声学空化近距拦截器。检测速射攻击（扫描、暴力破解），并响应充满高频噪声数据的猛烈 TCP 重置 payload。
- 根据请求频率累积动压
- 在压力阈值 >15 时触发空化爆破
- 发出 410 Gone 状态码以及 `x-pistol-shrimp-blast` 标头
- 消耗计算能量以模拟声致发光（4700°C 维持 0.1 毫秒）
- 每个 IP 冷却时间 60 秒
- 限制最多 50 个并发爆破
#### 第 2 层：放屁虫 — `bombardier_beetle.py` / `bombardier_beetle.js`
带有放热排放响应的速率限制。三个响应级别：
- **25 次请求**：429 "Connection rejected"（连接被拒绝）并附带热量输出标头
- **100 次请求**：429 "Rate limit exceeded"（超出速率限制）并附带 retry-after
- **惯犯**：503 "Service Temporarily Unavailable"（服务暂时不可用）持续 5 分钟
通过消耗资源池额度来模拟生物成本。
#### 第 3 层：拟态章鱼 — `mimic_octopus.py` / `mimic_octopus.js`
基于攻击者指纹的多态特征伪装：
| 攻击者类型 | 响应配置 |
|---------------|------------------|
| 扫描器 (nmap, sqlmap) | 存在漏洞的 Apache/PHP 服务器 |
| 爬虫 (googlebot) | WordPress/Nginx CMS 后端 |
| 漏洞利用工具包 (metasploit) | 旧版 IIS/ASP.NET 服务 |
| 默认 | Cloudflare 代理错误 |
始终返回 200 OK，并带有轮换的 body 变体以浪费解析器逻辑。
#### 第 4 层：递归 Tarpit — `recursive_tarpit.py` / `recursive_tarpit.js`
当攻击者尝试进行 web 抓取或爬取诱饵目录时，此模块会以缓慢的间隔流式传输无尽的垃圾字节（1MB 分块）。迫使自动化工具陷入资源耗尽循环，从而锁定其扫描机器。限制最多 50 个并发 tarpit，以防止自身遭遇 DoS。
#### 第 5 层：多毛蛙 — `hairy_frog.py` / `hairy_frog.js`
牺牲型陷阱 endpoint 部署。在同一个 IP 访问 50 次后：
1. 提供虚假的数据库配置文件（带有占位符密码）
2. 重复访问时，提供蜜罐登录表单以捕获凭证
3. 消耗 8% 的系统健康度以模拟生物结构性创伤
#### 第 6 层：德克萨斯角蜥 — `horned_lizard.py` / `horned_lizard.js`
通过自发性出血数据爆发进行资源耗尽。在被访问 30 次后：
- 以 `backup_data.bin` 的形式转储 1-3MB 的随机二进制数据
- 每次激活消耗 25% 的资源池
- 耗尽攻击者的带宽和内存缓冲区
#### 第 7 层：弗吉尼亚负鼠 — `opossum.py` / `opossum.js`
死亡服务模拟。在 3 次重复访问后：
- 返回随机错误响应（502/503/504/500/404）
- 发出过时的标头（Apache 2.2.8，2000 年的日期）
- 使服务在 1 小时内看起来像已崩溃或被废弃
#### 第 8 层：AI 煤气灯操纵器 — `ai_gaslighter.py`（仅限 Python）
沙盒化的 AI 终端接口。根据 29 个被阻止的模式验证输入，将输入限制为 500 个字符，并在具有 5 秒超时的隔离的 `/tmp` 目录中执行。默认禁用。
#### 第 9 层：路由重定向 — `router_redirect.py` / `router_redirect.js`
最终诱饵模板路由。将请求匹配到配置的诱饵路径，并使用适当的内容类型提供相应的 HTML 模板。
### 攻击流程
```
Attacker Scanner
│
├─ probes /wp-admin ──────────────────► Layer 9: routed to fake admin portal (URL unchanged)
├─ crawls bait directory ─────────────► Layer 4: served infinite junk folders / byte streams
├─ requests database_backup_fake.sql ─► Layer 0: IP blocked + corrupted payload + webhook alert
├─ rapid-fire scanning detected ──────► Layer 1: cavitation blast (410 Gone + noise payload)
├─ repeated requests from same IP ────► Layer 2: rate limited with 429/503 responses
├─ scanner fingerprint detected ──────► Layer 3: polymorphic signature spoofing
├─ 50+ hits on same endpoint ─────────► Layer 5: trap endpoints deployed
├─ 30+ hits persist ──────────────────► Layer 6: resource exhaustion data dump
└─ 3+ repeat hits ───────────────────► Layer 7: dead service emulation
```
## 设置与集成
### 1. 克隆代码库
```
git clone casuya-defence
cd casuya-defence
```
### 2. 关联拦截器（FastAPI 后端）
将核心拦截器附加到您的 FastAPI 应用中。由于 ASGI middleware 在路由表**外部**运行，因此诱饵路径永远不会到达真实的 route handler：
```
from fastapi import FastAPI
from middleware.index import DeceptionMiddleware
app = FastAPI()
# 所有 8 个 layer 均按正确顺序自动装配
app.add_middleware(DeceptionMiddleware)
@app.get("/")
async def home():
return {"status": "ok"}
```
### 3. 关联拦截器（Node / Express 后端）
对于纯 JS 网站，从 `middleware-js/` 中接入等效的 JS——它们具有相同的层和逻辑：
```
const express = require("express");
const { wireDeception } = require("./middleware-js/index");
const app = express();
// All 8 layers are automatically wired in correct order
wireDeception(app, { webhookUrl: process.env.ALERT_WEBHOOK });
app.get("/", (req, res) => res.send({ status: "ok" }));
```
或者使用预置的入口点：
```
const { createDeceptionApp } = require("./middleware-js");
const app = createDeceptionApp({ webhookUrl: process.env.ALERT_WEBHOOK });
```
对于 **Next.js**，在 Node runtime 上运行相同的模块（Next.js middleware 默认仅限 Edge，因此将其指向 Node）：
```
// middleware.js — Next.js (requires Node runtime)
import { NextResponse } from "next/server";
import { isBaitPath } from "./middleware-js/core/routes";
export function middleware(request) {
if (isBaitPath(request.nextUrl.pathname)) {
return new NextResponse("Login", {
headers: { "content-type": "text/html" },
});
}
return NextResponse.next();
}
export const config = { matcher: ["/wp-admin", "/backup.zip", "/.env", "/phpmyadmin"], runtime: "nodejs" };
```
### 4. 提供虚假前端（Node / Next.js）
`assets/templates/` 中的诱饵页面由纯 JavaScript 构建和提供——Next.js 路由或 Express handler 会按需呈现它们，使得这些诱饵看起来与您的技术栈融为一体：
```
// Node / Express (pure JS)
const express = require("express");
const app = express();
// Render fake portals dynamically instead of serving static files
app.get("/wp-admin", (req, res) => {
res.send(renderFakeAdminLogin()); // fake login portal
});
app.get("/backup.zip", (req, res) => {
res.send(renderFakeBackupDashboard()); // fake dashboard page
});
```
对于 Next.js，将相同的虚假页面实现为 JSX route handler（`app/wp-admin/page.tsx`，`app/backup/page.tsx`）或 middleware——FastAPI 欺骗层会自动将 `/wp-admin` 和 `/backup.zip` 路由到那里，而攻击者永远看不到隐藏在它们背后的真实应用。
### 5. 访问 SIEM 仪表板
实时 SIEM 仪表板可将所有防御层的入侵者分解模式可视化：
```
# 启动 demo server
npm start
# 打开 dashboard
open http://localhost:3100/dashboard
```
仪表板面板包括：
- **放热峰值追踪器** — 放屁虫激活强度
- **多态迷失网格** — 拟态章鱼特征伪装
- **结构性创伤图** — 多毛蛙陷阱部署
- **恶臭指数** — 德克萨斯角蜥资源耗尽
- **紧张性欺骗量表** — 负鼠死亡服务模拟
- **入侵者分解追踪器** — 单个攻击者经历 0-5 阶段的进度
API endpoint：
- `GET /api/metrics` — 实时仪表板数据
- `GET /api/alerts` — 活动的生物防御警报
- `GET /api/footprints` — 入侵者追踪数据
### 6. 配置您的诱饵路由
在 `config/deception_routes.json` 中填入您想用作诱饵的路径字符串，以及每个路径所提供的模板：
```
{
"bait_routes": [
"/wp-admin",
"/.env",
"/backup.zip",
"/phpmyadmin",
"/server-status",
"/config.php"
],
"bait_templates": {
"/wp-admin": "admin_login_fake.html",
"/.env": "config_env_canary.json",
"/backup.zip": "backup_dashboard.html",
"/phpmyadmin": "admin_login_fake.html",
"/server-status": "backup_dashboard.html",
"/config.php": "admin_login_fake.html"
},
"protected_paths": [
"/api",
"/dashboard",
"/admin"
]
}
```
### 7. 调整阈值规则
调整 `config/threshold_rules.conf` 以控制 tarpit 何时激活或 IP 何时被封锁：
```
# 当单个 IP 发起 N 次快速请求后激活 tarpit
tarpit.threshold_requests = 25
tarpit.slow_stream_bytes = 1048576
# 在反复命中 honeytoken 后 block IP
block.ip_repeat_hits = 3
block.autoban_ttl_hours = 24
# Webhook 告警目标
alert.webhook_url = https://your-ops-team.example.com/alerts
alert.encryption_key = CHANGE_ME
# Anti-fingerprinting（攻击者会检测 X- headers 和 canned responses）
stealth.emit_layer_headers = false
stealth.vary_response = true
stealth.rotation_interval_hours = 168
```
### 8. 部署陷阱
验证配置和资产，然后打印活动的诱饵路由映射：
```
python scripts/deploy_traps.py
```
为 tarpit 生成无尽的虚假数据：
```
python scripts/generate_bait_data.py --output ./assets/dynamic_clones --depth 6 --branching 4
```
轮换陷阱，使过时的诱饵无法被指纹识别（按计划运行，例如每周 cron 任务）：
```
python scripts/rotate_traps.py # clone honeytokens under new names + reshuffle templates
python scripts/rotate_traps.py --dry-run
```
## 了解您的对手
**攻击者了解欺骗战术。** 公开的蜜罐研究、开源的扫描器特征以及泄露的剧本，意味着此代码库中的确切路由（`/wp-admin`、`/.env`、`tarpit` 标头、虚假 SQL 转储）对于自动化工具来说是可识别的。请将以下几点视为基本底线：
- **指纹识别对攻击者来说成本很低。** `X-Deception-Layer` 标头、跨主机相同的模板、`data.bin` tarpit 以及千篇一律的 "Login" 后备方案都是指纹。请在投入生产环境之前，部署自定义模板、改变响应，并移除可识别身份的标头。
- **欺骗带给您的是*时间和遥测数据*，而不是绝杀。** 一个有能力且检测到诱饵的对手只需忽略它或进行枢纽转移。您所保留下来的是入侵信号——警报 webhook——以及他们被浪费掉的周期。
- **真正的安全防护依然在发挥作用。** 打补丁、速率限制、身份验证和网段划分。欺骗是绊线，而不是栅栏。如果 tarpit 或 honeytoken 是路由上的*唯一*控制手段，那么攻击无论如何都会成功。
- **陷阱绝不能成为攻击媒介。** 一个看似可信的虚假代理到了真实应用、一个可以被提示词诱导出沙箱的 LLM 操纵器，或者一个耗尽*您的* socket 的 tarpit，都会把防御变成对自己的攻击。请将诱饵与生产数据和网络隔离开来。
- **持续刷新。** 静态诱饵会腐化。请定期轮换模板、honeytoken 文件名和路由，以便上个月刚耗尽您诱饵的扫描器必须重新进行学习。此代码库附带 `scripts/rotate_traps.py` 和 `[stealth]` 配置块（`emit_layer_headers = false` 是默认值），使轮换和去指纹化只需一条命令即可完成。
## 高级反情报
该框架包含高级模块，用于对抗那些试图进行指纹识别或绕过欺骗的经验丰富的攻击者：
**时间分析防御** (`middleware/core/timing.py`)
- 检测统一的请求时间模式（自动化扫描）
- 检测连续的目录枚举
- 应用可变的抖动延迟以击败时间分析
**流量模式分析** (`middleware/core/traffic.py`)
- 识别扫描器 user agent、连续路径探测
- 检测资源过度抓取模式
- 追踪可疑的扩展名和敏感路径定位
**蜜罐检测对策** (`middleware/core/counterintelligence.py`)
- 检测攻击者何时正在主动搜索蜜罐特征
- 追踪连续的指纹识别尝试
- 识别请求中的欺骗检测 payload
**欺骗深度分层** (`middleware/core/deception_depth.py`)
- 根据攻击者的持续程度不断加深的分阶段欺骗
- 阶段 1：表面诱饵（基础的虚假页面）
- 阶段 2：深度诱饵（虚假凭证、配置）
- 阶段 3：自适应诱饵（匹配响应技术）
- 阶段 4：反应性伪装（深度的虚假服务模拟）
**误报预防** (`middleware/core/false_positive.py`)
- 将 localhost、私有网络和受信任的 user agent 列入白名单
- 需要类似浏览器的标头（Accept、Accept-Language、Accept-Encoding）
- 进行速率限制以防止滥用，同时保护合法流量
这些模块作为生物防御层之前的预检运行，可确保：
1. 合法流量绝不会被阻止
2. 经验丰富的攻击者无法对蜜罐进行指纹识别
3. 自动化扫描器能被尽早检测到并加以反击
4. 欺骗深度会随着攻击者的持续程度进行适当的升级
## 重要安全提示
- **Honeytoken 绝不包含真实凭证。** `assets/honeytokens/` 中的所有诱饵文件都是合成的；SQL 转储使用虚假表，而 `.json` 金丝雀包含虚假密钥。
- **警报 webhook 必须被加密/签名**，以便攻击者无法欺骗或读取操作警报。
- **Tarpit 可能会消耗服务器资源。** 请根据您的流量基线调整 `threshold_rules.conf`，以免合法用户受到限制。Tarpit 限制为 50 个并发连接，可防止自身遭遇 DoS。
- **AI 诱饵必须保持在沙盒中。** `ai_gaslighter.py` LLM 绝不能接触到生产数据、真实凭证或内部网络。它默认禁用，并会拦截 29 种危险命令模式。
- **故障开放设计。** 如果任何 middleware 层崩溃，请求将继续进入下一层或真实应用程序。这可以防止欺骗系统成为单点故障。
- **路由轮换是自动的。** 诱饵路由每 24 小时使用基于哈希的变体进行一次轮换，以防止指纹识别。
- **受保护路径可以动态注册。** 使用 `register_protected_paths()` 可在不重启的情况下添加新的 endpoint。
- **高级反情报默认处于活动状态。** 时间分析、流量模式检测和误报预防会在任何防御层介入之前自动运行。
- **这是深度防御，而不是替代方案**，不能替代打补丁、速率限制、WAF 和适当的访问控制。
## 文档
| 文档 | 描述 |
|----------|-------------|
| `BIOLOGICAL_DEFENSE.md` | 全部 5 个生物防御层的详细文档 |
| `SECURITY_PATCHES.md` | 针对 5 个架构漏洞的补丁 |
| `SIEM_DASHBOARD.md` | 仪表板面板、API endpoint、视觉指示器 |
| `SIEM_QUICK_REFERENCE.md` | 仪表板布局、命令、故障排除 |
| `QUICK_REFERENCE.md` | 所有防御层的快速参考卡 |
## 验证与 CI
`.github/workflows/security-scan.yml` 流水线会在每次推送时自动验证欺骗完整性：
- 编译所有 Python 模块（`middleware/**`、`scripts/*.py`）。
- 对所有 JS 模块进行语法检查（`middleware-js/**`）。
- 运行 `deploy_traps.py --check-only` 以确认诱饵路由、模板和 honeytoken 存在，并且没有任何 `protected_path` 被诱饵路由所遮蔽。
- 扫描 honeytoken 以确保没有真实机密（真实域名、私钥、有效的 API 密钥）泄漏到诱饵中。
## 许可证
此代码库仅用于演示和教育目的。在生产部署之前，请选择并添加一个许可证文件。
## 贡献
发现了更好的陷阱？欢迎提交 PR。欢迎在代码库的 issue 追踪器中提出 issue、想法和威胁建模反馈。
标签：WAF, Web安全, 实时处理, 密码管理, 数据可视化, 自动化防御, 蓝队分析, 蜜罐技术, 逆向工具, 防御架构