jclee941/blacklist

# Blacklist 服务管理      ## 一句话简介 · One-liner 这是一个基于 Python 的集成管理平台，从多个外部威胁情报源收集、规范化 IP、域名和 URL，整合到中央黑名单后，自动部署到 Fortinet 等外部安全设备中。它以 Jinja2 Web 控制台、REST API 和 WebSocket 实时通道作为统一入口。 一个 Python 平台，聚合外部威胁情报源，将条目规范化至中央黑名单，并通过 REST API 和 WebSocket 将生成的地址对象推送到 Fortinet 类设备，通过 Jinja2 Web 控制台对外提供服务。 ## 状态 · 运营概览 | 项目 / Item | 值 / Value | 备注 / Notes | | --- | --- | --- | | 默认端口 / Default port | `2542` | 通过 `PORT` 环境变量修改 | | 默认 ENV / Default env | `development` | 切换至 `ENV=production` | | Python | `3.11+` | `pyproject.toml` 中的 `target-version = "py311"` | | 容器 / Container | Docker + Compose | `deploy/docker-compose.yml` | | 环境变量文件 / Env file | `deploy/.env` | Compose 自动注入 | | 本地入口 / Local entry | `app/run_app.py` | `python app/run_app.py` | | 容器入口 / Container entry | `app/entrypoint.sh` | 在 `app/Dockerfile` 中调用 | | 部署前验证 / Pre-deploy check | `app/deployment_validation.py` | `make verify` | | 行长度 / Line length | 120 | Ruff | | 结构化日志 / Structured logging | `app/utils/structured_logging.py` | JSON 输出 | | 日志轮转 / Log rotation | `app/utils/log_rotation_manager.py` | 基于大小/时间策略 | | 生产就绪 / Production-ready? | 运营验证阶段 | 内部 PoC → 逐步推广 | ## 简明流程 · 运营流程 1. **收集 (Collection)** — 定期或手动从外部威胁情报源获取 IP / Domain / URL 条目。 (`app/core/routes/api/collection/`) 2. **规范化 (Normalization)** — `app/core/routes/api/blacklist/core.py` 对条目进行格式和重复检查后，将其合并到中央黑名单。 3. **管理 (Management)** — `app/core/routes/api/blacklist/management.py` 和 `batch.py` 处理批量添加、删除和 TTL 过期。 4. **部署 (Deployment)** — `app/core/routes/api/fortinet/core.py` 将地址对象推送到 Fortinet 设备。 5. **监控 (Observability)** — `app/core/monitoring/` 中的指标和错误计数器以及 `dashboard.html` 负责状态可视化，并通过 WebSocket 发送通知。 6. **认证 (Auth)** — `app/core/auth/` 中的 JWT/装饰器/中间件控制所有路由的授权。 英文摘要：从情报源收集 → 规范化并合并到中央黑名单 → 结合 TTL 进行批量管理 → 推送到 Fortinet → 通过指标/仪表盘监控 → 在整个技术栈中强制执行认证。 ## 包内容 · 组件构成 | 领域 / Area | 路径 / Path | 角色 / Role | | --- | --- | --- | | App bootstrap | `app/run_app.py`, `app/entrypoint.sh`, `app/Dockerfile` | 本地/容器执行入口 | | 部署前检查 | `app/deployment_validation.py` | 部署前环境与机密验证 | | Core | `app/core/app.py`, `app/core/config.py`, `app/core/dashboard.py`, `app/core/testing_app.py` | 应用工厂、配置与仪表盘聚合 | | Auth | `app/core/auth/` | JWT 签发/验证，`@require_*` 装饰器，请求中间件 | | Monitoring | `app/core/monitoring/` | 缓存、错误和系统指标收集器 | | Web routes | `app/core/routes/web_routes.py` | Jinja2 页面路由 | | API routes | `app/core/routes/api_routes.py`, `app/core/routes/api/` | REST API blueprint 注册 | | Collection API | `app/core/routes/api/collection/` | 源注册、凭证、同步、触发器和历史 | | Blacklist API | `app/core/routes/api/blacklist/` | 合并、批处理、管理和系统状态 | | Fortinet API | `app/core/routes/api/fortinet/core.py` | 设备注册与地址对象部署 | | Proxy / WS | `app/core/routes/proxy_routes.py`, `app/core/routes/websocket_routes.py`, `app/core/routes/system_routes.py` | 代理、实时通道和系统 endpoint | | Templates | `app/templates/`, `app/templates/monitoring/dashboard.html` | 登录、主页、收集、集成、会话、设置和仪表盘 UI | | Utils | `app/utils/structured_logging.py`, `app/utils/log_rotation_manager.py` | JSON 日志与日志轮转 | ## 首选阅读文件 · 先读这部分 1. `app/run_app.py` — 本地运行和应用工厂入口。 2. `app/core/config.py` — 环境变量、默认端口和 ENV 模式定义。 3. `app/core/app.py` — blueprint 注册顺序和中间件链。 4. `app/core/auth/decorators.py` — 路由保护模式和权限矩阵。 5. `app/core/routes/api/collection/sync.py` — 威胁情报同步核心逻辑。 6. `app/core/routes/api/blacklist/core.py` — 合并与规范化策略。 7. `app/core/routes/api/fortinet/core.py` — Fortinet 推送协议。 8. `app/deployment_validation.py` — 部署前的检查场景。 9. `Makefile` — 日常运营命令集合。 10. `AGENTS.md` (根目录) — 代码库运营规约。 ## API 与入口点 · Endpoint ### Web 控制台 (Jinja2) | Path | Template | 描述 / Description | | --- | --- | --- | | `/` | `app/templates/index.html` | 登录后的主仪表盘 | | `/collection` | `collection.html` | 收集任务与源状态 | | `/collection/logs` | `collection_logs.html` | 收集日志流 | | `/integrations` | `integrations.html` | Fortinet 等外部系统连接 | | `/sessions` | `sessions.html` | 活动会话/token 管理 | | `/settings` | `settings.html` | 环境、账户和 TTL 设置 | | `/monitoring/dashboard` | `monitoring/dashboard.html` | 指标与错误可视化 | ### REST API (blueprint: `app/core/routes/api/`) | Prefix | 模块 / Module | 角色 / Role | | --- | --- | --- | | `/api/auth` | `auth_routes.py` | 登录、token 刷新和登出 | | `/api/analytics` | `analytics.py` | 聚合与报告 | | `/api/dashboard` | `dashboard_api.py` | 仪表盘摘要卡片 | | `/api/database` | `database_api.py` | 数据库状态与迁移触发 | | `/api/migration` | `migration.py` | schema 迁移 | | `/api/settings` | `settings_api.py` | runtime 配置查询/修改 | | `/api/system` | `system_api.py` | 健康、信息与模式 | | `/api/core` | `core_api.py` | 核心功能网关 | | `/api/error-metrics` | `error_metrics_api.py` | 错误计数器暴露 | | `/api/fortinet` | `fortinet_register.py` | Fortinet 设备注册与注销 | | `/api/ip-management` | `ip_management_helpers.py` | IP 辅助工具 | | `/api/monitoring/metrics` | `monitoring/metrics.py` | 指标暴露（Prometheus 友好） | | `/api/collection/*` | `collection/*.py` | 源、凭证、同步、触发、历史与状态 | | `/api/blacklist/*` | `blacklist/*.py` | 合并、批处理、管理与系统 | ### 实时通信 | Endpoint | Module | 备注 | | --- | --- | --- | | WebSocket `/ws/*` | `app/core/routes/websocket_routes.py` | 推送收集进度与部署结果 | ## 快速开始 · 快速上手 ### 1. 前置条件 / Prerequisites - Python 3.11+ - Docker / Docker Compose（如需容器执行） - `deploy/.env`（由 Compose 自动加载） ### 2. 本地直接运行 / Local (no container) ``` git clone blacklist-service cd blacklist-service python -m venv .venv source .venv/bin/activate pip install -r app/requirements.txt cp deploy/.env.example deploy/.env # 필요 시 시크릿 채우기 export PORT=2542 export ENV=development python app/run_app.py # → http://localhost:2542 ``` ### 3. 容器运行 / Docker Compose ``` make setup-hooks # 1회: pre-commit + husky make dev # 빌드 + 핫리로드 개발 환경 make dev-no-build # 기존 이미지로 빠르게 기동 make dev-prod # 운영 모드에 가까운 빌드 make logs # tail 로그 make health # 헬스 체크 ``` ### 4. 部署前验证 / Pre-deploy verification ``` make verify # 전체 검증 make verify-lint # Ruff make verify-types # mypy make verify-secrets # 시크릿 누출 점검 make verify-pre-commit make verify-quick make verify-all ``` ### 5. 发布 / Release ``` make release-dry # 시뮬레이션 (CHANGELOG, VERSION 확인) make release # VERSION bump + 커밋 + 태그 ``` ## 配置 · 环境设置 `.env` 中的主要键值（实际键值列表以 `app/core/config.py` 作为 SSoT）： | Key | 默认值 / Default | 描述 / Description | | --- | --- | --- | | `ENV` | `development` | `development` / `production` | | `PORT` | `2542` | Web 监听端口 | | `DATABASE_URL` | (env) | 中央黑名单存储库 | | `JWT_SECRET` | (生产环境必填) | `app/core/auth/jwt_service.py` | | `FORTINET_BASE_URL` | (env) | Fortinet API endpoint | | `FORTINET_API_TOKEN` | (必填) | Fortinet 认证 token | | `LOG_LEVEL` | `INFO` | 结构化日志级别 | | `LOG_ROTATE_MAX_BYTES` | `10485760` | 日志轮转阈值 | | `LOG_ROTATE_BACKUPS` | `10` | 保留世代数 | ## 命令参考 · Make 命令 | Target | 目的 / Purpose | | --- | --- | | `make help` | 输出可用的 target 及说明 | | `make setup-hooks` | 安装 pre-commit + husky + commit-msg 钩子 | | `make dev` | 启动开发环境（构建 + 热重载） | | `make dev-no-build` | 使用现有镜像快速启动 | | `make dev-prod` | 构建生产模式（无覆盖） | | `make dev-app` | 仅重启 app 服务（快速迭代） | | `make build` | 构建镜像 | | `make up` / `make down` | 启动/停止 Compose | | `make logs` | tail 日志 | | `make restart` | 重启 | | `make health` | 健康检查 | | `make clean` | 清理本地产物 | | `make test` | pytest（unit / integration / security / db / api 标记） | | `make deploy` | 部署序列 | | `make verify` / `verify-lint` / `verify-types` / `verify-secrets` / `verify-pre-commit` / `verify-quick` / `verify-all` | 验证集合 | | `make release` / `make release-dry` | 发布（VERSION + CHANGELOG + tag） | ## 本地开发 · 本地开发 - **Lint**: `ruff check app/`（行长 120，`py311`）。 - **类型**: `mypy` (`mypy.ini`)。 - **测试**: `pytest`（基于 `app/tests`，标记：`unit` / `integration` / `security` / `db` / `api`）。 - **提交**: Conventional Commits，通过 `commitlint.config.js` 强制执行。 - **Pre-commit**: Python lint/类型/机密扫描；前端使用 `frontend/` 中的 husky 执行 ESLint / Prettier。 - **热重载**: `make dev` 启用卷挂载（volume mount）+ 应用自动重启。 ## 架构 · 架构 ### 分层概述 | Layer | 职责 / Responsibility | 核心模块 | | --- | --- | --- | | Edge | HTTP/WS 接收，认证/授权，速率限制 | `app/core/auth/middleware.py`, `app/core/routes/web_routes.py` | | UI | Jinja2 页面渲染 | `app/templates/`, `monitoring/dashboard.html` | | API | REST endpoint，请求验证 | `app/core/routes/api_routes.py`, `api/*` | | Domain | 收集、黑名单和 Fortinet 领域逻辑 | `api/collection/`, `api/blacklist/`, `api/fortinet/` | | Infra | 数据库，外部 HTTP，指标 | `core/monitoring/`, `app/utils/`, `core/config.py` | | Ops | 部署、验证、日志轮转 | `deployment_validation.py`, `utils/log_rotation_manager.py` | ### 请求流程 · 典型流程 1. 客户端调用 `POST /api/collection/{id}/sync`。 2. `web_routes` → `middleware` 验证 JWT（`auth/decorators.py`）。 3. `collection/sync.py` 从 `collection/credentials.py` 加载源凭证。 4. 获取外部信息流并规范化 → 合并至 `blacklist/core.py`。 5. 结果事件记录至 `monitoring/metrics.py`，由 `websocket_routes.py` 推送给订阅者。 6. `fortinet/core.py` 将变更部署至 Fortinet → 将结果保存至 `/api/fortinet` 历史记录。 7. `dashboard_api.py` 将摘要反映到 `/monitoring/dashboard`。 ## 测试 · 测试 ``` # 全部 pytest # 按 marker pytest -m unit pytest -m integration # 외부 서비스 필요 pytest -m security pytest -m db pytest -m api ``` 将应用 `pyproject.toml` 中的 `addopts = "-v --tb=short"`。新测试请遵循 `app/tests/` 下的 `test_*.py` 命名约定。 ## 生产就绪 · 运营准备度 | 领域 / Area | 状态 / Status | | --- | --- | | 认证 / Auth | JWT + 装饰器/中间件已应用 | | 日志 / Logging | JSON 结构化 + 轮转 | | 指标 / Metrics | 暴露缓存、错误和系统计数器 | | 部署 / Deploy | 基于 Compose，提供验证脚本 | | 文档 / Docs | 本 README + `CHANGELOG.md` + `AGENTS.md` | | 运营阶段 / Stage | 内部 PoC → 逐步推广（Production-ready：验证中） | ## 维护者 · 负责人 - `OWNERS` 文件是代码所有权和审查者的 SSoT。 - 运营/发布决策由 `OWNERS` 中的 primary / secondary 组做出。 - 外部贡献流程遵循 `CONTRIBUTING.md`。 ## 更多文档 · 补充文档 | 文档 / Doc | 路径 / Path | 内容 / Contents | | --- | --- | --- | | 变更日志 / Changelog | `CHANGELOG.md` | 发行说明，迁移指南 | | 贡献指南 / Contributing | `CONTRIBUTING.md` | PR 流程，编码规约，审查 SLA | | 代码库规约 / Codebase rules | `AGENTS.md`（根目录） | 代理/审查者运营规则 | | 应用模块规约 / App rules | `app/AGENTS.md` | `app/` 目录下规约 | | 核心规约 / Core rules | `app/core/AGENTS.md` | 核心层规约 | | 许可证 / License | `LICENSE` | 许可证全文 | | 版本 / Version | `VERSION` | 当前语义版本 | | 健康检查 | `GET /api/system/health`（路由：`system_api.py`） | liveness/readiness | ## 帮助 · 帮助 - Bug 报告/功能请求：请使用仓库的 issue 追踪器。 - 安全问题：请私下联系 `OWNERS` 中的负责人。 - 内部聊天：在运营团队频道中搜索 `blacklist-service`。 - 详细运营程序：请遵循 `CHANGELOG.md` 中的迁移条目和 `app/AGENTS.md` 中的 runbook。

标签：Docker, Python, REST API, 威胁情报, 安全规则引擎, 安全运营, 安全防御评估, 开发者工具, 扫描框架, 无后门, 版权保护, 自定义脚本, 自定义请求头, 请求拦截, 逆向工具, 黑名单管理