ahmad12583719/Ubuntu-Sentinel

# Ubuntu Sentinel - 轻量级主机 SOC 与 IDS **Ubuntu Sentinel** 是一个 100% 本地运行的、专为 Ubuntu Linux 构建的主机安全运营中心 (SOC) 和入侵检测系统 (IDS)。它完全在您的系统上提供实时异常检测、日志分析和安全警报，无需依赖 LLM 或繁重的云服务等外部组件。 ## 功能 ✅ **实时日志流处理** - 零延迟从 `journalctl` 获取实时系统日志 ✅ **ML 驱动的异常检测** - 使用 River 的 HalfSpaceTrees 进行增量流式机器学习 ✅ **多类别分析** - 将日志分类为 AUTH、KERNEL、NETWORK、PACKAGE、SERVICE ✅ **桌面通知** - 通过 `notify-send` (libnotify) 发送即时警报 ✅ **持久化存储** - 将所有 WARNING/CRITICAL 警报记录到本地 SQLite 数据库中 ✅ **交互式 CLI 仪表板** - 提供带有状态和事件历史的 Rich 终端 UI ✅ **轻量且快速** - 占用空间约 50MB，可在任何 Ubuntu 系统上运行 ## 技术栈 | 组件 | 技术 | 用途 | |-----------|-----------|---------| | ML 引擎 | River 0.25.0 | 流式异常检测 (HalfSpaceTrees) | | CLI UI | Typer + Rich | 交互式仪表板和命令 | | 数据库 | SQLite3 | 本地警报持久化 | | 日志来源 | journalctl | 系统日志获取 | | 通知 | libnotify | 桌面警报 | ## 安装 ### 前置条件 - Ubuntu Linux 20.04 或更高版本 - Python 3.11+ - `libnotify-bin`（用于桌面通知） - `systemd` 及 `journalctl`（Ubuntu 标准配置） ### 设置 ``` # 克隆或下载项目 cd /path/to/ubuntu-sentinel # 创建虚拟环境 python3 -m venv venv source venv/bin/activate # 安装依赖 pip install -r requirements.txt # 安装 libnotify（用于桌面提醒） sudo apt install libnotify-bin # 初始化数据库 python3 -c "from db import init_db; init_db()" ``` ## 快速开始 ### 开始实时监控 ``` source venv/bin/activate python3 -m cli start ``` 这将流式传输实时日志并在检测到时显示警报： - 日志通过 ML 异常检测进行处理 - WARNING 和 CRITICAL 警报会触发桌面通知 - 所有事件都会保存到 `~/.sentinel/sentinel_soc.db` - 按 `Ctrl+C` 可优雅停止 ### 查看事件历史 ``` python3 -m cli status ``` 显示内容： - 已记录的警报总数 - 按严重程度划分 (CRITICAL、WARNING、INFO) - 按类别划分 (AUTH、KERNEL、NETWORK 等) - 最近 20 条事件的表格 ### 运行自检 ``` python3 -m cli test ``` 验证内容： - 引擎初始化 - ML 模型功能 - 数据库 schema - 通知系统 - 特征提取 ### 清理旧警报 ``` # 删除超过 7 天的提醒（默认） python3 -m cli clear # 仅保留最近 30 天 python3 -m cli clear --days 30 ``` ## 项目结构 ``` ubuntu-sentinel/ ├── requirements.txt # Python dependencies ├── .gitignore # Git exclusions ├── README.md # This file │ ├── db.py # SQLite database layer │ ├── init_db() # Initialize schema │ ├── log_alert() # Persist alerts │ ├── get_recent_alerts() # Query alerts │ └── get_alert_stats() # Aggregate statistics │ ├── engine.py # ML anomaly detection │ ├── SentinelSOCEngine # Main ML class │ ├── categorize_log() # Rules-based categorization │ ├── extract_features() # BagOfWords feature extraction │ ├── process_log() # Full ML pipeline │ └── should_alert() # Alert decision logic │ ├── cli.py # Interactive CLI dashboard │ ├── start # Stream logs & detect anomalies │ ├── status # Show incident dashboard │ ├── clear # Clean up old alerts │ ├── test # Run self-tests │ └── send_desktop_notification() # Alert delivery │ └── test_sentinel.py # Automated test suite ├── test_engine_initialization() ├── test_log_categorization() ├── test_feature_extraction() ├── test_anomaly_scoring() ├── test_severity_calculation() ├── test_alert_should_trigger() ├── test_database_initialization() ├── test_alert_logging() ├── test_journalctl_json_parsing() └── test_graceful_error_handling() ``` ## 架构 ### 日志处理 Pipeline ``` journalctl -f (JSON) ↓ Parse JSON ↓ Extract text message ↓ Categorize (rules-based) ↓ Extract BagOfWords features (string keys) ↓ Anomaly score via HalfSpaceTrees ↓ Calculate severity (INFO/WARNING/CRITICAL) ↓ Should alert? (WARNING/CRITICAL) ↓ ┌─────────────────────────┐ ├─ Desktop notification │ ├─ SQLite persistence │ └─ Console output │ ``` ### ML 特征提取 - 使用 `ngram_range=(1,1)` 的 **BagOfWords** 生成 unigram 特征 - 所有特征字典的键都**严格为字符串**（防止 River 排序时崩溃） - 特征表示日志文本的词汇频率 - 异常检测器会观察特征分布随时间的变化 ### 严重程度映射 | 异常分数 | 严重程度 | 通知 | |---|---|---| | 0.0 - 0.49 | INFO | 无（仅记录日志） | | 0.50 - 0.79 | WARNING | 普通紧急程度 | | 0.80 - 1.00 | CRITICAL | 关键紧急程度 | ## 自动化测试 运行全套测试套件以验证所有组件： ``` source venv/bin/activate python3 test_sentinel.py ``` **测试覆盖范围：** - ✓ 引擎初始化和 ML 模型设置 - ✓ 跨所有 5 个类别的日志分类 - ✓ 带有字符串键验证的特征提取 - ✓ 异常分数计算及其有效性 (0.0-1.0) - ✓ 严重程度级别映射 - ✓ 警报触发逻辑 - ✓ 数据库 schema 和持久化 - ✓ 警报记录和检索 - ✓ JSON 解析 (journalctl 格式) - ✓ 优雅的错误处理（格式错误的输入） **预期输出：** ``` ====================================================================== Ubuntu Sentinel - Automated Test Suite ====================================================================== TEST 1: Engine Initialization... ✓ Engine initialized successfully TEST 2: Log Categorization... ✓ All logs categorized correctly [... 8 more tests ...] ====================================================================== Test Results: 10/10 passed ====================================================================== [✓] ALL TESTS PASSED! ``` ## 配置 ### 数据库位置 警报存储于：`~/.sentinel/sentinel_soc.db` 要指定自定义位置，请修改 `db.py`： ``` DB_PATH = Path("/custom/path/sentinel_soc.db") ``` ### ML 模型参数 在 `engine.py` 中，调整 `SentinelSOCEngine` 的初始化： ``` engine = SentinelSOCEngine( window_size=1000 # Sliding window for anomaly detector ) ``` ### 日志优先级过滤器 目前过滤优先级 6 及以上的日志（即 Info 及以上）。要在 `cli.py` 中进行更改： ``` ["journalctl", "-f", "-o", "json", "-p", "6"] # Change 6 to 0-7 ``` ## 故障排除 ### 没有出现桌面通知？ 确保已安装 `libnotify-bin`： ``` sudo apt install libnotify-bin ``` 测试通知： ``` notify-send "Test" "Ubuntu Sentinel is working" ``` ### 数据库文件未被创建？ 检查 `~/.sentinel/` 的权限： ``` mkdir -p ~/.sentinel chmod 700 ~/.sentinel ``` ### journalctl 访问被拒绝？ 将您的用户添加到 `systemd-journal` 组： ``` sudo usermod -a -G systemd-journal $USER # 注销并重新登录 ``` ### 出现大量误报警报？ ML 模型会随着时间进行学习。初始运行时可能具有较高的敏感度。请让其运行处理超过 100 条日志以建立基线。您也可以在 `engine.py` 中调整 `window_size` 以加快或减慢学习速度。 ## 性能 | 指标 | 数值 | |--------|-------| | 内存 (空闲) | ~15 MB | | 内存 (流式传输) | ~30-50 MB | | CPU (每条日志) | <1 ms | | 数据库写入 (每次警报) | ~2 ms | | 警报延迟 | <100 ms | ## 安全说明 ⚠️ **本地执行**：Sentinel 完全在您的机器上运行，不进行任何云端或外部服务调用 ⚠️ **数据库存储**：警报历史记录以明文 SQLite 存储。请相应地保护 `~/.sentinel/` 的权限 ⚠️ **Journalctl 访问**：需要读取系统日志的权限（可能需要群组成员资格） ## 作者 - **Ubuntu Sentinel 团队** - 网络安全工程 ## 免责声明 Ubuntu Sentinel 是一款检测和警报工具，不能替代： - 专业的安全监控服务 - 全面的安全审计 - 事件响应程序 - 安全强化措施 请将其作为纵深防御策略的一部分使用。 **最后更新**：2026-07-24 **版本**：1.0.0 **Python 兼容性**：3.11+ **Ubuntu 兼容性**：20.04+ ### 🔑 所需系统权限（日志访问） 为了让 Ubuntu Sentinel 能够读取系统日志而无需以 `root` (`sudo`) 身份运行，您的 Linux 用户必须属于 `systemd-journal` 组。 在您的终端中运行以下命令： ``` # 将您的用户添加到 systemd-journal 组 sudo usermod -a -G systemd-journal $USER ``` ### 💡 为什么这对您的项目很重要 * **无需 `sudo`：** 将用户添加到 `systemd-journal` 允许您的工具以普通用户身份通过 `python3 cli.py start` 干净地运行，而无需 `sudo`。 * **保证日志遥测：** 它确保 `journalctl -f -o json -p 6` 能将实时系统日志直接送入您的 River ML pipeline 中！

标签：Apex, PB级数据处理, Python, SQLite, 主机入侵检测, 安全运维, 异常检测, 无后门, 机器学习, 逆向工具