dllswbr/threep

向您的政策文档提问。获取带有引用的回答——如果缺乏证据，也会如实告知“未涵盖”。

**threep** 是一个用于合规问答的本地 RAG 助手。上传您的政策文档，用自然语言提问，即可获得结构化的回答，这些回答会引用其源自的确切政策章节——并且每个回复都会映射到一个 NIST SP 800-53 控制。 当您的政策未涵盖某项内容时，threep 会如实相告。覆盖状态是明确的：`YES`、`PARTIAL`、`NONE` 或 `UNKNOWN`。这里绝没有凭空捏造却听起来煞有介事的答案。 默认运行在 [Ollama](https://ollama.com) 上。除非您主动选择，否则任何政策文本都不会离开您的本机。 ## 适用人群 - 准备迎接 FedRAMP、SOC 2 或基于 NIST 审计的 **GRC 从业者和 InfoSec 工程师** - 需要根据真实政策集来回答第三方问卷的 **政策所有者** - 希望了解当前政策已涵盖、部分涵盖或遗漏了哪些 NIST SP 800-53 控制的 **安全团队** - **任何**曾尝试向 LLM 询问内部政策，却得到一个没有引用来源、无法向审计员交代的自信回答的**人** ## 为什么基于证据的回答很重要 大多数基于 LLM 的工具会用听起来很合理的内容来回答合规问题。在合规语境下，这是一个大问题：一个引用了错误章节，或描述了实际并不存在于您政策中的控制的自信回答，可能会通过问卷流程并成为隐患。 threep 采取了截然相反的方法。每一个回答都建立在从您上传的政策文档中检索到的文本块上。如果一个问题无法根据证据作出回答，系统会返回 `NONE` 或 `UNKNOWN`，而不是构建一个听起来似乎合理的段落。每次回复都会包含政策引用，以便进行独立核实。 ## 示例输出 **问：远程访问是否需要 MFA？** ``` Yes, MFA is required for all remote access at Meridian Software, including VPN and cloud consoles. Approved methods include TOTP authenticator apps and hardware security keys (FIDO2), but SMS OTP is prohibited for privileged access. ```  *通俗易懂的合规回答——快速且直接。* **诚实的差距分析，提供完整的政策和控制上下文。** **问：我们如何满足 SA-9 外部系统服务？** ``` Summary: Not evidenced. No policy in the loaded document set addresses SA-9 External System Services. Coverage status: Not evidenced in the provided policy excerpts. Policy Coverage: - (No policy snippets found in context) ```  *诚实的差距：SA-9 外部系统服务返回 NONE ——没有捏造的覆盖范围。* ## 快速入门 **需要 Python 3.10 或更高版本。** ``` # 克隆并设置 git clone https://github.com/dllswbr/threep.git && cd threep python3 -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt # 配置（复制并可选设置 ORG_NAME） cp .env.example .env # 拉取模型并构建索引 ollama pull qwen2.5:14b python3 ingest.py # 启动 uvicorn app:app --reload # → http://127.0.0.1:8000 ``` **LLM 后端 — Ollama（推荐）：** 从 [ollama.com](https://ollama.com) 安装并验证其是否正在运行（`ollama list` 应能正常返回）。如果您使用的是较旧的 Mac 或低配机器，请参阅 [如果您无法在本地运行 Ollama](#if-you-cannot-run-ollama-locally)。 ## 尝试示例策略 四个虚构的 **Meridian Software** 政策随附在 `sections/policies/_samples/` 中。默认情况下它们**不**会被索引——`ingest.py` 会跳过任何 `_*` 子目录，因此示例内容永远不会与您的真实语料库混淆。 要尝试它们，请执行： ``` cp sections/policies/_samples/*.md sections/policies/ python3 ingest.py ``` 然后提问： | 问题 | 预期覆盖范围 | |---|---| | *"密码复杂性要求是什么？"* | YES — 最低14位，复杂性规则 | | *"远程访问是否需要 MFA？"* | YES — 需要 VPN + MFA | | *"应如何处理严重事件？"* | YES — 升级时间表、遏制、恢复 | | *"组织是否要求职责分离？"* | YES — 代码、财务和配置变更分离 | | *"是否有 BYOD 政策？"* | UNKNOWN — 示例集中未涵盖 | 当您准备好使用您自己的政策时，删除复制的文件并按照[添加策略](#adding-policies)中的步骤操作。 ## 工作原理 1. **摄取 (Ingest)** — `ingest.py` 使用 [sentence-transformers](https://www.sbert.net/) 将您的政策 Markdown 文件和内置的 NIST SP 800-53 Rev 5 源文件分块，并生成独立的嵌入索引。 2. **路由 (Route)** — 每个问题都会被分类为合规问题（映射到 NIST 控制）、一般政策问题、评估模式查询或 NIST CSF 类别声明。 3. **检索 (Retrieve)** — 政策文本块和 NIST 控制文本块从独立的命名空间中分别检索。政策回答会引用您的政策文本；NIST 仅作为支持性参考出现。 4. **回答 (Answer)** — LLM 生成结构化的响应：`Summary → Policy Coverage → Supporting NIST Reference → Implementation Details`。覆盖状态（`YES`/`PARTIAL`/`NONE`/`UNKNOWN`）在生成后强制执行——模型被指示使用 `UNKNOWN` 或 `PARTIAL`，而不是捏造覆盖范围。 5. **返回 (Return)** — 应用程序返回结构化的回答，并在 UI 中提供可点击的章节引用。 ## 证据纪律的基准测试 大多数 AI 评估都在询问答案听起来是否合理。在合规工作中，这是远远不够的。 threep 的评估标准在于：答案是否基于真实的文档，声明是否可审查，以及差距是否被如实陈述。目标不仅仅是产出答案，而是产出经得起检查、质疑和改进的答案。 ### 我们衡量什么 - **依据性 (Grounding)** — 答案是否保持与源语料库的联系，而不是附上装饰性或无关的引用。 - **克制性 (Restraint)** — 系统是否能避免夸大文档实际证明的内容，特别是当存在政策语言但缺乏实施证据时。 - **输出控制 (Output control)** — 答案是否保持可读、有界且结构严谨，而不是冗长杂乱或拼凑字数。 - **覆盖诚实度 (Coverage honesty)** — 正确的回复是否有时是 `PARTIAL` 或 `GAP`，而不是被强制转为确定。 ### v1 基线改进 在包含 120 个 NIST SP 800-53 问题的测试集上，针对真实的政策语料库进行了评估： - 引用重复现象急剧减少 - 无根据的引用使用急剧减少 - 跨文档污染显著减少 - 违规实施动词降至零 - `PARTIAL` 被引入为第一类回答状态 - 章节篇幅泛滥得到限制和控制 基准测试工件和评分结果位于 [`benchmarks/`](benchmarks/)。 ### 这些基准不 claims 什么 这些评估本身并不能证明法律上的充分性、控制的有效性或审计准备就绪。 它们旨在衡量依据性、引用行为、输出纪律以及对不确定性的诚实度。threep 旨在支持人工审查，而非取代它。 ## Docker 快速入门 ``` git clone https://github.com/dllswbr/threep.git && cd threep cp .env.example .env # 按需编辑 .env 以设置 ORG_NAME 和 LLM config docker compose up # → http://localhost:8000 ``` Ollama **未**打包在镜像中。默认情况下，`OLLAMA_URL` 设置为 `http://host.docker.internal:11434`，该地址会连接到运行在您宿主机上的 Ollama。如果 Ollama 运行在其他地方，请在 `.env` 中设置 `OLLAMA_URL`。 如果要改用 OpenAI，请在运行 `docker compose up` 之前，在 `.env` 中设置 `LLM_PROVIDER=openai` 和 `OPENAI_API_KEY`。 您的 `sections/`、`data/` 和 `images/` 目录会挂载到容器中，以便索引和政策文件在重启后依然存在。 ## 如果您无法在本地运行 Ollama **选项 A — 远程 Ollama** 将 threep 指向运行在您网络中另一台机器（或云 VM）上的 Ollama 实例： ``` OLLAMA_URL=http://192.168.1.x:11434 ``` 在运行 `python3 ingest.py` 之前在 `.env` 中设置此项。 **选项 B — OpenAI** 1. 在 [platform.openai.com](https://platform.openai.com) 创建账户（与 ChatGPT 订阅分开——API 访问需要计费额度）。 2. 生成 API 密钥。 3. 在 `.env` 中设置： LLM_PROVIDER=openai OPENAI_API_KEY=sk-... 4. 运行 `pip install openai`（默认不在 requirements.txt 中）。 5. 继续执行 `python3 ingest.py` 和 `uvicorn app:app --reload`。 ## 功能特性 | 功能 | 描述 | |---|---| | **合规 Q&A** | 用自然语言提问，回答带有政策引用和 NIST SP 800-53 控制映射 | | **评估模式** | 切换为正式的第三人称回复——专为外部问卷和审计提交构建的结构化形式 | | **NIST 覆盖矩阵** | 可视化网格展示 SP 800-53 控制在您的政策集中的覆盖情况：已覆盖、部分覆盖或未覆盖 | | **差距跟踪** | 标记未覆盖的控制并跟踪整改进度 | | **策略管理器** | 上传 DOCX 文件——自动转换为 Markdown 并建立索引 | | **策略编辑器** | 在浏览器中编辑政策内容，一键保存并重新索引 | | **审查日期** | 每个政策的审查截止日期，配有绿色/琥珀色/红色状态指示器 | | **LLM 快速预览** | 悬停在任何政策上，即可获取 AI 生成的 2-3 句摘要 |  *IA-5 Authenticator Management 返回 PARTIAL ——找到了真实证据，指出了具体差距并提供了实施清单。* ### 评估模式 当评估模式激活时，答案会从要点式的问答切换为陈述性的第三人称段落，专为外部审计员和问卷回复格式化——例如，*"The organization maintains an Access Control Policy (POL-AC-001) which requires..."* 而不是 *"Your policy says..."*。这在您填写供应商安全问卷或为评估准备证据叙述时非常有用。  *批量评估运行，返回一组控制的多个判定结果。* ## 环境变量 将 `.env.example` 复制到 `.env`。所有变量都是可选的——默认配置在本地安装 Ollama 后即可开箱即用。 | 变量 | 默认值 | 描述 | |---|---|---| | `ORG_NAME` | `the organization` | LLM 在回答中如何称呼您的组织（例如 `Acme Corp`） | | `OLLAMA_URL` | `http://127.0.0.1:11434` | Ollama API 基础 URL | | `OLLAMA_MODEL` | `qwen2.5:14b` | 由 `ollama list` 显示的模型名称 | | `OLLAMA_TEMPERATURE` | `0.2` | LLM 温度 (0.0–1.0) | | `OLLAMA_NUM_PREDICT` | `1536` | 每次响应的最大 token 数 | | `OLLAMA_TIMEOUT` | `300` | 请求超时时间（秒） | | `LLM_PROVIDER` | `ollama` | 设置为 `openai` 以使用 OpenAI | | `OPENAI_API_KEY` | *(未设置)* | 如果 `LLM_PROVIDER=openai` 则为必填项 | | `OPENAI_MODEL` | `gpt-4o` | OpenAI 模型名称 | ## 添加策略 **通过 UI 上传** — 打开应用，在左侧栏展开 **Manage Policies**，并上传一个 `.docx` 文件。流水线会将其转换为 Markdown，摄取它，并自动更新索引。 **手动 (Markdown)** — 将 `.md` 文件直接放入 `sections/policies/` 并运行： ``` python3 ingest.py ``` **手动 (DOCX 批处理)** — 将 `.docx` 文件放在仓库根目录的 `docxs/` 文件夹中，进行转换，然后摄取： ``` mkdir docxs # 将您的 .docx 文件复制到 docxs/ python3 tools/export_docx_to_md.py # writes .md files to sections/policies/ python3 ingest.py ``` ## 目录结构 ``` threep/ ├── app.py # FastAPI application ├── ingest.py # Index builder (policies + NIST) ├── Dockerfile ├── docker-compose.yml ├── requirements.txt ├── sections/ │ ├── policies/ # Your Markdown policy files go here │ │ ├── _samples/ # Fictional demo policies — skipped by ingest.py │ │ └── local/ # Private policies (gitignored) │ ├── mappings/ │ │ └── policy_nist.json # Curated policy → NIST control mappings │ └── nist/ # NIST SP 800-53 Rev 5 source data ├── data/ # Embedded indexes (gitignored, built by ingest.py) ├── threep_core/ # Core library (routing, retrieval, answer formatting) ├── web/ # Single-page UI (chat.html, app.js) └── tests/ ``` ## 运行测试 ``` PYTHONPATH=. python3 -m unittest discover -s tests -q ``` ## 许可证 [MIT](LICENSE)

标签：AI助手, AI风险缓解, DLL 劫持, FedRAMP, GRC, IT审计, LLM, LLM评估, meg, NIST SP 800-53, NLP, Ollama, OpenAI, Python, RAG, SOC 2, Unmanaged PE, 人工智能安全, 信息安全, 内存规避, 合规性, 向量化, 大语言模型, 安全合规, 控制项映射, 政策文件解析, 文本分析, 文档问答, 无后门, 本地部署, 检索增强生成, 私有化部署, 网络代理, 证据支撑, 请求拦截, 逆向工具, 防御规避, 隐私优先