BlessedRebuS/Krawl
GitHub: BlessedRebuS/Krawl
一款云原生 Web 欺骗服务器，通过虚假应用和诱饵数据检测、延迟并分析攻击者与爬虫的恶意活动。
Stars: 469 | Forks: 38
Krawl
一个现代化、可定制的 Web 蜜罐服务器，旨在通过欺骗性网页、虚假凭证和 Canary Token 检测并追踪攻击者与 Web 爬虫的恶意活动。
## 目录
- [演示](#demo)
- [什么是 Krawl？](#what-is-krawl)
- [Krawl 仪表盘](#krawl-dashboard)
- [安装](#-installation)
- [Docker Run](#docker-run)
- [Docker Compose](#docker-compose)
- [Kubernetes](#kubernetes)
- [本地 (Python)](#local-python)
- [配置](#configuration)
- [config.yaml](#configuration-via-configyaml)
- [环境变量](#configuration-via-enviromental-variables)
- [封禁恶意 IP](#use-krawl-to-ban-malicious-ips)
- [IP 信誉](#ip-reputation)
- [转发 Server 头](#forward-server-header)
- [更多文档](#additional-documentation)
- [贡献](#-contributing)
## 演示
提示：抓取 `robots.txt` 路径以获得更多乐趣
### Krawl URL: [http://demo.krawlme.com](http://demo.krawlme.com)
### 查看仪表盘 [http://demo.krawlme.com/das_dashboard](http://demo.krawlme.com/das_dashboard)
## 什么是 Krawl？
**Krawl** 是一个云原生欺骗服务器，旨在检测、延迟和分析恶意攻击者、Web 爬虫及自动化扫描器。
它创建逼真的虚假 Web 应用程序，其中充满低垂的果实，如管理面板、配置文件和暴露的虚假凭证，以吸引并识别可疑活动。
通过消耗攻击者的资源，Krawl 有助于清晰地区分恶意行为与合法爬虫。
其特性包括：
- **蜘蛛陷阱页面**：基于 [spidertrap 项目](https://github.com/adhdproject/spidertrap)，通过无限随机链接消耗爬虫资源
- **虚假登录页面**：WordPress、phpMyAdmin、管理面板
- **蜜罐路径**：在 robots.txt 中宣传以捕获扫描器
- **虚假凭证**：外观逼真的用户名、密码、API 密钥
- **[Canary Token](docs/canary-token.md) 集成**：外部告警触发
- **随机服务器头**：基于服务器头和版本混淆攻击
- **实时仪表盘**：监控可疑活动
- **可定制字典**：基于 JSON 的简易配置
- **随机错误注入**：模拟真实服务器行为
您可以轻松地将 Krawl 与您的其他服务一起通过反向代理暴露，从而保护它们免受 Web 爬虫和恶意用户的侵害。更多详情请参阅 [反向代理文档](docs/reverse-proxy.md)。
## Krawl 仪表盘
Krawl 提供了一个全面的仪表盘，可通过启动时生成的**随机秘密路径**或通过 `KRAWL_DASHBOARD_SECRET_PATH` 配置的**自定义路径**访问。这使得仪表盘对扫描您蜜罐的攻击者不可见。
仪表盘分为三个主要标签页：
- **Overview (概览)** — 攻击活动的高级视图：IP 来源的交互式地图、近期可疑请求，以及排名前列的 IP、User-Agent 和路径。
- **Attacks (攻击)** — 捕获的凭证、蜜罐触发和检测到的攻击类型（SQLi、XSS、路径遍历等）的详细分析，配有图表和表格。
- **IP Insight (IP 洞察)** — 选定 IP 的深度取证视图：地理位置、ISP/ASN 信息、信誉标记、行为时间轴、攻击类型分布及完整访问历史。
更多详情请参阅 [仪表盘文档](docs/dashboard.md)。
## 🚀 安装
### Docker Run
使用最新镜像运行 Krawl：
```
docker run -d \
-p 5000:5000 \
-e KRAWL_PORT=5000 \
-e KRAWL_DELAY=100 \
-e KRAWL_DASHBOARD_SECRET_PATH="/my-secret-dashboard" \
-v krawl-data:/app/data \
--name krawl \
ghcr.io/blessedrebus/krawl:latest
```
访问服务器地址 `http://localhost:5000`
### Docker Compose
创建一个 `docker-compose.yaml` 文件：
```
services:
krawl:
image: ghcr.io/blessedrebus/krawl:latest
container_name: krawl-server
ports:
- "5000:5000"
environment:
- CONFIG_LOCATION=config.yaml
- TZ=Europe/Rome
volumes:
- ./config.yaml:/app/config.yaml:ro
# bind mount for firewall exporters
- ./exports:/app/exports
- krawl-data:/app/data
restart: unless-stopped
volumes:
krawl-data:
```
运行：
```
docker-compose up -d
```
停止：
```
docker-compose down
```
### Kubernetes
**Krawl 也可以在 Kubernetes 上原生运行**。可以通过 [通过 manifest](kubernetes/README.md) 或 [使用 helm chart](helm/README.md) 进行安装。
### Python + Uvicorn
直接使用 Python（建议版本 13）和 uvicorn 运行 Krawl，用于本地开发或测试：
```
pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 5000 --app-dir src
```
访问服务器地址 `http://localhost:5000`
## 配置
Krawl 使用**配置层级**，其中**环境变量优先于配置文件**。此方法推荐用于 Docker 部署和开箱即用的快速自定义。
### 通过 config.yaml 配置
您可以使用 [config.yaml](config.yaml) 文件进行高级配置，例如 Docker Compose 或 Helm chart 部署。
### 通过环境变量配置
| 环境变量 | 描述 | 默认值 |
|----------------------|-------------|---------|
| `CONFIG_LOCATION` | yaml 配置文件路径 | `config.yaml` |
| `KRAWL_PORT` | 服务器监听端口 | `5000` |
| `KRAWL_DELAY` | 响应延迟（毫秒） | `100` |
| `KRAWL_SERVER_HEADER` | 用于欺骗的 HTTP Server 头 | `""` |
| `KRAWL_LINKS_LENGTH_RANGE` | 链接长度范围，格式为 `min,max` | `5,15` |
| `KRAWL_LINKS_PER_PAGE_RANGE` | 每页链接数，格式为 `min,max` | `10,15` |
| `KRAWL_CHAR_SPACE` | 用于链接生成的字符集 | `abcdefgh...` |
| `KRAWL_MAX_COUNTER` | 初始计数器值 | `10` |
| `KRAWL_CANARY_TOKEN_URL` | 外部 Canary Token URL | None |
| `KRAWL_CANARY_TOKEN_TRIES` | 显示 Canary Token 前的请求数 | `10` |
| `KRAWL_DASHBOARD_SECRET_PATH` | 自定义仪表盘路径 | 自动生成 |
| `KRAWL_PROBABILITY_ERROR_CODES` | 错误响应概率 (0-100%) | `0` |
| `KRAWL_DATABASE_PATH` | 数据库文件位置 | `data/krawl.db` |
| `KRAWL_EXPORTS_PATH` | 防火墙规则集导出路径 | `exports` |
| `KRAWL_BACKUPS_PATH` | 数据库转存储存路径 | `backups` |
| `KRAWL_BACKUPS_CRON` | 控制备份作业计划的 cron 表达式 | `*/30 * * * *` |
| `KRAWL_BACKUPS_ENABLED` | 启用数据库转储作业的布尔值 | `true` |
| `KRAWL_DATABASE_RETENTION_DAYS` | 数据库数据保留天数 | `30` |
| `KRAWL_HTTP_RISKY_METHODS_THRESHOLD` | 危险 HTTP 方法检测阈值 | `0.1` |
| `KRAWL_VIOLATED_ROBOTS_THRESHOLD` | robots.txt 违规阈值 | `0.1` |
| `KRAWL_UNEVEN_REQUEST_TIMING_THRESHOLD` | 计时变异系数阈值 | `0.5` |
| `KRAWL_UNEVEN_REQUEST_TIMING_TIME_WINDOW_SECONDS` | 请求计时分析的时间窗口（秒） | `300` |
| `KRAWL_USER_AGENTS_USED_THRESHOLD` | 检测多 User-Agent 的阈值 | `2` |
| `KRAWL_ATTACK_URLS_THRESHOLD` | 攻击 URL 检测阈值 | `1` |
| `KRAWL_INFINITE_PAGES_FOR_MALICIOUS` | 向恶意 IP 提供无限页面 | `true` |
| `KRAWL_MAX_PAGES_LIMIT` | 爬虫最大页面限制 | `250` |
| `KRAWL_BAN_DURATION_SECONDS` | 被限速 IP 的封禁时长（秒） | `600` |
例如
```
# 设置 canary token
export CONFIG_LOCATION="config.yaml"
export KRAWL_CANARY_TOKEN_URL="http://your-canary-token-url"
# 设置页面范围 (min,max 格式)
export KRAWL_LINKS_PER_PAGE_RANGE="5,25"
# 设置 analyzer 阈值
export KRAWL_HTTP_RISKY_METHODS_THRESHOLD="0.2"
export KRAWL_VIOLATED_ROBOTS_THRESHOLD="0.15"
# 设置自定义 dashboard 路径
export KRAWL_DASHBOARD_SECRET_PATH="/my-secret-dashboard"
```
带环境变量的 Docker 运行示例：
```
docker run -d \
-p 5000:5000 \
-e KRAWL_PORT=5000 \
-e KRAWL_DELAY=100 \
-e KRAWL_CANARY_TOKEN_URL="http://your-canary-token-url" \
--name krawl \
ghcr.io/blessedrebus/krawl:latest
```
## 使用 Krawl 封禁恶意 IP
Krawl 使用基于信誉的系统对攻击者 IP 地址进行分类。每隔五分钟，Krawl 会将识别出的恶意 IP 导出到 `malicious_ips.txt` 文件中。
该文件既可以从 Docker 容器挂载到另一个系统，也可以通过 `curl` 直接下载：
```
curl https://your-krawl-instance/
/api/download/malicious_ips.txt
```
此文件支持在各种平台上自动阻止恶意流量。您可以用它来更新以下平台的防火墙规则：
* [OPNsense 和 pfSense](https://www.allthingstech.ch/using-opnsense-and-ip-blocklists-to-block-malicious-traffic)
* [RouterOS](https://rentry.co/krawl-routeros)
* [IPtables](plugins/iptables/README.md) 和 [Nftables](plugins/nftables/README.md)
* [Fail2Ban](plugins/fail2ban/README.md)
## IP 信誉
Krawl [使用分析近期流量的任务来构建并持续更新 IP 信誉](src/tasks/analyze_ips.py)评分。它会定期运行，并根据多种行为指标评估每个活跃 IP 地址，将其分类为攻击者、爬虫或普通用户。阈值完全可自定义。
分析包括：
- **危险 HTTP 方法使用**（例如 POST、PUT、DELETE 比例）
- **Robots.txt 违规**
- **请求计时异常**（突发或不规则模式）
- **User-Agent 一致性**
- **攻击 URL 检测**（例如 SQL 注入、XSS 模式）
每个信号都会贡献到一个加权评分模型，该模型会分配一个信誉类别：
- `attacker` (攻击者)
- `bad_crawler` (恶意爬虫)
- `good_crawler` (良好爬虫)
- `regular_user` (普通用户)
- `unknown` (数据不足)
生成的评分和指标存储在数据库中，供 Krawl 用于驱动仪表盘、信誉跟踪以及自动缓解操作（如 IP 封禁或防火墙集成）。
## 转发 Server 头
如果 Krawl 部署在 NGINX 等代理之后，应使用以下代理配置转发 **server header**：
```
location / {
proxy_pass https://your-krawl-instance;
proxy_pass_header Server;
}
```
## 更多文档
| 主题 | 描述 |
|-------|-------------|
| [API](docs/api.md) | Krawl 用于 IP 数据、信誉和地理位置的外部 API |
| [Honeypot](docs/honeypot.md) | 蜜罐页面全览：虚假登录、目录列表、凭证文件、SQLi/XSS/XXE/命令注入陷阱等 |
| [Reverse Proxy](docs/reverse-proxy.md) | 如何将 Krawl 部署在 NGINX 之后或使用诱饵子域名 |
| [Database Backups](docs/backups.md) | 启用并配置自动数据库转储作业 |
| [Canary Token](docs/canary-token.md) | 通过 canarytokens.org 设置外部告警触发器 |
| [Wordlist](docs/wordlist.md) | 自定义虚假用户名、密码和目录列表 |
| [Dashboard](docs/dashboard.md) | 访问并探索实时监控仪表盘 |
## 免责声明
## Star History
标签：AMSI绕过, BOF, CISA项目, Cobalt Strike, Docker, Helm, IP信誉, IP封禁, Python, Web蜜罐, 伪造凭据, 低交互蜜罐, 反爬虫, 威胁检测, 子域名突变, 安全防御评估, 密码管理, 攻击诱捕, 无后门, 欺骗防御, 漏洞模拟, 网络安全, 蜜罐, 证书利用, 请求拦截, 逆向工具, 配置审计, 金丝雀令牌, 隐私保护
