brandontroidl/Propolis

GitHub: brandontroidl/Propolis

Propolis 是一个单节点蜜罐威胁情报报告工具，将蜜罐日志经人工审核后转化为滥用报告和防火墙黑名单 feed。

Stars: 1 | Forks: 0

# Propolis Propolis 将蜜罐和传感器的日志转化为经过人工审核的威胁情报供应商报告，以及一个防火墙黑名单 feed。它会持续跟踪同一主机上运行的蜜罐日志，对每个源 IP 进行评分，随着时间推移使该分数衰减，将所有候选 IP 置于操作员审核队列之后，仅在明确批准后向 AbuseIPDB、DShield 和 OTX 提交滥用报告，并发布双层黑名单。单节点，单操作员，SQLite，无 broker，无 cluster。 在 [PolyForm Noncommercial License 1.0.0](LICENSE.md) 下提供源码：可免费用于个人、家庭实验室、研究、教育以及非营利或政府用途；商业使用需要单独的授权。

Propolis operator dashboard — top attackers, scored, decayed, and tiered

## Pipeline ``` flowchart TD sensors["honeypot sensors
Cowrie / Heralding / ADBHoney / Redis / catch-all"] sensors -->|log lines| ingest["ingest — Tailer
offset-tracked"] ingest --> parsers["parsers
PARSER_REGISTRY (13 sources)"] parsers --> sanitize["sanitize
clean_for_log at parse time"] sanitize --> scoring["scoring
weighted signal + half-life decay"] scoring --> gate["scoring gate
is_reportable + tier"] gate -->|reportable| review["review queue
operator approve / reject / snooze"] review -->|approve| dispatch["ReportDispatcher
per-vendor gatekeeper"] dispatch --> vendors["AbuseIPDB / DShield / OTX"] scoring -.->|scheduler reads approved + tiered| feed["feed builder
plain / ipset / nft × 2 tiers"] feed -.-> firewall["public blocklist feed"] ``` 两个下游分支是相互独立的。Web UI 中的操作员批准操作会驱动调度器进行供应商提交；一个独立的 feed 发布调度器会按照自身的间隔构建并发布黑名单。分析循环仅负责跟踪、解析、评分和入队——它既不会触发供应商报告，也不会触发 feed 构建。 ## 核心特性 人工审批门是整个设计的核心。自动报告原始蜜罐命中记录会将可伪造的单包噪音提交给供应商，并导致报告者账号受到处罚；Propolis 会捕获所有内容，并且仅报告操作员批准的内容。仅 SYN 的事件和 UDP 源事件在提交前会被丢弃（未完成的握手意味着源是不可验证的，且通常是伪造的）；交叉验证门（`is_reportable`：至少 2 个事件，至少 2 个不同的类别，至少 1 个 TCP 认证的蜜罐事件）和审核队列会捕获其余内容。已知扫描器会通过将其 IP 范围放入操作员白名单来抑制；这里没有自动的扫描器分类器。 分数基于 21600 秒（6 小时，这是操作员唯一可调整的评分参数）的半衰期进行衰减，上限为 100。衰减在写入和读取分数时都会应用，因此处于静默状态的 IP 会自动从仪表板、报告门和 feed 中移除，而无需等待新活动。 发布的 feed 仅基于已批准的、分级的 IP 构建，并对误伤保持保守态度。默认情况下，每个条目都是一个 `/32` 主机路由；只有当 `/24` 中的所有 256 个主机都被独立列出时，它才会被折叠为单个条目，这样单个嘈杂的主机就不会导致其邻近主机被黑洞化。RFC1918 和保留地址范围在构建时会被排除，并在发布前重新验证。两个权重层级——一个激进列表（90 天过期）和一个标准超集（30 天过期）——会渲染为纯文本（pfBlockerNG/pf）、ipset 和 nftables 格式：包含六个防火墙文件以及 `manifest.json` 和 `delisted.txt`。 设计上为单节点、单操作员。没有高可用性，没有 clustering，没有多主机日志传输，也没有消息 broker；该 feed 仅支持 IPv4。如果部署规模超出了单机的承载能力，也就超出了此工具的适用范围。这些都是预设的边界，记录在 [docs/architecture/overview.md](docs/architecture/overview.md) 中。 ## 操作员控制台 整个工作流都位于绑定到本地回环地址的 Web 控制台中——捕获审核、供应商报告和发布的 feed 都位于人工审批门之后。
Review queue
Review queue — weight-ordered candidates; nothing is reported or blocked until an operator approves.		 Reporting vendors
Vendors — each reporting destination with its enable state and score/confidence gate.
Published feed
Feed — two-tier blocklist build status, entry counts, and the manifest hash.		 Event activity
Activity — event volume per day across the sensors.
Top attacker usernames
Credentials — aggregate login-attempt counts; passwords are dropped at parse time, never stored.		 Audit trail
Audit — the immutable decision and vendor-submission trail.
这些截图来自使用文档范围 IP（192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24）作为种子数据的本地演示——未显示任何真实主机。 ## 环境要求 - 带有 systemd 的 Linux，以及 Python 3.11 或更高版本。 - SQLite（内置的标准库 `sqlite3` 模块；无需单独的数据库服务器）。 - 可以拉取 URL 或文件黑名单的防火墙：pfSense/pfBlockerNG、pf 表、ipset 或 nft sets。 - 至少一个 TCP 认证的蜜罐。交叉验证门在任何 IP 变得可报告之前，需要一个真实的 TCP 认证蜜罐事件，因此一个**仅限全捕获**的部署在设计上会产生一个空的 feed。内置的全捕获传感器提供了广泛的端口覆盖；Cowrie (SSH/Telnet) 则是将连接转化为值得报告内容的关键。 ## 快速开始 这是面向开发者的本地检出版本。要进行加固的 systemd 部署，请遵循 [docs/operations/deploy.md](docs/operations/deploy.md)。 ``` # 1. 将 package（可编辑模式）安装到 virtualenv 中。这将安装一个 console script：propolis。 python3.11 -m venv .venv && . .venv/bin/activate pip install -e . # 2. 复制 example config，并将 log-source 路径指向你的 honeypots。 cp config/config.example.yaml config/config.yaml $EDITOR config/config.yaml # 3. 创建或升级 schema，然后确认其处于 Alembic head # （必须提供 --url；如果 DB 落后于 head，--check 将以非零状态退出）。 propolis db migrate --url sqlite:///$PWD/propolis.db propolis db migrate --check --url sqlite:///$PWD/propolis.db # 4. 运行 reporter：analysis loop、purge scheduler、feed-publish scheduler # 以及 operator web UI，所有这些都运行在同一个进程中（必须提供 --config）。 propolis run --config config/config.yaml ``` Web UI 默认绑定 `127.0.0.1:8000`（`web.bind`/`web.port`）；在启动时会拒绝通配符绑定。使用 `propolis web hash-password` 生成操作员密码哈希，并将其粘贴到 `web.auth.password_hash` 中。就绪探针仅在数据库处于最新状态时才报告就绪： ``` curl -s http://127.0.0.1:8000/readyz # -> {"status":"ready","db":"at_head"} ``` 供应商 API 密钥和 feed 推送 token 永远不会从 YAML 中读取——它们来自于环境变量（`PROPOLIS_ABUSEIPDB_API_KEY`、`PROPOLIS_DSHIELD_API_KEY`、`PROPOLIS_DSHIELD_USER_ID`、`PROPOLIS_OTX_API_KEY`、`PROPOLIS_WEB_SESSION_SECRET`、`PROPOLIS_FEED_PUSH_TOKEN`）。配置使用 Pydantic 的 `SecretStr` 进行类型化，加载器会剥离在文件中发现的任何 `vendors..api_key`，因此留在 YAML 中的真实密钥会在加载时被拒绝或丢弃。本仓库中没有提交任何密钥和真实的 IP 地址。 请单独安装蜜罐。`deploy/install/install_cowrie.sh` 会安装 Cowrie（feed 所需的 TCP 认证环节）；`deploy/install/install_heralding.sh` 和 `deploy/install/install_catchall.sh` 会安装可选的 Heralding 和内置的全捕获传感器。全捕获传感器作为一个独立的 systemd unit（`propolis-sensor-catchall.service`）发布，在单独的非特权 `catchall` 用户下运行，没有数据库句柄，也没有任何密钥。 ## 文档 - [docs/architecture/](docs/architecture/overview.md) — 系统级设计：拓扑结构、权限边界、映射到源模块的端到端 pipeline、C4 视图，以及 [docs/architecture/adr/](docs/architecture/adr/) 下的决策记录。 - [docs/reference/](docs/reference/configuration.md) — 各子系统参考：[CLI](docs/reference/cli.md)、[配置](docs/reference/configuration.md)、评分、解析器、持久化、报告、feed 和 Web 内部机制。 - [docs/operations/](docs/operations/deploy.md) — 运维手册：部署、拓扑和 systemd、故障排除、feed 使用、密钥和密钥轮换、从备份恢复、事件响应以及解除名单申诉。 - [docs/security/](docs/security/stride.md) — STRIDE 威胁模型和安全架构。 - [docs/compliance/](docs/compliance/dpia.md) — 数据保留、合法利益依据、DPIA/RoPA 以及已发布 feed 的解除名单流程。 ## 许可证 在 [PolyForm Noncommercial License 1.0.0](LICENSE.md) 下提供源码。可免费用于个人、家庭实验室、研究、教育以及非营利或政府用途。商业使用——即任何您或您的雇主通过它赚钱的行为——需要单独的授权；有关条款，请参阅 `LICENSE.md`。
标签：SQLite, 威胁情报, 安全运营, 开发者工具, 扫描框架, 蜜罐, 证书利用, 逆向工具, 防火墙黑名单