vinsk0h/KQLab

## 为什么选择 KQLab？ SOC 分析师在 Microsoft Defender 和 Azure Sentinel 中积累了数百个 KQL 查询。这些查询散落在记事本、Notion、共享驱动器中——缺乏文档、无法搜索，在团队中分散各处。 KQLab 将它们集中在一个**自托管、加密的平台**中：基于团队的共享、MITRE ATT&CK 映射、调查跟踪和 Passkey 身份验证——零云依赖、零密码、零供应商锁定。 将其部署在您的基础设施上。完全掌控您的数据。 ## 功能 | Feature | Description | |---|---| | **Passkey 身份验证** | WebAuthn/FIDO2 — 基于硬件的凭据，无需密码 | | **加密数据库** | AES-256-GCM 加上 scrypt KDF，每个存储的值使用独立的 salt | | **团队作用域** | 查询和文件夹按团队隔离 | | **MITRE ATT&CK 映射** | 按战术 (tactic) 和技术 (technique) 标记查询 | | **PICERL 映射** | 将查询映射到事件响应阶段 | | **变量解析器** | 将查询复制到剪贴板前填充 `{{variables}}` | | **环境兼容性** | 根据您的 Defender/Sentinel 表检查查询兼容性 | | **调查** | 跟踪活跃事件 — IoCs、时间线、发现结果、报告 | | **报告导出** | 生成 PDF、DOCX 和 HTML 调查报告 | | **报告模板** | 可自定义的基于章节的报告模板（由管理员管理） | | **网络监控** | 内置威胁源阅读器，支持查询自动匹配 | | **GitHub 仓库同步** | 直接从公共 GitHub 仓库拉取 KQL 查询 | | **导入 / 导出** | 批量 JSON 导入和导出 | | **管理门户** | 用户、团队、审计日志和设置管理 | | **审计日志** | 带有 IP 和时间戳的所有身份验证和 CRUD 事件的完整追踪 | | **速率限制** | 每 15 分钟 30 次身份验证请求 · 每分钟 120 次 API 请求 | ## 技术栈 | Layer | Technology | |---|---| | Runtime | Node.js ≥ 18 | | Framework | Express 4 | | Database | SQLite via `better-sqlite3` (同步，无需服务器) | | Encryption | AES-256-GCM · scrypt KDF (N=16384) | | Authentication | WebAuthn / Passkeys (FIDO2) | | Frontend | Vanilla JS SPA — 无框架，无打包器 | | Code editor | Monaco Editor (VS Code 引擎，通过 CDN 引入) | | Syntax highlighting | PrismJS (KQL, PowerShell, Python, JSON, YAML) | | Charts | Chart.js (管理员仪表盘) | | Reports | pdfkit · docx | ## 快速开始 ### 前置条件 - [Node.js LTS](https://nodejs.org/en/download) ≥ 18 - npm (随 Node.js 一起提供) ``` node --version # v18.x or higher npm --version ``` ### 1. 克隆 ``` git clone https://github.com/vinsk0h/kqlab.git cd kqlab ``` ### 2. 安装依赖 ``` npm install ``` ### 3. 配置环境 ``` cp .env.example .env ``` 生成密钥 (运行两次 — 您需要两个不同的密钥): ``` npm run keygen # → paste as DB_ENCRYPTION_KEY npm run keygen # → paste as SESSION_SECRET ``` 用于本地开发的最小 `.env` 配置: ``` PORT=3000 DB_ENCRYPTION_KEY=<64-char hex key> SESSION_SECRET=<64-char hex key> RP_ID=localhost RP_NAME=KQLab ORIGIN=http://localhost:3000 ``` ### 4. 启动 ``` npm start ``` 打开 `http://localhost:3000` — 使用演示账号 `john.doe` 进行探索。 ## 生产部署 KQLab 专为在反向代理 (nginx, Caddy, Traefik) 之后进行自托管的企业部署而设计。 ### 环境 ``` NODE_ENV=production RP_ID=kqlab.yourdomain.com RP_NAME=KQLab ORIGIN=https://kqlab.yourdomain.com ``` ### 推荐设置 ``` Internet → HTTPS reverse proxy → KQLab (127.0.0.1:3000) ``` 仅将 KQLab 绑定到 `127.0.0.1`，并让反向代理处理 TLS。SQLite 数据库位于 `backend/db/kqlvault.db` — 请定期备份。 ### 可选集成 ``` # GitHub token — 将 repo 同步速率限制从 60 提升至 5000 req/h GITHUB_TOKEN= # VirusTotal — IoC enrichment（免费版：4 req/min，500 req/day） VT_API_KEY= ``` ## 安全 | Layer | Protection | |---|---| | Credentials | AES-256-GCM · 每个值使用独立的 salt · scrypt KDF | | Sessions | 数据库中的 HMAC-SHA256 哈希 · httpOnly cookie · 24 小时 TTL · 最多 5 个并发 | | WebAuthn | `userVerification: required` · 源检查 · 计数器重放防范 | | Account lockout | 5 次失败尝试 → 锁定 15 分钟 | | Rate limiting | 每 15 分钟 30 次身份验证请求 · 每分钟 120 次 API 请求 | | Database file | `chmod 600` · `secure_delete` · `auto_vacuum` | | HTTP headers | Helmet · 严格的 CSP · 移除 `X-Powered-By` | | Input | 所有端点均已进行净化处理 · 枚举验证 | | Audit log | 所有身份验证和 CRUD 事件：时间戳、用户、IP | 若要报告漏洞，请提交 [GitHub Security Advisory](../../security/advisories/new) — 请勿使用公开的 issues。 ## 角色模型 | Role | Permissions | |---|---| | `admin` | 完全访问权限 — 用户、团队、设置和审计管理 | | `analyst` | 在其团队内读取和写入查询、文件夹及调查的权限 | | `viewer` | 对团队查询的只读访问权限 | 用户仅隶属于一个团队。查询、文件夹和调查均限定在相应团队的作用域内。 ## 可用命令 ``` npm start # Production server (port 3000) npm run dev # Dev server with file watch (auto-restart) npm run keygen # Generate a 64-char hex secret key npm run sync-repos # Sync queries from configured GitHub repositories npm run release:patch # Bump patch version + git tag (2.1.1 → 2.1.2) npm run release:minor # Bump minor version + git tag (2.1.1 → 2.2.0) npm run release:major # Bump major version + git tag (2.1.1 → 3.0.0) ``` ## API KQLab 提供完整的 REST API。所有端点都需要身份验证（`/api/auth/*` 除外）并返回 JSON。 | Prefix | Description | |---|---| | `/api/auth/*` | 注册、登录、会话管理 | | `/api/queries/*` | KQL 查询 CRUD、星标、批量导入/导出 | | `/api/folders/*` | 文件夹管理（团队 + 个人） | | `/api/investigations/*` | 调查跟踪、IoCs、发现结果、报告 | | `/api/templates/*` | 报告模板管理（管理员） | | `/api/settings/*` | 报告品牌化和系统设置（管理员） | | `/api/comments/*` | 针对查询的评论 | | `/api/env/*` | 环境配置文件和查询兼容性 | | `/api/repos/*` | GitHub 仓库来源和同步 | | `/api/watch/*` | 威胁源和文章 | | `/api/admin/*` | 用户、团队和审计管理（仅限管理员） | | `/health` | 健康检查（无需身份验证） | 有关完整的端点参考，请参阅 [`docs/API.md`](docs/API.md)。 ## 项目结构 ``` kqlab/ ├── frontend/ │ ├── index.html # Main SPA │ ├── admin.html # Admin portal │ ├── investigations.html # Investigations view │ └── js/ │ ├── app.js # UI state + render loop │ ├── admin.js # Admin portal UI │ ├── admin-templates.js # Report template editor UI │ ├── api.js # REST fetch wrapper (GET/POST/PUT/DELETE) │ ├── auth.js # Auth client helpers │ ├── data.js # MITRE/PICERL constants + enums │ ├── i18n.js # Internationalisation (FR/EN) │ ├── investigations.js # Investigation UI │ ├── kql-monaco.js # Monaco editor integration │ ├── rich-editor.js # Rich text editor (findings) │ └── chart.umd.min.js # Chart.js (bundled, admin dashboard) ├── backend/ │ ├── server.js # Express entry point + rate limiting │ ├── db/database.js # SQLite init · AES-256-GCM · seed data │ ├── lib/ │ │ ├── sanitize.js # Input sanitization helpers │ │ ├── reportGenerator.js # PDF / DOCX / HTML report generation │ │ ├── repo-parser.js # GitHub repo sync engine │ │ └── watch-engine.js # Threat feed fetcher │ ├── middleware/ │ │ ├── auth.js # requireAuth() │ │ ├── roles.js # requireWriter(), requireAdmin() │ │ └── utils.js # Re-exports from lib/sanitize + roles │ └── routes/ │ ├── auth.js # Register · login · passkey · lockout │ ├── queries.js # KQL CRUD · star · import · export │ ├── folders.js # Folder CRUD │ ├── comments.js # Per-query comments │ ├── investigations.js # Investigations · IoCs · findings · reports │ ├── templates.js # Report templates (admin) │ ├── settings.js # System + report settings (admin) │ ├── fingerprint.js # Environment profiles + compatibility │ ├── repos.js # GitHub repo sources + sync │ ├── watch.js # Threat feeds + articles │ └── admin.js # User/team/audit management ├── scripts/ │ └── sync-repos.js # Standalone repo sync runner ├── docs/ │ └── API.md # Full REST API reference ├── .env.example ├── .gitignore ├── CHANGELOG.md ├── LICENSE └── package.json ``` ## 故障排除 **`better-sqlite3` 编译失败 (Windows)** 安装 [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) 后运行 `npm install`。 **端口 3000 已被占用** ``` netstat -ano | findstr :3000 taskkill /PID /F ``` 或者在 `.env` 中设置不同的 `PORT=`。 **Passkey 无法使用** WebAuthn 在 `localhost` 上无需 HTTPS 即可工作（Chrome、Edge）。任何其他主机名均需要 HTTPS。 **重置数据库** ``` rm backend/db/kqlvault.db npm start # re-seeds with demo data automatically ``` ## 更新日志 有关完整的版本历史，请参阅 [CHANGELOG.md](CHANGELOG.md)。 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

标签：AES-256-GCM, ATT&CK映射, Azure Sentinel, Cloudflare, DInvoke, Express, FIDO2, GNU通用公共许可证, JSONLines, KQL, Kusto查询语言, Microsoft Defender, MITM代理, MITRE ATT&CK, MIT开源, Node.js, Passkey, PICERL, SQLite, WebAuthn, 加密数据库, 团队协作, 安全运营中心, 无密码认证, 本地部署, 查询管理平台, 网络安全, 网络映射, 自定义脚本, 自托管, 速率限制处理, 隐私保护, 零信任