mal0ware/Threatscope

# ThreatScope [](https://github.com/mal0ware/Threatscope/actions/workflows/ci.yml) [](https://www.python.org/downloads/) [](https://www.typescriptlang.org/) [](LICENSE) 实时威胁情报平台，摄取系统日志，运行基于机器学习的异常检测和确定性规则评估，并通过带有 WebSocket 推送的实时仪表板展示安全事件。 专为需要比原始日志文件更多功能但无法承担企业 SIEM 价格的场景设计。完全离线运行，无需任何外部依赖或 API 密钥。 ## 目录 - [架构](#architecture) - [检测能力](#detection-capabilities) - [技术栈](#tech-stack) - [快速开始](#quick-start) - [用法](#usage) - [API 参考](#api-reference) - [测试](#testing) - [安全态势](#security-posture) - [项目结构](#project-structure) - [桌面应用](#desktop-app) - [CI/CD](#cicd) - [许可证](#license) ## 架构 ``` ┌──────────────────────────┐ │ Data Sources │ │ auth.log syslog DNS │ └────────────┬─────────────┘ │ ┌────────────────▼────────────────┐ │ Log Collection Agent │ │ Watchdog file tailer with │ │ inode-aware rotation handling │ └────────────────┬────────────────┘ │ NormalizedEvent ┌────────────────▼────────────────┐ │ Async Event Bus (pub-sub) │ │ Bounded ring buffer (10K cap) │ │ Back-pressure on slow consumers │ └──┬─────────────┬──────────────┬─┘ │ │ │ ┌────────▼──┐ ┌──────▼──────┐ ┌───▼────────┐ │ Rule Engine│ │ ML Pipeline │ │ Subscribers│ │ Sliding │ │ Login IF │ │ SSE / WS │ │ windows, │ │ Network Z+IF│ │ clients │ │ thresholds │ │ DNS RF+heur │ │ │ └────────┬───┘ └──────┬──────┘ └────────────┘ │ │ ▼ ▼ ┌──────────────────────────────────────┐ │ SQLite + FTS5 (WAL) │ │ Events Alerts Rules Full-text │ └──────────────────┬───────────────────┘ │ ┌──────────────────▼───────────────────┐ │ FastAPI REST + WS │ │ /api/v1/events /alerts /stats │ │ /ws/events /api/v1/events/stream │ └──────────────────┬───────────────────┘ │ ┌──────────────────▼───────────────────┐ │ React Dashboard (Vite) │ │ Timeline Heatmap Network Graph │ │ Live Feed Alerts Top Sources │ └──────────────────────────────────────┘ ``` **数据流：** 日志文件由基于 watchdog 的收集器实时跟踪，并通过 inode 检测日志轮转。每行数据被路由到相应的解析器（认证、系统日志），输出 `NormalizedEvent` 冻结数据类。事件发布到基于有界环形缓冲区的内存异步事件总线。下游订阅者（ML 流水线、规则引擎、WebSocket/SSE 客户端）并发消费事件。检测结果生成告警并持久化到 SQLite。FastAPI 层提供带有全文搜索（FTS5）的 REST 端点，并通过 WebSocket 实时推送。 ## 检测能力 ### 基于机器学习的检测器 | 检测器 | 模型 | 工作原理 | |----------|-------|-------------| | **登录异常** | 孤立森林 | 从认证事件中提取时间和行为特征（小时、星期几、IP 频率、成功/失败比例）。基于 30 天滚动基线训练。异常分数归一化到 `[0.0, 1.0]`。 | | **网络流量** | Z 分数 + 孤立森林 | 维护流量快照的滚动基线（流入/流出字节、包计数、唯一 IP、端口熵）。每特征 Z 分数标记单个峰值；孤立森林捕捉 Z 分数无法识别的多维异常。 | | **DNS 分类** | 随机森林 + 启发式规则 | 特征向量包括 Shannon 熵、标签长度、数字比例、辅音比例、十六进制模式密度和点数。分类查询为 `NORMAL`、`TUNNELING` 或 `DGA`。启发式回退确保无需训练数据也能检测。 | ### 基于规则的检测器 | 规则 | 触发条件 | 严重性 | |------|-------------------|----------| | `BRUTE_001` | 同一 IP 在 5 分钟内失败 SSH 超过 10 次 | 高 | | `PRIV_001` | 同一用户在 3 分钟内先失败后成功执行 sudo | 严重 | | `SCAN_001` | 同一 IP 在 1 分钟内访问超过 50 个不同目标端口 | 中 | | `EXFIL_001` | 出站传输量高于基线 3 个标准差 | 高 | 规则使用滑动时间窗口并按来源 IP、用户名等键分组，触发后自动重置窗口。 ## 技术栈 | 层 | 技术 | 原因 | |-------|-----------|-----| | **后端** | Python 3.11+、FastAPI、uvicorn | 异步原生、高吞吐量、类型安全（`from __future__ import annotations`） | | **存储** | SQLite（WAL 模式）、FTS5 | 零配置、ACID 兼容、事件字段全文搜索无需外部搜索引擎 | | **ML** | scikit-learn、NumPy | 孤立森林与随机森林的行业标准实现 | | **事件总线** | asyncio Queue + deque 环形缓冲区 | 无锁发布-订阅，内存有界，慢消费者背压处理 | | **前端** | React 19、TypeScript（严格）、Vite、Tailwind CSS | 类型安全组件、亚秒级 HMR、实用优先样式 | | **可视化** | Recharts、D3.js（力导向布局） | Recharts 用于时序/柱状图，D3 用于交互式网络拓扑图 | | **桌面** | Tauri 2.x（Rust） | ~10MB 二进制体积（对比 Electron 的 ~150MB），原生系统托盘与通知 | | **CI/CD** | GitHub Actions | Python 3.11/3.12/3.13 矩阵、前端类型检查与构建、跨平台 Tauri 发布 | | **质量** | ruff、mypy（严格）、pytest、ESLint | CI 中强制执行代码检查与类型检查；77 个测试覆盖单元测试、集成测试与安全套件 | ## 快速开始 ### 先决条件 - Python 3.11+ - Node.js 22+ - （可选）Rust 工具链用于 Tauri 桌面构建 ### 后端 ``` # Clone and set up git clone https://github.com/mal0ware/Threatscope.git cd Threatscope # 创建虚拟环境并安装依赖项 python3 -m venv venv source venv/bin/activate pip install -r requirements.txt # 使用演示数据启动服务器 python3 -m api.main --demo ``` `--demo` 标志会在启动时生成约 400 个合成事件（暴力破解攻击、端口扫描、DNS 查询、基准流量），以便仪表板立即显示数据。 ### 前端 ``` cd frontend npm ci npm run dev ``` 打开 `http://localhost:5173` ——仪表板将连接到 `http://127.0.0.1:8000` 的 API 并开始实时流式接收事件。 ## 用法 ### 服务器选项 ``` python3 -m api.main [OPTIONS] --demo Seed synthetic attack data on startup --debug Enable debug logging and Swagger docs at /docs --host Bind address (default: 127.0.0.1) --port Bind port (default: 8000) ``` ### 仪表板组件 | 组件 | 描述 | |--------|------------| | **统计卡片** | 总事件数、最近一小时计数、开放告警数、关键告警数 | | **威胁时间线** | 按严重性分桶的时间段堆叠面积图 | | **活动热图** | 24 小时 × 7 天的网格，颜色强度映射事件量 | | **网络地图** | 基于 IP 通信的力导向图——蓝色节点为内网，红色为外网 | | **实时订阅** | 带有连接状态指示器的实时 WebSocket 事件流 | | **告警表** | 可一键确认、可展开威胁详情的活动告警 | | **源 IP 排行** | 最活跃源 IP 的水平条形图 | ## API 参考 所有端点前缀为 `/api/v1`。 | 方法 | 端点 | 描述 | |--------|----------|-------------| | `GET` | `/api/v1/events/search` | 支持过滤、FTS5 全文搜索、分页的事件查询 | | `GET` | `/api/v1/events/stream` | 实时事件的 SSE 流 | | `GET` | `/api/v1/events/{id}` | 按 ID 检索单个事件 | | `GET` | `/api/v1/alerts` | 按严重性/状态过滤的告警列表 | | `POST` | `/api/v1/alerts/{id}/ack` | 确认告警 | | `GET` | `/api/v1/stats/overview` | 仪表板统计摘要 | | `GET` | `/api/v1/stats/heatmap` | 24 小时 × 7 天活动热图数据 | | `GET` | `/api/v1/anomalies` | 按最低分数列出的异常 | | `GET` | `/api/v1/anomalies/{id}/narrative` | 获取告警的威胁叙述 | | `WS` | `/ws/events` | 实时事件 WebSocket 推送（最多 50 个连接，保持活跃） | | `GET` | `/health` | 健康检查 | **搜索参数：** `q`（FT5 查询）、`severity`、`source`、`event_type`、`source_ip`、`start`/`end`（ISO 8601）、`sort`、`order`、`limit`、`offset`。 启用 `--debug` 时，可在 `/docs` 访问交互式 API 文档。 ## 测试 ``` # 运行完整套件 pytest tests/ -v # 按类别运行 pytest tests/unit/ -v # 64 unit tests pytest tests/integration/ -v # 13 integration tests # Linting 和 type checking ruff check . mypy agent/ ml/ api/ --ignore-missing-imports # 前端 cd frontend npx tsc --noEmit # type check npm run build # production build ``` **77 个测试**覆盖： - 解析器正确性（认证日志、系统日志、边界情况、不可变性） - 事件总线发布-订阅（订阅、取消订阅、环形缓冲区淘汰、慢消费者） - ML 模型（孤立森林训练/评分、DNS 特征提取、Z 分数标记） - 规则引擎（阈值触发、按键分组、窗口重置、告警生成） - 威胁叙述器（模板渲染、降级行为） - API 集成（搜索、过滤、分页、错误处理、统计） - 文件跟踪器（事件发布、现有内容跳过、缺失来源处理） ## 安全态势 这是一个安全工具，其自身的攻击面已按相应策略加固。 | 关注点 | 缓解措施 | |---------|-----------| | **SQL 注入** | 所有数据库查询使用参数化占位符，SQL 中无字符串插值。 | | **输入验证** | 使用正则验证事件 ID，允许的枚举值（严重性/来源/排序），所有参数均受 `Query` 约束。 | | **XSS** | React JSX 默认转义。原始日志内容作为文本渲染，永不使用 `dangerouslySetInnerHTML`。 | | **速率限制** | 可配置的每 IP 速率限制。WebSocket 硬限制为 50 个并发连接。 | | **CORS** | 限制为配置的仪表板来源，生产环境禁止通配符来源。 | | **认证** | 基于 JWT 的会话过期与作用域令牌。 | | **资源耗尽** | 有界事件总线环形缓冲区（10K）。慢 WebSocket 消费者会被丢弃而非无限缓冲。 | | **文件访问** | 日志跟踪器仅读取显式注册的路径，不读取用户控制的文件。 | | **静态分析** | CI 中启用 ruff `S` 规则（Bandit）——捕获硬编码密钥、不安全函数使用和常见漏洞模式。 | ## 项目结构 ``` threatscope/ ├── agent/ # Log collection and parsing │ ├── config.py # Centralized settings (frozen dataclass, env var overrides) │ ├── event_bus.py # Async pub-sub with bounded ring buffer │ ├── collectors/ │ │ └── file_tailer.py # Watchdog-based tailer with inode rotation detection │ └── parsers/ │ ├── base.py # NormalizedEvent schema, LogParser ABC │ ├── auth.py # SSH auth log parser (failed/success/brute/sudo) │ └── syslog.py # RFC 3164 syslog parser ├── api/ # FastAPI REST API │ ├── main.py # App factory, lifespan management, CLI entrypoint │ ├── routes/ │ │ ├── events.py # Search, stream (SSE), single event retrieval │ │ ├── alerts.py # Alert listing and acknowledgment │ │ ├── stats.py # Overview stats and heatmap │ │ ├── anomalies.py # Anomaly listing and threat narratives │ │ └── websocket.py # WebSocket push with keepalive │ ├── middleware/ # Auth, rate limiting │ └── models/ │ └── database.py # SQLite manager (WAL, FTS5, CHECK constraints) ├── ml/ # Detection pipeline │ ├── pipeline.py # Orchestrator — subscribes to bus, runs all detectors │ ├── narrator.py # Threat narrative generation (template + optional API) │ ├── dns_analysis.py # Shannon entropy, structural DNS analysis │ ├── models/ │ │ ├── login_anomaly.py # Isolation Forest for auth behavior │ │ ├── network_anomaly.py # Z-score + IF hybrid for traffic patterns │ │ └── dns_classifier.py # Random Forest + heuristic DNS classification │ └── rules/ │ ├── detection.py # Rule definitions (frozen dataclasses) │ └── engine.py # Sliding-window evaluation engine ├── frontend/ # React + TypeScript dashboard │ ├── src/ │ │ ├── App.tsx # Dashboard layout │ │ ├── components/ # StatsCards, Timeline, Heatmap, NetworkMap, etc. │ │ ├── hooks/ # useAPI, useWebSocket (auto-reconnect) │ │ └── lib/ # API client, TypeScript interfaces │ └── src-tauri/ # Tauri v2 desktop wrapper (Rust) │ └── src/main.rs # System tray, native menu, window management ├── scripts/ │ └── generate_demo_data.py # Synthetic event seeder (brute force, port scan, baseline) ├── tests/ │ ├── unit/ # Parser, ML model, rule engine, event bus tests │ ├── integration/ # API endpoint and file tailer tests │ └── security/ # Security-focused test cases ├── .github/workflows/ │ ├── ci.yml # Lint + type-check + test (Python 3.11-3.13 matrix) │ └── release.yml # Cross-platform Tauri desktop builds on tag push ├── pyproject.toml # ruff, mypy strict, pytest config └── requirements.txt # Python dependencies ``` ## 桌面应用 ThreatScope 通过 [Tauri 2.x](https://v2.tauri.app/) 以原生桌面应用形式分发： - 系统托盘快速访问菜单（显示仪表板 / 退出） - 关键告警的原生通知支持 - ~10MB 二进制体积（Rust + 系统 WebView，不捆绑 Chromium） - 通过 GitHub Actions 进行 macOS、Windows 和 Linux 的跨平台构建 本地构建方法： ``` cd frontend npm ci npx tauri build ``` 需要 Rust 工具链和平台特定依赖（[Tauri 先决条件](https://v2.tauri.app/start/prerequisites/)）。 ## CI/CD **持续集成** 在每次推送到 `main` 分支及 PR 时运行： - **后端：** ruff 校验、mypy 严格类型检查、pytest 在 Python 3.11/3.12/3.13 上运行 - **前端：** TypeScript 严格编译、Vite 生产构建 **发布** 流水线在版本标签（`v*`）触发时执行： - 为 Linux、macOS 和 Windows 构建原生桌面二进制文件 - 创建包含所有平台工件的 GitHub 草稿发布 ## 许可证 [MIT](LICENSE)

标签：DNS日志, inode监控, LLM威胁叙事, Python, SIEM替代, TCP/UDP协议, TypeScript, WebSocket实时推送, 企业级安全, 低成本安全, 安全事件可视化, 安全插件, 安全监控仪表盘, 实时威胁情报, 文件轮转监控, 无后门, 日志采集, 机器学习异常检测, 桌面安全应用, 离线安全分析, 系统日志分析, 网络威胁检测, 规则评估, 逆向工具, 零依赖