tolgaakkapulu/cybercavalry

## ✨ 概述 CYBERCavalry 是一个功能齐全的黑名单管理平台，专为 SOC 和网络团队设计。它可以接收来自您自有工具（SIEM、蜜罐、防火墙告警）或外部情报源的 IP / 文件哈希指标，将每个指标与 **AbuseIPDB** 和 **VirusTotal** 进行交叉验证，根据可信度将其划分到短期（24小时）和长期（30天）发布组中，并通过简单的 HTTP API 将生成的黑名单提供给您的执行节点。 所有操作都在一个简洁的 Web UI 背后运行，具备基于角色的访问控制、活动审计、syslog 转发，以及针对配额和 API 速率异常的完整告警机制。 ## 🚀 功能

### 🎯 黑名单管理 - **IP 黑名单**，具有滚动的 24 小时和长期 30 天分组 - **哈希黑名单**（MD5 / SHA-1 / SHA-256 / SHA-512），用于恶意软件 IOC - **白名单**，具备 CIDR 重叠检测 - **命中追踪**，记录每个 IP 的滚动报告次数 - **自动升级** — 根据 N 天窗口期内的可配置阈值，将多次违规者从 24 小时升级至 30 天 - **置顶条目** — 管理员覆盖操作，在自动重新评估后依然保留	### 🧠 威胁情报 - 集成 **AbuseIPDB**，支持基于评分的分组分配 - 集成 **VirusTotal**，支持恶意引擎阈值设定 - **多密钥轮换** — 为每个提供商配置 N 个密钥，在配额耗尽时透明故障转移 - **自动评分** — 在接收数据时及计划的批量重新评分时执行 - **清理规则** — 根据评分区间和存在时间进行保留
### 🔔 告警与可观测性 - 针对配额耗尽（AbuseIPDB / VirusTotal）的**邮件告警** - 针对每个调用方 API 速率限制滥用的**邮件告警** - **活动日志**，记录每次配置变更的新旧差异 - **Syslog 转发** — 将 `cybercavalry.log`、`error.log`、`access.log` 流镜像到 RFC 3164 收集器 - **可配置的冷却时间**，避免操作人员因同一事件被重复呼叫	### 🔐 安全与访问 - **LDAP** 身份验证（支持多个 base-DN） - **基于角色的访问控制**（管理员 / 操作员 / 查看者） - **会话超时**及失败尝试后的锁定机制 - **API token**，支持基于 token 的源 IP 白名单 - **密码策略**引擎（长度、字符类别、轮换） - **CSP 安全的 UI** — 无内联 `on*` 处理器
### 📊 报告 - **仪表盘**，支持深色/浅色主题、品牌色、自定义 Logo - **PDF 报告** — 活动摘要、分组明细 - **图表**，展示命中趋势、分组分布、热门报告者 - **自动刷新**仪表盘，支持可配置的轮询间隔	### 🔧 运维 - **备份调度器** — 具备保留策略的每日数据库快照 - **自动清理任务** — 清除过期条目 - **基于 APScheduler** 的进程内后台任务（核心功能无需依赖 Celery / Redis） - 适用于气隙环境的**离线安装包**

## 📸 截图 ## 🏗️ 架构 **组件布局** ``` CYBERCavalry/ ├── cybercavalry/ # Django project package (settings, urls, wsgi) │ ├── settings/base.py # LOGGING, INSTALLED_APPS, middleware chain │ ├── log_filters.py # Below-error filter for syslog / file split │ └── urls.py ├── apps/ │ ├── accounts/ # Auth, LDAP, roles, sessions, API tokens │ ├── api/ # Public HTTP API (report + consume endpoints) │ ├── blacklist/ # IP entries, AbuseIPDB service, promotion logic │ ├── hashlist/ # Hash entries, VirusTotal service │ ├── whitelist/ # CIDR / IP allowlist with overlap detection │ ├── dashboard/ # Landing page, charts, quick actions │ ├── reports/ # PDF generator, activity exports │ └── settings_app/ # Setting model, cache, alert & quota services ├── templates/ # Django templates (dark/light theme aware) ├── static/ # CSS, JS, brand assets ├── deploy/ # Linux/Windows install script, systemd unit, wheels bundle └── manage_server.py # Dev helper: setup / run / migrate / seed ``` ## 🧰 技术栈 | 层级 | 选择 | 原因 | | --- | --- | --- | | 语言 | Python 3.10+ | Django 4.2 LTS 兼容窗口 | | 框架 | Django 4.2 LTS | 长期安全反向移植 | | 数据库 | SQLite (开发) / PostgreSQL (生产) | 零配置开发，标准生产配置 | | 前端 | Alpine.js + 原生 CSS | 无需构建步骤，CSP 友好 | | 图表 | Chart.js | 占用空间小，无需 CDN | | 认证 | Django sessions + LDAP (ldap3) | 兼容现有企业目录 | | 调度器 | APScheduler (进程内) | 核心功能无需外部 broker | | 模板 | Django templates | 服务端渲染页面，易于导出 PDF | | PDF | ReportLab | 纯 Python 实现，无需无头浏览器 | ## 📋 前置条件 - **Python** 3.10、3.11 或 3.12 - **pip** 和 `venv` - **git** - （仅生产环境）**PostgreSQL** 12+、**SMTP 中继**、**Nginx / Traefik** 或带有 TLS 的独立 Gunicorn - （可选）用于企业 SSO 的 **LDAP** 服务器 - （可选）**AbuseIPDB** 和 **VirusTotal** API 密钥——平台在没有它们的情况下也能运行，但会禁用自动评分功能 ## ⚙️ 安装说明 每个平台一个脚本，每个脚本一条命令。完整的操作指南（包括前置条件和离线 wheel 安装包）位于 [`deploy/README.md`](deploy/README.md)。 **🐧 Linux — RHEL / Debian / Ubuntu** ``` sudo bash deploy/linux/setup.sh install # first time sudo bash deploy/linux/setup.sh update # in-place upgrade ``` 该脚本会自动检测您的发行版家族，并自动处理 `dnf`/`apt`、 `firewalld`/`ufw` 以及 SELinux（仅限 RHEL）。 **🪟 Windows Server 2019 / 2022, Windows 10 / 11** ``` powershell -ExecutionPolicy Bypass -File .\deploy\windows\setup.ps1 -Action install powershell -ExecutionPolicy Bypass -File .\deploy\windows\setup.ps1 -Action update ``` 两个平台在更新期间都会保留 `.env`、数据库、TLS 证书、日志和备份，并在进行任何更改之前写入回滚快照。 ### 快速开始 — 开发者 / 评估 对于在任何操作系统上进行本地开发，`manage_server.py` 会跳过完整的生产环境流程： ``` git clone https://github.com/tolgaakkapulu/CYBERCavalry.git cd CYBERCavalry python -m venv venv # Linux / macOS source venv/bin/activate # Windows PowerShell .\venv\Scripts\Activate.ps1 pip install -r requirements.txt cp .env.example .env # then fill in the secrets python manage_server.py setup # migrate + seed default admin + collectstatic python manage_server.py start # → https://127.0.0.1:8443 ``` 系统会自动生成默认管理员账户：**`admin` / `admin`** — 登录后请**立即**在您的个人资料下修改密码。接下来： 1. **设置 → 威胁情报** — 粘贴您的 AbuseIPDB / VirusTotal 密钥，点击 *Check Key* 2. **设置 → LDAP** *（可选）* — 连接您的目录，点击 *Test LDAP* 3. **设置 → 操作 → 邮件** — 配置 SMTP，点击 *Test SMTP* 4. **账户** — 根据需要添加操作员 / 查看者 5. **API token** — 为您的 SIEM / 蜜罐生成一个 token 以便 POST 报告 ## 🔧 配置 ### 环境变量（`.env`） | 变量 | 默认值 | 用途 | | --- | --- | --- | | `SECRET_KEY` | — | **必填。** Django 的加密密钥。使用 `python -c "import secrets; print(secrets.token_urlsafe(50))"` 生成 | | `DEBUG` | `False` | 生产环境中绝不能设为 `True` | | `ALLOWED_HOSTS` | `localhost,127.0.0.1` | 逗号分隔的主机名 | | `DATABASE_URL` | `sqlite:///cybercavalry.db` | 在生产环境中使用 `postgres://user:pass@host/db` | | `TIME_ZONE` | `UTC` | 例如 `Europe/Istanbul` | | `LANGUAGE_CODE` | `en-us` | UI 语言 | ### 运行时设置（Web UI） 大多数操作设置都位于 **设置** 页面中，并存储在数据库中（机密信息已加密）。重点功能：

通用 — 品牌、刷新间隔、时区

- `general.platform_name` / `general.platform_name_suffix` — 用于侧边栏的拆分品牌名称（例如 `CYBER` + 强调色的 `Cavalry`） - `general.brand_color` — 强调色（`#RRGGBB`） - `general.brand_logo`、`general.brand_login`、`general.brand_background` — 图片上传 - `general.dashboard_refresh_seconds` / `general.blacklist_refresh_seconds` — 自动轮询频率

LDAP — 企业目录

- `ldap.server_uri` — `ldaps://dc01.corp.tld:636` - `ldap.bind_dn` / `ldap.bind_password` — 服务账户 - `ldap.user_search_bases` — 一个或多个 base DN（换行分隔） - `ldap.user_filter` — 例如 `(sAMAccountName={username})`

威胁情报 — AbuseIPDB & VirusTotal

- `threat_intel.abuseipdb_api_key` — 一个或多个密钥（以逗号 / 换行分隔以进行轮换） - `threat_intel.abuseipdb_threshold_24h` — 当 IP 的置信度分数高于此值时进入 24 小时组（默认 `10`） - `threat_intel.abuseipdb_threshold_30d` — 30 天组的分数（默认 `80`） - `threat_intel.abuseipdb_promotion_threshold` + `_window_days` — 自动升级持续违规者（例如 *7 天内报告 3 次 → 30 天组*） - `threat_intel.virustotal_api_key` — 一个或多个密钥，以相同方式轮换 - `threat_intel.virustotal_detection_threshold` — 将哈希标记为恶意以保持其活跃状态的最少引擎数 - `_schedule_enabled` + `_schedule_interval` — 定期重新评分 - `_cleanup_*` — 针对陈旧、低分条目的保留规则

操作 — 告警、邮件、Syslog

- 邮件选项卡：SMTP 主机 / 端口 / 用户名 / 密码 / 发件人 / TLS - 告警 → 配额：阈值`、冷却时间、收件人列表（以 `;` 分隔） - 告警 → 速率限制：每个调用方的 RPM 阈值、告警邮件 - Syslog：主机 / 端口 / 协议、每个流的开关（活动 / 错误 / 访问）

安全

- `security.session_timeout` — 空闲超时分钟数 - `security.lockout_attempts` / `lockout_duration` — 登录失败退避策略 - API token：在 **账户 → API Tokens** 下管理，支持可选的源 IP 白名单

## 🛣️ HTTP API 两种身份验证模式，分别应用于不同的 endpoint： - **Token + 用户名** *(POST endpoint)* — 需要同时提供请求头 `Authorization: Token ` 和 `X-Username: `。该 token 必须属于该用户，用户必须具有 **API User** 角色，并且请求 IP 必须在“设置 → 源 IP”的白名单中。Token 由管理员在 **账户 → 用户管理** 下生成。 - **仅源 IP** *(GET endpoint)* — 无需 token 或用户名请求头。请求 IP 只需在白名单中即可。这允许防火墙、SIEM 和代理在无需管理凭证的情况下拉取当前黑名单。 | 方法 | 路径 | 认证 | 用途 | | --- | --- | --- | --- | | `GET` | `/api/status/` | Source IP | 健康检查 — 平台版本 + 计数 | | `POST` | `/api/report/ip/` | Token + Source IP | 报告 IP；自动评分并分组 | | `POST` | `/api/report/hash/` | Token + Source IP | 报告哈希 (MD5 / SHA-1 / SHA-256 / SHA-512) | | `GET` | `/api/blacklist/` | Source IP | 完整的活跃 IP 黑名单（两个组） | | `GET` | `/api/blacklist/24h/` | Source IP | 仅 24 小时组 | | `GET` | `/api/blacklist/30d/` | Source IP | 仅 30 天组 | | `GET` | `/api/hashlist/` | Source IP | 完整的活跃哈希黑名单 | **示例 — 从蜜罐报告 IP：** ``` curl -X POST https://blacklist.example.com/api/report/ip/ \ -H "Authorization: Token 9c1e0f...redacted" \ -H "X-Username: honeypot-01" \ -H "Content-Type: application/json" \ -d '{"ip": "X.X.X.X", "reason": "SSH brute force"}' ``` 响应： ``` { "status": "blacklisted", "cidr": "X.X.X.X/32", "group": "24h", "score": 87, "message": "New blacklist entry created." } ``` **示例 — 报告 SHA-512 哈希：** ``` curl -X POST https://blacklist.example.com/api/report/hash/ \ -H "Authorization: Token 9c1e0f..." \ -H "X-Username: edr-connector" \ -H "Content-Type: application/json" \ -d '{"hash": "9b71d224bd62f3785d96d46ad3ea3d73...", "type": "sha512", "reason": "Ransomware"}' ``` **示例 — 从您的防火墙拉取当前的 24 小时黑名单（无 token，强制执行 IP 白名单）：** ``` curl https://blacklist.example.com/api/blacklist/24h/ \ | jq -r '.entries[].cidr' > /etc/firewall/deny_24h.txt ``` 完整的 endpoint 架构（包括请求体、响应结构和错误代码）会在您登录后在 **账户 → API 文档** 下实时呈现，并且可以从同一页面导出为 PDF。 ## 🏭 生产部署 完整的指南 — 前置条件、离线 wheel 包、服务管理、更新流程、回滚 — 位于 [`deploy/README.md`](deploy/README.md)。概览： | 平台 | 运行器 | 服务 | 安装 / 更新程序 | |---|---|---|---| | RHEL 9.x · Debian 12+ · Ubuntu 22.04+ | gunicorn | systemd ([`cybercavalry.service`](deploy/linux/cybercavalry.service)) | [`deploy/linux/setup.sh install\|update`](deploy/linux/setup.sh) | | Windows Server 2019 / 2022 · Windows 10 / 11 | waitress | WinSW ([`cybercavalry-service.xml`](deploy/windows/cybercavalry-service.xml)) | [`deploy/windows/setup.ps1 -Action install\|update`](deploy/windows/setup.ps1) | 两个平台在更新期间都会保留 `.env`、数据库、TLS 证书、日志和备份；Linux 服务以非特权的 `cavalry` 用户身份运行，并启用了 `NoNewPrivileges` + `PrivateTmp` 加固。 **最小化生产环境检查清单：** - [ ] `DEBUG=False` - [ ] 使用 `secrets.token_urlsafe(50)` 生成的强 `SECRET_KEY` - [ ] `ALLOWED_HOSTS` 限制为实际的 FQDN - [ ] 使用 PostgreSQL（而非 SQLite）作为 `DATABASE_URL` - [ ] 在 `certs/` 目录中放置 TLS 证书（真实的 CA，而非捆绑的自签名开发证书） - [ ] 配置了 SMTP 并且 *Test SMTP* 通过 - [ ] 启用备份并将 `backups/` 存储在主机外 - [ ] 使用 LDAP（或其他 SSO）代替本地密码 - [ ] Syslog 转发指向您的 SIEM - [ ] API token 按照已记录的周期进行轮换 ## 🛡️ 安全 - 切勿提交您的 `.env`、`db.sqlite3`、`certs/*.pem` 或 `media/brand/` 下的任何内容 - API token 认证使用常量时间比较 - 机密设置（SMTP 密码、LDAP 绑定密码、API 密钥）在静态存储时使用由 `SECRET_KEY` 派生的密钥进行加密 - 请私下报告漏洞 — 切勿**公开**提交 issue ## 🗺️ 路线图 - [ ] Prometheus `/metrics` endpoint - [ ] 新黑名单条目的 Webhook 扇出 - [ ] 多租户工作区 - [ ] MISP 集成 - [ ] 更多威胁情报提供商 (Shodan、GreyNoise) ## 🤝 贡献 欢迎贡献。对于任何非同小可的更改，请先提交一个 issue，以便我们在范围上达成共识。 ``` # fork, 然后 git checkout -b feat/short-description # ... commit ... python manage.py test git push origin feat/short-description # open a PR ``` ## 🤝 致谢 本项目由开发者——负责指导安全、性能和设计决策——与 Anthropic 的 **[Claude](https://claude.ai)** 合作构建，Claude 作为结对编程伙伴参与了实现、重构和文档编写。 ## 📄 许可证 GNU General Public License v3.0 — 完整文本请参见 [`LICENSE`](LICENSE)。

**用 ❤️ 为希望黑名单系统能够直接正常运作的 SOC 和网络团队而构建。**

标签：Checkov, 测试用例, 逆向工具