bj112233/sentinel-agent
GitHub: bj112233/sentinel-agent
一个基于端侧 LLM 的 Windows 威胁检测研究项目，通过 ReAct 代理架构结合 YARA、OSINT 和 MITRE ATT&CK 实现本地化安全监控与告警富化。
Stars: 1 | Forks: 0
# Sentinel
[](https://github.com/bj112233/sentinel-agent/actions/workflows/ci.yml)
适用于 Windows 的本地优先威胁检测代理。在设备端运行 4B 参数 LLM（通过 KoboldCpp）进行推理，无需依赖云端。监控系统行为，通过端侧推理丰富告警内容，并通过 Telegram 交付检测结果。包含行为 TTP 检测（MITRE ATT&CK）、文件完整性监控（watchdog + YARA）、凭证泄露狩猎，以及带有 5 层搜索瀑布流的 OSINT 子系统。
## 本项目不是什么
**这不是一款商业安全产品、EDR 的替代品，也不是生产级别的防御工具。** 这是一个探索在消费级硬件上进行本地优先 LLM 驱动威胁检测的个人研究项目。
- 本项目**不提供支持** —— 不提供任何保证、不保证维护、没有 SLA。
- 它**不能替代**专业的 EDR/XDR/AV 解决方案。
- 它**未经过独立审计**或渗透测试。
- LLM（4B 参数）**不是一位可靠的安全分析师** —— 它可能会产生幻觉、漏报威胁或产生误报。所有关键操作都需要通过 Telegram 获得人类在环（HITL）的批准。
- **不要**将其部署为任何重要机器上的唯一安全控制手段。请用它来学习、实验和演示概念。
完整的免责条款请参见 [LICENSE](LICENSE) (AGPL-3.0)。
## 架构
```
main.py
└── services/
├── telegram/ (aiogram 3.x — DM + groups)
├── startup/ (monitor_loop → alert_queue → llm_analysis workers)
├── web_c2*.py (aiohttp — LAN dashboard, Basic Auth + rate limit)
├── agent/ (ReAct FSM: INITIALIZE → PLANNER → EXECUTE → CRITIC → FINALIZE + ERROR)
│ ├── bypass/ (17 fast-path handlers, chain of responsibility)
│ ├── routing/ (hybrid semantic + keyword tool/skill routing)
│ └── _nodes/ (FSM nodes + tool-level circuit breaker + tool ranker)
├── _skills_engine/ (15-skill engine — loads YAML skills from /skills)
├── llm_bridge/ (KoboldCpp / Qwen3.5-4B, circuit breaker, TPOT degradation)
├── bot_memory/ (SQLite + FTS5 + vectorlite HNSW, E5-large-instruct)
├── monitor_engine → monitor_analyzer → alert_dispatcher
│ (EMA baseline, 4-layer whitelist, Intel enrichment,
│ TTP detection → MITRE ATT&CK, score ≥85 → auto-queue kill)
├── fim_engine + yara_engine
│ (watchdog Observer → YARA auto-scan, 5 rules, 15 exts)
├── credential_monitor + leak_scanner
├── threat_hunter + pre_hunt_enricher
│ (APScheduler 6h → full ReAct → score → Telegram)
├── osint_hunter + osint_react_loop + osint_search
│ (engine-in-engine ReAct, 5-tier search waterfall)
└── action_tools/ (HITL-protected OS remediation: firewall, defender, shell)
```
完整架构参考（18 个部分，包括关于代理幻觉防御的案例研究）：[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
## 安装
### 环境要求
| 要求 | 详情 |
|-------------|--------|
| 操作系统 | Windows 10/11（测试和 lint 检查仅在 Windows 上运行） |
| Python | 3.12.2（唯一支持的解释器 —— 由 venv 钩子强制执行） |
| GPU | 至少 6 GB VRAM（用于通过 KoboldCpp 运行 Qwen3.5-4B Q4_K_S） |
| LLM 运行时 | [KoboldCpp](https://github.com/LostRuins/koboldcpp)（本地推理服务器） |
| 可选：Tesseract 5.x | 用于 OCR 技能（支持希伯来语和 LTR） |
| 可选：opus-mt 模型 | 用于离线翻译技能 |
### 步骤
```
# 1. Clone
git clone https://github.com/bj112233/sentinel-agent.git
cd sentinel-agent
# 2. 创建 venv（Python 3.12.2 — 唯一支持的解释器）
python -m venv .venv
.\.venv\Scripts\Activate.ps1
# 3. 安装依赖
# 选项 A — uv（首选，确定性 lockfile）：
uv sync --frozen
# 选项 B — pip fallback（使用自动生成的 requirements.txt）：
pip install -r requirements.txt
# 4. 从示例文件进行配置
copy config\channels.example.json config\channels.json
copy config\news_feeds.example.json config\news_feeds.json
copy config\trusted_devices.example.json config\trusted_devices.json
copy config\persona\USER.example.md config\persona\USER.md
# 编辑每个文件 — 将占位符替换为您的值。
# 5. 从模板创建 .env
copy .env.example .env
# 编辑 .env — 将占位符替换为您的 API keys（见下表）。
# .env 文件已被 gitignored — 切勿提交它。
# 6. 安装 gitleaks（用于 secret/PII scan gate）
winget install gitleaks.gitleaks
# 7. 运行 lint gates
.\.venv\Scripts\python.exe bin\lint-gate.py
# 8. 运行测试
.\.venv\Scripts\python.exe -m pytest tests/ -q
# 9. 启动 bot
.\.venv\Scripts\python.exe main.py
```
### API Keys
该机器人使用可选的威胁情报 API keys 进行数据富化。所有 keys 均从环境变量（`.env`）中加载 —— 没有任何硬编码。
| Key | 用途 | 获取地址 |
|-----|---------|-----------------|
| `TELEGRAM_BOT_TOKEN` | Telegram 机器人投递 | [@BotFather](https://t.me/BotFather) |
| `TELEGRAM_CHAT_ID` | 您的 Telegram 聊天 ID（管理员） | [@userinfobot](https://t.me/userinfobot) |
| `VIRUSTOTAL_API_KEY` | VirusTotal 数据富化 | [virustotal.com → 注册](https://www.virustotal.com/gui/join-us) |
| `ABUSEIPDB_API_KEY` | AbuseIPDB 信誉查询 | [abuseipdb.com → 注册](https://www.abuseipdb.com/account) |
| `URLHAUS_AUTH_KEY` | URLhaus 订阅源 (abuse.ch) | [urlhaus.abuse.ch](https://urlhaus.abuse.ch/) |
| `THREATFOX_AUTH_KEY` | ThreatFox 订阅源 (abuse.ch) | [threatfox.abuse.ch](https://threatfox.abuse.ch/) |
| `NVD_API_KEY` | NVD CVE 速率限制（可选） | [nvd.nist.gov → 申请 Key](https://nvd.nist.gov/developers/request-an-api-key) |
链接仅指向注册页面 —— 不分享或嵌入任何 keys。
## 测试与质量状态
| 门禁 | 工具 | 说明 |
|------|------|-------|
| 圈复杂度 | xenon | max-absolute=D, max-average=A, max-modules=C |
| 架构耦合 | import-linter | 强制执行分层隔离 |
| 无用代码 | vulture | 白名单由工具注册表自动生成 |
| Lint + 格式化 | ruff | |
| 类型检查 | mypy | 零未抑制错误；包含 25 个已明确审查的 `type: ignore` 抑制 |
| 安全 SAST | bandit | Medium+ 级别会阻塞，Low 级别仅作记录 |
| 密钥 + PII 扫描 | gitleaks | 自定义规则：VT, AbuseIPDB, Telegram, ThreatFox, URLhaus, Maltiverse, NVD + 本地 PII |
| 文件长度 | file-length-gate | 每个文件最多 300 行 |
| 认知复杂度 | cognitive-complexity-gate | 受棘轮机制保护，最大 15 |
| 代码覆盖率 | coverage-gate | 受棘轮机制保护 |
| 依赖审计 | pip-audit | 阻塞包含 CVE 的依赖项 |
**所有检查门禁和测试均在 Windows 上运行。** CI 使用 `windows-latest`。
测试需要安装了所有依赖项的完整 Windows 环境；部分测试依赖于系统（进程内省、Windows API、KoboldCpp 运行时），在 Linux/macOS 上无法收集或通过。
```
# 完整 lint gate（包含 coverage 在内的所有 gates）
.\.venv\Scripts\python.exe bin\lint-gate.py
# 快速 lint gate（跳过 coverage — 用于 pre-commit）
.\.venv\Scripts\python.exe bin\lint-gate.py --fast
# 测试
.\.venv\Scripts\python.exe -m pytest tests/ -q
```
## 技术栈
| 组件 | 技术 |
|-----------|------------|
| 语言 | Python 3.12.2（严格类型，Pydantic V2，async） |
| LLM | Qwen3.5-4B (Q4_K_S) 通过 KoboldCpp（16K 上下文，6GB VRAM） |
| Embeddings | E5-large-instruct (1024-dim) |
| 向量搜索 | vectorlite HNSW (m=16, ef_construction=200) |
| 数据库 | SQLite (WAL 模式，7 个活跃数据库 —— 参见 [ARCHITECTURE.md](docs/ARCHITECTURE.md)) |
| Telegram | aiogram 3.x |
| Web 仪表盘 | aiohttp (Basic Auth，IP 白名单，限流) |
| 调度器 | APScheduler |
| 技能 | 15 项技能 (crypto, currency, email-forensics, file_analyst, firewall, geocode, intel, news-monitor, pcap-analyst, persistence-hunter, report-maker, stocks, translator, weather, web-scraper) |
| FIM + YARA | watchdog Observer + YARA（5 条规则，15 种危险扩展名） |
| TTP 检测 | cmdline_analyzer (regex) → mitre_mapper |
| OCR | Tesseract 5.x (仅限 CPU，支持希伯来语和 LTR) |
| 翻译 | opus-mt (离线) → MyMemory → deep-translator → LibreTranslate |
| 许可证 | AGPL-3.0-or-later |
## 文档
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — 完整架构参考（18 个部分）
- [`conceptual_repo/`](conceptual_repo/) — 工程展示变体（仅包含 README 和 ARCHITECTURE，无源代码）。适用于在不含代码库的情况下分享设计。
- [`SECURITY.md`](SECURITY.md) — 漏洞报告策略
- [`AGENTS.md`](AGENTS.md) — 项目规则（token 经济，venv，验证）
- [`LICENSE`](LICENSE) — AGPL-3.0-or-later
## 许可证
版权所有 (C) 2026 Sentinel 贡献者。
本程序为自由软件：您可以依据自由软件基金会发布的 GNU Affero 通用公共许可证的条款重新分发和/或修改它（许可证的第三版，或您自行选择的任何后续版本）。
发布本程序的目的是希望它能够有用，但**不提供任何保证**；甚至不提供其适销性或特定用途适用性的隐含保证。有关完整条款，请参见 [LICENSE](LICENSE)。
标签：AMSI绕过, LLM代理, YARA, 云资产可视化, 威胁检测, 本地大模型, 端点检测与响应(EDR)