hegazi-sec/nullshift

## 什么是 NullShift？ **NullShift** 是一款面向 L1 SOC 分析师的开源 AI 助手。它可以接入您的 SIEM，针对当前的告警检索正确的 playbook，执行确定性的调查步骤，结合威胁情报丰富 IOC 的上下文，并生成结构化的报告——这样分析师就可以将时间花在那 5% 真正重要的检测上，而不是 95% 看起来可疑但实际上并无问题的告警上。 它兼容所有主流 LLM 提供商——Anthropic Claude、OpenAI GPT 或完全本地的 Ollama 模型——并且开箱即支持连接到 **LimaCharlie**、**Wazuh**、**Splunk**、**Elastic** 或 **Microsoft Sentinel**。 ## 核心亮点 - 🧠 **12 种 LLM 提供商** — Claude Agent SDK（使用您的 Claude 订阅，无需 API 密钥）、云 API 或完全本地的 Ollama（甚至可以通过 Tailscale 托管在另一台机器上）。 - 🔌 **5 种 SIEM 连接器** — Wazuh、LimaCharlie、Splunk、Elastic、Sentinel。 - 📚 **基于您自有 playbook 的 RAG** — 将 markdown 文件放入 `data/kb/` 即可自动索引。 - 📋 **结构化调查报告** — 第 1 部分（证据）→ 第 2 部分（推理）→ 第 3 部分（结论）。 - 🎯 **L1 → L2 交接模式** — 通过单一命令生成可直接用于工单的摘要。 - 🔧 **支持针对单个用户的 temperature 设置、对话搜索、结论追踪和 debug 跟踪。** - 💻 **适用于日常运维的 CLI** — `nullshift start/stop/status/logs`。 - ⚡ **单条命令完成设置** — 无需配置文件，无需手动步骤。 ## 快速开始 ``` git clone https://github.com/hegazi-sec/Ai-ChatBot.git cd Ai-ChatBot/nullshift python setup.py ``` 设置向导会创建一个虚拟环境，安装依赖项，生成 JWT 密钥，创建您的管理员账号，引导您完成 SIEM + LLM 配置，并在后台启动服务器。 完成后，在浏览器中打开 **http://localhost:58443**。 ## CLI 设置完成后，您可以在任何终端管理服务器： ``` nullshift start # start the server in the background nullshift status # check if it's running, see URL + PID + uptime nullshift logs # stream live server logs (Ctrl+C to exit) nullshift stop # stop the server nullshift restart # restart nullshift update # pull latest from GitHub, refresh deps, restart nullshift setup # re-run the configuration wizard ``` ## 环境要求 - Python **3.11+** - macOS、Linux 或 Windows 10+ - 至少配置一种 LLM 选项（见下文） 可选：SIEM 凭证（Wazuh / LimaCharlie / Splunk / Elastic / Sentinel）以及用于 IOC 丰富的 VirusTotal API 密钥。 ## LLM 选项 NullShift 不依赖于特定的提供商。请根据您的环境选择合适的方案： ### 🆓 Claude Agent SDK *（无需 API 密钥）* 如果您拥有 **Claude.ai Pro 或 Max 订阅**，NullShift 可以通过本地的 **`claude` CLI** 直接驱动 Claude——无需 API 密钥，也无需按 token 计费。NullShift 的设置向导会检测该 CLI 并引导您完成一次性的 `claude login`。 最适合个人分析师以及运行在个人 Claude 订阅上的家庭实验室 SOC。 ### 🌐 云端 API 密钥 在 **Admin → LLM Providers** 中为以下任意服务粘贴密钥： - **Anthropic**（`claude-sonnet-4-6`、`claude-opus-4-7` 等） - **OpenAI**（`gpt-4.1`、`gpt-4o` 等） - **Google Gemini、Groq、xAI、DeepSeek、Perplexity、OpenRouter、Qwen、Kimi** ### 🖥️ 本地 Ollama *（完全离线）* 在本地运行任何兼容 Ollama 的模型——`qwen2.5:14b`、`llama3.3:70b`、`deepseek-r1`、`phi4` 等。**无需 API 密钥**，数据也不会离开您的网络。请在 **Admin → LLM Providers** 中配置 Ollama 的 URL。 ## 配置 几乎所有配置都可以通过位于 `/admin` 的 **Admin UI** 完成——任何设置的更改均无需重启即可生效。 - **LLM Providers** — 固定活动的提供商，拖拽设置 fallback 链，粘贴 API 密钥。 - **Connectors** — SIEM 凭证 + VirusTotal。保存前请测试连接。 - **RAG** — embedding 提供商、模型、实时索引状态。 - **Users** — 管理分析师账号（admin、L1、L2 角色）。 设置会持久化保存在 SQLite 数据库（`app/data/config.db`）中。得益于 `app/config.py` 中的设置代理层，所有更改都会立即应用。 ## 架构（简述） ``` User message → FastAPI route ↓ Mode + intent detection (deterministic, no LLM) ↓ PlaybookRunner — best-match playbook fires its SIEM queries ↓ run_investigation() — fallback keyword-based SIEM hunt ↓ VirusTotal IOC enrichment ↓ RAG retrieval — pull relevant playbook chunks from Chroma ↓ LLM provider chain (Anthropic → OpenAI → Ollama → ...) ↓ Structured Markdown report (SECTION 1 / 2 / 3 with Verdict + Confidence) ``` ## 仓库结构 ``` nullshift/ ├── app/ │ ├── main.py FastAPI routes │ ├── llm.py LLM provider chain │ ├── rag.py Chroma-based playbook retrieval │ ├── connectors/ SIEM + VirusTotal clients │ ├── execution/ Investigation pipeline │ ├── playbooks/ Playbook runner (YAML front-matter) │ ├── db/ SQLite stores │ ├── static/ Logo, favicon │ └── *.html UI pages (chat, admin, login, setup) ├── data/ │ └── kb/ Markdown playbooks (RAG corpus) ├── tests/ pytest unit tests ├── setup.py Interactive setup wizard ├── cli.py Daemon management CLI └── requirements.txt ``` ## 知识库与引用致谢 NullShift 在 `data/kb/` 目录中内置了 **四个 NullShift 专属的顶层 playbook**，涵盖了常见的 L1 分诊场景——SSH 暴力破解、端口扫描、恶意软件检测和 Web 攻击。 大部分被索引的内容库源自 **Anthropic-Cybersecurity-Skills** 项目： **我们使用了上游项目中的哪些内容：** NullShift 仅内置了原仓库中经过精选的子集——具体为 **`skills/`** 文件夹（涵盖 26 个网络安全领域的 753 个 SKILL.md playbook）和 **`mappings/mitre-attack/`** 文件夹（MITRE ATT&CK 技术对齐）。为了保持 NullShift 精简的安装体积，我们移除了仓库的元文件、CI 工作流、plugin 清单以及无关的资产。 每个被索引的 skill 都包含分步操作流程、工具命令、预期输出以及 MITRE ATT&CK 映射。`data/kb/cybersecurity-skills/` 中的捆绑副本保留了原始的 `LICENSE`、`README.md` 和 `CITATION.cff`，完全符合 Apache 2.0 协议。 ## 技术栈 - **后端** — [FastAPI](https://fastapi.tiangolo.com/) + [Pydantic](https://docs.pydantic.dev/) + [uvicorn](https://www.uvicorn.org/) - **前端** — 原生 HTML + CSS + JS（无构建步骤，无框架） - **LLM SDK** — [`anthropic`](https://github.com/anthropics/anthropic-sdk-python) + [`openai`](https://github.com/openai/openai-python)（与提供商无关的适配层） - **RAG** — [ChromaDB](https://www.trychroma.com/) - **认证** — 存放在 HttpOnly cookies 中的 JWT (HS256)，使用 `passlib` 进行密码哈希处理 (pbkdf2_sha256) - **持久化** — 两个 SQLite 数据库（WAL 模式）：`config.db`（设置）+ `chat.db`（用户数据） ## 路线图 - 一键设置额外的 SIEM（CrowdStrike、Microsoft Defender for Endpoint） - 案例管理 — 将多个调查组合并到一个带有时间线的单一案例文件中 - 在得出结论时发送 Webhook 通知（Slack / Teams / 电子邮件） - 定时狩猎（基于差异告警的周期性查询） - 多租户 L2 升级队列 ## 支持与项目状态 这是一个正在积极维护的项目——我构建 NullShift 是希望它能成为我们都可以依赖的工具，而不仅仅是一个副业实验。**您的反馈将决定其发展路线图。** **如果任何功能的运行未达到您的预期**，请在 GitHub 上[提交一个 issue](https://github.com/hegazi-sec/Ai-ChatBot/issues)。我会尽最大努力快速回复并发布修复补丁。 ### 连接器成熟度 | 状态 | 连接器 | 备注 | |---|---|---| | ✅ **生产就绪** | **LimaCharlie** | 测试最充分。推荐用于生产环境。 | | ✅ **生产就绪** | **Wazuh** | 测试最充分。推荐用于生产环境。 | | 🧪 **Beta — 正在积极测试中** | **Splunk** | 功能正常。会随着发现边缘案例而推送更新。 | | 🧪 **Beta — 正在积极测试中** | **Elasticsearch** | 功能正常。会随着发现边缘案例而推送更新。 | | 🧪 **Beta — 正在积极测试中** | **Microsoft Sentinel** | 功能正常。会随着发现边缘案例而推送更新。 | 如果您正在使用其中一个 Beta 版连接器并遇到了问题，**请告诉我**——这是将其修复并升级为生产就绪状态的最快方式。 ## 许可证 NullShift 基于 [Apache License 2.0](LICENSE) 协议发布。 ## 作者 由 **Ahmed Hegazi** 构建并维护。

标签：AI风险缓解, DLL 劫持, RAG, SIEM集成, SOC助手, 告警分诊, 大语言模型, 安全运营, 扫描框架, 逆向工具