rmayen/halotrace

# HaloTrace 用于分析 Linux 身份验证日志和安全事件的防御性网络威胁检测与事件响应平台。 HaloTrace 是一个教育性质的防御性安全项目，用于接入 Linux SSH 身份验证日志，检测可疑登录行为，将警报关联为事件，并为分析师提供一个用于分诊的小型 Web 仪表板。 它不能替代企业级的 SIEM、IDS、EDR 或事件响应平台。 ## 功能 - 根据源 IP 的重复登录失败进行 SSH 暴力破解检测。 - 根据单个源 IP 目标针对大量用户名的行为进行密码喷洒检测。 - 确定性的严重程度和置信度评分。 - 带有可配置冷却时间的重复警报抑制。 - 基于源 IP、主机、相近时间戳和重叠用户名的事件关联。 - 事件状态管理：待处理、调查中、已解决、误报。 - 分析师备注、状态历史和审计日志。 - 包含验证、过滤和安全错误响应的 REST API。 - 响应式原生 JavaScript 仪表板。 - 使用 SQLAlchemy 模型和实用索引的 SQLite 持久化。 - Docker、Docker Compose 和 GitHub Actions CI。 ## 技术栈 Python 3.12、FastAPI、SQLAlchemy、SQLite、Pydantic、Pytest、原生 JavaScript、HTML、CSS、Docker、Docker Compose 和 GitHub Actions。 ## 架构 ``` flowchart LR A[Linux auth.log text or upload] --> B[FastAPI ingestion API] B --> C[SSH auth log parser] C --> D[(Auth events)] C --> E[Detection engine] E --> F[Scoring and duplicate suppression] F --> G[(Alerts)] G --> H[Incident correlation] H --> I[(Incidents, notes, history, audit logs)] I --> J[REST API] G --> J J --> K[HaloTrace dashboard] ``` ## 安装 使用 Python 3.12。 ``` python3.12 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -r requirements.txt cp .env.example .env ``` 本地运行： ``` uvicorn app.main:app --reload ``` 打开 `http://127.0.0.1:8000`。 ## Docker ``` docker compose up --build ``` Compose 堆栈将 SQLite 数据库存储在 `halotrace-data` 卷中，并通过 `http://127.0.0.1:8000` 暴露仪表板。 加载经过处理的示例日志： ``` scripts/load_sample.sh ``` ## 配置 配置使用带有 `HALOTRACE_` 前缀的环境变量。 | 变量 | 默认值 | 用途 | | --- | --- | --- | | `HALOTRACE_DATABASE_URL` | `sqlite:///./halotrace.db` | SQLAlchemy 数据库 URL | | `HALOTRACE_MAX_UPLOAD_BYTES` | `1048576` | 最大上传日志大小 | | `HALOTRACE_MAX_TEXT_BYTES` | `262144` | 最大直接文本提交大小 | | `HALOTRACE_INGEST_RATE_LIMIT` | `20` | 每个客户端每分钟的接入请求 | | `HALOTRACE_DETECTION_WINDOW_SECONDS` | `300` | 检测时间窗口 | | `HALOTRACE_FAILURE_THRESHOLD` | `5` | 暴力破解警报的登录失败阈值 | | `HALOTRACE_SPRAY_USER_THRESHOLD` | `5` | 密码喷洒警报的不同用户名阈值 | | `HALOTRACE_ALERT_COOLDOWN_SECONDS` | `900` | 重复抑制冷却时间 | 数据库在应用程序启动时通过 `Base.metadata.create_all()` 进行初始化。在第一个版本中刻意省略了数据库迁移，以保持教育环境的轻量化；在针对长期运行的生产数据运行此操作之前，请添加 Alembic。 ## API 概述 - `GET /api/health` - `POST /api/ingest/text` - `POST /api/ingest/upload` - `GET /api/alerts` - `GET /api/alerts/{alert_id}` - `GET /api/incidents` - `GET /api/incidents/{incident_id}` - `PATCH /api/incidents/{incident_id}/status` - `POST /api/incidents/{incident_id}/notes` 警报和事件列表端点支持严重程度、源 IP、搜索和时间过滤器。事件列表还支持状态过滤。 ## 检测逻辑 HaloTrace 解析常见的 `sshd` syslog 风格的日志行，以获取密码失败、无效用户、接受的登录、用户名、源 IP、时间戳和主机名。不支持和格式错误的行将被安全地忽略。 暴力破解规则：一个源 IP 在 `HALOTRACE_DETECTION_WINDOW_SECONDS` 内对一台主机产生至少 `HALOTRACE_FAILURE_THRESHOLD` 次失败的 SSH 登录。可能存在多个用户名，但如果每个事件都针对不同用户名的模式，则将被视为密码喷洒。 密码喷洒规则：一个源 IP 在检测窗口内尝试对至少 `HALOTRACE_SPRAY_USER_THRESHOLD` 个不同的用户名进行失败的 SSH 身份验证。 严重程度和置信度是确定性的。它们基于事件量、时间集中度和目标帐户的数量。不使用随机评分。 暴力破解警报示例： ``` { "alert_type": "ssh_brute_force", "severity": "medium", "confidence": 0.68, "source_ip": "203.0.113.10", "target_hostname": "lab-host", "affected_usernames": ["root"], "event_count": 5, "explanation": "5 failed SSH login attempts from 203.0.113.10 against 1 account(s) within 300 seconds." } ``` 密码喷洒警报示例： ``` { "alert_type": "password_spray", "severity": "medium", "confidence": 0.7, "source_ip": "198.51.100.25", "target_hostname": "lab-host", "affected_usernames": ["alice", "bob", "carol", "dave", "erin"], "event_count": 5, "explanation": "198.51.100.25 attempted failed SSH authentication against 5 distinct usernames within 300 seconds." } ``` ## 测试 ``` pytest ``` 测试使用隔离的临时 SQLite 数据库，涵盖了解析、格式错误的行、IPv4/IPv6 地址、检测边界、重复抑制、评分、事件关联、API 验证、上传限制、不支持的文件类型、状态更新、备注、安全标头和速率限制。 ## 安全控制 - 对请求体和查询输入进行严格的 Pydantic 验证。 - 上传文件大小限制和直接文本正文限制。 - 允许的上传扩展名：`.log` 和 `.txt`。 - 不信任或使用上传的文件名进行存储。 - 上传的日志仅作为文本解析，永远不会被执行。 - 每个客户端的接入速率限制。 - 安全响应标头。 - 安全的通用服务器错误。 - SQLAlchemy 查询参数化。 - 基于环境的配置，没有硬编码的密钥。 - 针对事件状态更改和备注的审计日志。 - 应用程序代码中没有 `eval`、shell 插值或子进程执行。 ## 已知限制 - 仅支持常见的 Linux `sshd` 身份验证日志格式。 - SQLite 适用于本地演示和实验室，不适合大吞吐量的生产环境接入。 - 速率限制在内存中进行，并在进程重启时重置。 - 第一个版本中没有分析师身份验证。 - 数据库迁移已记录为未来的工作。 ## 道德使用 HaloTrace 仅用于授权的防御性实验室、教育以及分析您被允许检查的日志。请勿使用它来支持未经授权的访问、凭据窃取、持久化、规避、破坏性行动、恶意软件或未经授权的扫描。 ## 路线图 - 添加 Alembic 迁移。 - 添加分析师身份验证和基于角色的权限。 - 添加针对警报和事件的 CSV/JSON 导出。 - 添加更丰富的趋势图表和源聚合。 - 添加对其他 Linux 发行版和日志格式的支持。 - 添加可选的 PostgreSQL 部署配置。 ## 截图 接入示例身份验证日志后的威胁监控仪表板 —— 一个 暴力破解和一个密码喷洒警报，各自关联为一个待处理事件： 

标签：AV绕过, FastAPI, Python, SQLite, 多模态安全, 数据可视化, 无后门, 版权保护, 网络测绘, 请求拦截