docs: 新增蜜罐部署运维文档，cli.md 补 honeypot 命令与排障条目
docs/honeypot.md（新增）： - 生效范围与匹配规则：挂在 NotFound、业务前缀强制剔除、三类匹配方式； - 配置项表，并单独警告「行尾注释会被并入值」（IgnoreInlineComment 的坑）； - 两条封禁路径：GET 探测走常规阈值、提交凭据才一次即封，附原因 （GET 就封等于拿不到字典，这是最容易误解的一点）； - 凭据文件格式/权限/保留期，以及为什么不入库（备份、主从、BI）； - trust_proxy 部署必读：回环 IP 会让取证失真且一次封禁封掉整站； - 升级清理旧版明文列（purge-creds 不可逆）； - 排障表 + 设计取舍（GET 不封、canary 位置、邮件带明文等）。 docs/cli.md： - §0 补两条实测踩坑：「替换二进制必须重启进程」「strings 不认中文， 用 grep -ac」； - 命令总览加 honeypot； - 新增 §7 honeypot 命令（hits/stats/paths/size/prune/purge-creds）， 原 7/8/9 顺延为 8/9/10； - 排错表加 5 条：回环 IP、整站 403、进程未重启、strings 误判、命令不存在。
This commit is contained in:
tamakyi
+60
-5
@@ -20,13 +20,25 @@ go build -o NekoBox ./cmd/
|
||||
两处都注册在同一份 `app.Commands` 列表中。**新增命令时必须同时改 `tamabox.go` 和 `cmd/tamabox.go`**，
|
||||
否则会出现「本机二进制有、线上没有」（或反之），典型报错是 `No help topic for '<cmd>'`。
|
||||
|
||||
⚠️ **替换二进制不等于生效**：`go build -o tamabox .` 只改磁盘文件，正在运行的进程仍是旧映像。
|
||||
换完之后必须重启（systemd / supervisor / 手动拉起），否则改了代码也看不到变化。
|
||||
另外 `./tamabox web` 在前台立即返回，通常是端口被旧进程占着：
|
||||
|
||||
```bash
|
||||
ps -eo pid,lstart,cmd | grep '[t]amabox' # 看进程启动时间，与二进制 mtime 比对
|
||||
```
|
||||
|
||||
确认手头二进制包含全部命令：
|
||||
|
||||
```bash
|
||||
./tamabox --help | sed -n '/COMMANDS/,/GLOBAL/p'
|
||||
# web / censor / uid / ban / restore / reports / restrict / unrestrict / hide-public
|
||||
# web / censor / uid / ban / restore / reports / restrict / unrestrict / hide-public / honeypot
|
||||
```
|
||||
|
||||
> 想确认某个字符串有没有编进二进制，**不要用 `strings`** —— 它默认只输出可打印 ASCII，
|
||||
> UTF-8 中文整段被丢弃，`strings x | grep 中文` 恒为 0。
|
||||
> 用 `grep -ac "中文字符串" x`。
|
||||
|
||||
### 配置文件
|
||||
|
||||
CLI 与 `web` 读同一份配置，路径由环境变量指定：
|
||||
@@ -64,9 +76,11 @@ pg_dump -Fc <dbname> > before-$(date +%F-%H%M).dump
|
||||
| `restore` | 恢复已停用账号 | 是 | 用户申诉后恢复 |
|
||||
| `censor` | 重新审核历史内容 | 是 | 审核规则变更后复检 |
|
||||
| `uid` | 为用户生成/补齐 uid | 是 | 数据修复 |
|
||||
| `honeypot` | 扫描器诱捕取证（假登录页） | 部分是（`prune` / `purge-creds`） | 看谁在扫、拿到了什么字典 |
|
||||
| `web` | 启动 Web 服务 | — | 生产入口 |
|
||||
|
||||
除 `reports` 外，所有写操作都要求交互式输入大写 `YES` 确认；脚本化时加 `--yes`。
|
||||
除 `reports`、`honeypot hits/stats/paths/size` 外，所有写操作都要求交互式输入大写 `YES` 确认；
|
||||
脚本化时加 `--yes`。注意 `honeypot prune` / `purge-creds` 的确认词是 **`yes`**（小写）。
|
||||
|
||||
---
|
||||
|
||||
@@ -277,7 +291,43 @@ pg_dump -Fc <dbname> > before-$(date +%F-%H%M).dump
|
||||
|
||||
---
|
||||
|
||||
## 7. 典型处置流程
|
||||
## 7. `honeypot` —— 扫描器取证
|
||||
|
||||
> 设计取舍、凭据存储格式、部署要点见 [honeypot.md](honeypot.md)。这里只列命令。
|
||||
|
||||
| 子命令 | 作用 | 改数据 |
|
||||
|---|---|---|
|
||||
| `hits` | 列出捕获到的凭据（时间倒序，密码默认脱敏） | 否 |
|
||||
| `stats` | 来源 IP / 路径排行（库）+ 凭据排行（文件） | 否 |
|
||||
| `paths` | 列出当前生效的诱饵路径 | 否 |
|
||||
| `size` | 表行数、磁盘占用、凭据文件体积 | 否 |
|
||||
| `prune` | 按保留期清元数据 + 凭据文件 | 是 |
|
||||
| `purge-creds` | 删除旧版遗留的明文凭据列（**不可逆**） | 是 |
|
||||
|
||||
```bash
|
||||
./tamabox honeypot hits --since 7d --limit 50
|
||||
./tamabox honeypot hits --ip 203.0.113.9 --show-password
|
||||
./tamabox honeypot stats --days 7
|
||||
./tamabox honeypot paths
|
||||
./tamabox honeypot size
|
||||
./tamabox honeypot prune --days 30
|
||||
./tamabox honeypot purge-creds
|
||||
```
|
||||
|
||||
要点：
|
||||
|
||||
- **凭据不入库**。用户名/密码只写在 `data/honeypot-creds/creds-YYYY-MM-DD.jsonl`
|
||||
（目录 0700、文件 0600），数据库里只有 IP / 路径 / UA / 是否封禁这些元数据。
|
||||
所以 `hits` / `paths` **不连数据库**，DB 挂了也能查。
|
||||
- 密码默认脱敏（保留首尾各 1 位）。终端输出常被贴进工单或截图，`--show-password` 只在确有取证需要时开。
|
||||
- `purge-creds` 用于清掉早期版本存在 `honeypot_hits` 上的明文列（AutoMigrate 不删既有列）。
|
||||
执行前先 `pg_dump`；它只处理当前库，**历史备份与从库里的明文需要自行清理**。
|
||||
- 封禁语义：GET 探测走常规阈值（默认 10 次 / 60 秒），**提交凭据才一次即封**。
|
||||
所以「扫了几十次怎么没封」不是 bug —— 见 [honeypot.md](honeypot.md) 的「两条封禁路径」。
|
||||
|
||||
---
|
||||
|
||||
## 8. 典型处置流程
|
||||
|
||||
1. **发现**：收到告警邮件（同一箱主 24h ≥ 8 条 或 7d ≥ 20 条）→ 或箱主后台出现「被举报 N 次」。
|
||||
2. **取证**：`reports --domain <domain>` 看条目、占比、历史处置。
|
||||
@@ -299,7 +349,7 @@ pg_dump -Fc <dbname> > before-$(date +%F-%H%M).dump
|
||||
|
||||
---
|
||||
|
||||
## 8. 排错
|
||||
## 9. 排错
|
||||
|
||||
| 现象 | 原因 | 处理 |
|
||||
|---|---|---|
|
||||
@@ -312,12 +362,17 @@ pg_dump -Fc <dbname> > before-$(date +%F-%H%M).dump
|
||||
| 箱主说「我改了但没生效」 | 处置期内严格度被锁定 / L2 禁止设为公开 | 看后台条幅；`reports` 查当前处置 |
|
||||
| `--days 超过 90 天` 被拒绝 | 防手误设计，需要 `--force` | 确认时长后重试，或改用常规天数 |
|
||||
| 处置成功但箱主说没收到邮件 | SMTP 未配 / 发送失败 / 用了 `--no-notify` | 看终端 warn；`[mail]` 配好后可 `restrict` 重发（同级别重设会替换记录） |
|
||||
| 蜜罐记录的 `ip` 是 `127.0.0.1` | `trust_proxy` 未配，源站把所有人看成同一个代理 IP | 配 `trust_proxy`；**此时一次封禁会封掉整站**（见 [honeypot.md](honeypot.md) 的「部署」一节） |
|
||||
| 整站都返回 403 | 蜜罐把反代 IP 封了（上一条的后果） | 重启进程（封禁是内存态）或等 `honeypot_ban_minutes` 到期 |
|
||||
| 换了二进制但行为没变 | 进程没重启，跑的还是旧映像 | `ps -eo lstart,cmd \| grep tamabox` 比对启动时间与文件 mtime |
|
||||
| `strings 二进制 \| grep 中文` 恒为 0 | `strings` 只输出可打印 ASCII，中文 UTF-8 被丢弃 | 用 `grep -ac "中文字符串" 二进制` |
|
||||
| `honeypot` 命令不存在 | 二进制旧 / 两个构建入口未同步 | 重新编译后**重启进程** |
|
||||
|
||||
改完配置**必须重启**才生效（配置只在启动时读取一次）。
|
||||
|
||||
---
|
||||
|
||||
## 9. 明确不做的事
|
||||
## 10. 明确不做的事
|
||||
|
||||
- **不做自动处置**：举报数达标只发邮件，不自动封禁。这个场景里举报本身就是攻击武器。
|
||||
- **不做申诉后台**：申诉走邮件，处置结果由 CLI 写入。
|
||||
|
||||
Reference in New Issue
Block a user