Skip to content

Security: keith-yan/vibe-service-guardian

SECURITY.md

安全设计

本地控制面

  • HTTP 服务硬编码绑定 127.0.0.1,不提供修改为 0.0.0.0 的设置。
  • Windows 控制端口使用 SO_EXCLUSIVEADDRUSE,其他平台关闭地址复用;端口被旧实例或其他进程占用时选择下一个候选,不复用或抢占现有监听。
  • 所有请求校验客户端地址和 Host,只接受当前端口的 127.0.0.1localhost,降低 DNS rebinding 风险。
  • 状态变更接口要求随机控制令牌和同源 Origin;不返回 CORS 许可头。
  • 页面启用 CSP、X-Frame-Options: DENYnosniffno-referrerCross-Origin-Resource-Policy: same-origin 和受限 Permissions-Policy
  • 请求连接设置 10 秒超时;拒绝 Transfer-Encoding 请求,请求体上限为 64 KiB。
  • 旧实例探测/停止客户端只接受无凭据、无查询或片段的显式回环 HTTP 地址,响应体上限 1 MiB,不读取代理设置。
  • 同一数据目录发现已验证的其他版本实例时,只打开该回环控制台并记录最小冲突摘要;记录不含数据目录、控制令牌、环境变量或远端地址。

Windows 桌面集成

  • 原生托盘、全局快捷键和当前用户开机启动均默认关闭,不改变既有进程控制权限。
  • 快捷键只允许 disabledCtrl+Alt+G;注册失败只降级为无快捷键,不抢占其他应用,也不提升权限。
  • 开机启动仅支持冻结的 Windows 便携 EXE,只操作当前用户 HKCU Run 键;启用/禁用分别要求 ENABLE STARTUPDISABLE STARTUP
  • 若固定注册表值已指向其他目标,工具拒绝覆盖或删除。不安装系统服务、不写 HKLM、不请求管理员权限。
  • Web 安全退出要求 EXIT VSG,只关闭 VSG 的采集、观察、工作负载和本地数据库,不停止任何被监控服务。

进程操作

  • 只允许停止当前快照中已识别的普通宿主机开发或模型推理运行时;LM Studio 主程序保持只读。
  • 通过 PID 和创建时间双重校验抵御 PID 复用;子进程同样在发信号前逐一复核身份。
  • 拒绝当前工具、其父进程、Windows/macOS/Linux 核心进程和 Agent/IDE 主进程。
  • 如果子进程树中包含受保护进程,整次操作不执行。
  • 不支持按名称批量结束,不支持自动清理。
  • Agent 本体、Windows 服务、Docker 与 WSL 只读展示。
  • 停止前展示基于当前本机 TCP 连接、监听端点、项目/Agent 和生命周期证据的影响评估;评估不能证明外部客户端不存在。
  • 停止后只在有限窗口内观察原 PID/子进程、端口和替代 PID。即使检测到自动重启,也不会自动结束替代进程;局部终止错误和仍存活 PID 会进入验证证据,不会伪装成完整成功。
  • 0.8.4 持续观察只允许 5/15/30 分钟、10 秒轮询、单机最多 8 个活动任务,可随时协作式中止。只有原 PID 身份先消失,随后原端口重新监听或同一脱敏命令哈希在其他 PID 出现,才记录复活;父进程变化本身不构成复活证据。
  • 可继承生命周期标签使用“规范化可执行路径 + 规范化工作目录”的单向 SHA-256。标签不读取目标进程环境变量;“可安全清理”只提高复核优先级,不能降低保护、扩张停止白名单或省略 STOP <PID>
  • Agent/IDE、Docker、WSL、Windows 服务及可识别托管器的推荐操作只以 argv 和显示文本返回,并固定 will_execute: false;没有执行建议命令的 API。
  • 项目级安全清理只生成预览,没有批量停止 API。每个候选在进入现有停止弹窗时都重新读取当前快照和关停评估,并继续要求独立的 STOP <PID> 确认;历史“可安全清理”标签不能绕过受保护或受管阻断。

模型容量与本地基准

  • 容量计算只读取本机硬件摘要、内置离线目录和用户表单,不联网、不调用模型提供方 API。
  • 推荐启动命令只返回文本模板,固定绑定 127.0.0.1,服务端不会执行模板或自动下载模型。
  • 本地基准默认禁用;只有检测到 llama-bench、请求携带当前控制令牌并准确输入 BENCHMARK 时才执行。
  • 基准只接受已存在的绝对 .gguf 普通文件,以参数数组且 shell=False 启动,固定短参数并设置 300 秒超时。
  • 解析器只保留 tokens/s、token 数、线程和 GPU layers 等数值;不持久化绝对路径或上游 JSON 中的任意字符串。
  • 运行基准会消耗本机 CPU/GPU/内存,但不会启动长期监听服务;该动作进入本地审计日志。

本地模型盘点与归属规则

  • 模型盘点仅在用户选择绝对目录并准确输入 SCAN MODELS 后执行;拒绝文件系统根、用户主目录、符号链接和 Windows 目录联接。
  • 单次限制 5000 文件、6 层和 120 秒;不跟随链接,GGUF/Safetensors 元数据最多读取 16 MiB,配置头最多读取 2 MiB。GGUF 数组递归深度、Safetensors 张量维度/乘积和持久化字符串另有硬上限。
  • 快速指纹只读取文件首尾有界片段,不执行、下载、移动、删除、重命名或修改任何模型文件;绝对扫描根不持久化。
  • .vsg.yaml 限制为项目目录中的 64 KiB 普通 UTF-8 文件,仅解析受支持的简单字段,拒绝标签、锚点、别名和变量替换;JSON 形式必须声明 version: 1。规则覆盖的项目路径必须位于设置中的项目根目录,项目清单和本地规则只能增加保护,不能取消内置或既有保护。
  • 规则冲突先按具体度、再按同范围最新用户意图确定唯一胜出规则;候选和决胜原因保留在服务证据中。规则在不同服务生命周期中被多次覆盖只会标记“建议复核”,不会自动调权、禁用或停止进程。
  • 编辑、启用、禁用、回滚和删除分别需要 UPDATE RULEENABLE RULEDISABLE RULERESTORE RULEDELETE RULE 精确确认短语;按类别清除历史需要 CLEAR HISTORY。历史清除只操作 VSG 数据库表,不删除用户原文件。
  • 规则包最大 256 KiB/500 条,校验 canonical SHA-256;导出省略绝对路径、完整命令、备注和非便携选择器,导入先预览候选/冲突并要求逐条绑定当前服务。没有云同步或透明跨机匹配。

模型服务体检与显式诊断

  • 被动运行时探测仅连接快照中已识别模型服务的 127.0.0.1:<port>;HTTP 客户端不使用代理、不跟随重定向,单次超时不超过 2 秒,响应体上限 512 KiB。
  • 探测不读取进程环境变量或配置中的 API Key。认证端点返回 401/403 时只记录“需要认证”,不会尝试绕过。
  • Docker 元数据采集使用固定 9 字段格式模板,不调用无格式限制的完整 inspect,不请求 .Config.Env 或完整标签集合。
  • 主动服务短基准要求准确输入 BENCHMARK <端口>,且只允许已识别、健康就绪、无需密钥的本机模型服务。并发限制 1–4、上下文 128–4096、输出 1–64;内存占用超过 85% 时拒绝开始,不通过扩大负载故意制造 OOM。
  • 基准提示是固定合成文本,不含项目代码、聊天内容或用户数据;响应正文不写入数据库。
  • 固定工作负载矩阵要求先完整预览并准确输入 BENCHMARK PLAN <端口>。矩阵固定为并发 1/2/4 三步、最多 20 个请求/步,单机只允许一个活动任务;每步前复核 RAM、VRAM、温度、磁盘和服务身份,不自动扩档或故意制造 OOM。
  • 0.8.4 的本机校准只允许运行时已报告的已加载模型、并发 1 或 2、固定 60 秒,并要求计划专属 BENCHMARK <端口>。它不下载/加载模型、不修改配置,最多保留 120 个请求预算。
  • 校准期间持续重查资源;RAM 或 VRAM 达到 85% 后设置协作式取消,不发起后续请求波次。采集器快照可能滞后于瞬时峰值,因此该护栏降低风险但不能保证绝不 OOM;在途请求不会被强杀。
  • 60 秒校准缺少 RAM 占用证据时拒绝开始;若遥测已报告独立 GPU 和显存总量但没有任何 VRAM 占用读数,同样拒绝。普通固定矩阵维持既有的“未知项明确显示”行为。
  • 实测档案绑定硬件指纹与总 VRAM。硬件不匹配时自动降级为“可能失效”;恢复活动状态不能覆盖此判断。删除单条档案需要 DELETE PROFILE <ID>,且只删除 VSG SQLite 记录。
  • 中止只阻止后续请求波次,不强杀已经发出的本机推理请求。带认证的服务不进入矩阵,VSG 不读取或代填 API Key。
  • 同负载容量校准要求硬件指纹、目录模型、量化、并发、上下文和输出长度全部匹配;不符合条件的样本不会作为精确校准。
  • 日志/配置检查要求准确输入 INSPECT <PID> 和用户选择的绝对普通文件。拒绝符号链接、.env、已知凭据文件及私钥格式;日志最多 100 MiB,只读末尾 1 MiB/2000 行,配置最多 2 MiB,返回前脱敏且不持久化。
  • 持续日志监控另行要求 WATCH <PID>,只允许当前快照中已识别的宿主机模型推理服务。游标绑定服务指纹、PID 和启动时间;创建时间无法验证或身份变化即记录退出事件并停止,不自动跟随新进程。单机最多 32 个活动游标,每轮最多读取 256 KiB;原始行不入库,接口不返回绝对路径或本地文件错误路径,停用同样要求该确认短语。
  • 手工受信节点只允许无凭据、无查询串、无额外路径的 HTTP 回环/私网/链路本地地址。每次连接前重新解析并拒绝未指定、多播、保留和公开地址,不提供 LAN 扫描或自动发现。

快照与回滚

  • 文件清单要求 SNAPSHOT,只接受 1–100 个去重后的绝对普通文件,不递归目录或跟随符号链接。单文件超过 512 MiB 不做完整 SHA-256,单次快照总哈希预算为 1 GiB,大模型不自动复制。
  • 小型常见配置可按原样复制以保证回滚可用;已知 .env、凭据、私钥、证书和密钥库文件只写清单,绝不复制。自定义文件仍可能含工具无法识别的秘密,因此数据目录必须依赖当前用户 ACL/POSIX 权限,不能放在共享目录。
  • 快照失败会清理未完成目录。回滚要求 RESTORE <文件名>,从受限快照根读取;写入前再次确认原目标未被符号链接/目录链接重定向,保存唯一的回滚前副本并使用同目录临时文件原子替换。工具不会自动重启被影响服务。

优化与引擎建议

  • 引擎排名是本地确定性兼容性筛选,不执行安装、不下载权重、不修改驱动、环境、功耗、风扇或模型配置。
  • Windows 上的 Linux 原生引擎只有在用户允许且 WSL2 已检测,或用户明确接受 NVIDIA Docker/WSL GPU 路径时才进入预览候选;这不等于桥接环境内驱动和依赖已验证。
  • 硬件建议只使用实测遥测、用户工作负载、运行时健康和脱敏日志事件;传感器缺失保持未知。
  • 只有模型名、并发、上下文与输出长度一致的不同运行时基准进入比较组,避免跨负载误导。

数据最小化

  • 不枚举目标进程环境变量,不采集浏览器状态、网络包正文、DNS 名称、URL 或应用层内容。程序只读取自身使用的本地路径配置变量,完整清单见 PRIVACY.md
  • 当前快照可展示已识别模型进程的远端 IP/端口与作用域,以发现意外联网;这些地址不写入服务历史数据库,也不据此声称发生了上传。
  • 连接生命周期历史只保存远端端点的不可逆摘要、作用域、协议和端口;网络拓扑中的原始远端 IP 标记为仅当前快照。
  • 命令参数先对敏感选项、凭据 URI、查询参数和常见供应商 Token 脱敏再进入快照;历史库仅保存脱敏命令的 SHA-256。
  • Codex/Claude 会话读取限制在近期 JSONL 的元数据字段;Hermes/OpenCode 只查询会话元数据表;Gemini 只读取会话文件名和修改时间。提示词和回复不会写入本工具数据库。

本机成效证据

  • 服务人工确认只接受固定枚举值,并按服务指纹 upsert;不接收自由文本、路径或上传地址。
  • /api/impact 只返回白名单聚合字段。报告不会序列化服务快照中的 PID、路径、IP、命令、会话 ID、日志或模型响应。
  • 下载成效 JSON 是带控制令牌的状态变更请求,必须精确输入 EXPORT REPORT;文件由浏览器在用户动作中生成,服务端不写外部目录、不联网、不自动上传。
  • 报告包含规范化内容 SHA-256,便于发现后续编辑;摘要不是签名,不能证明报告来自独立用户或未被有权限的本机用户重建。
  • 报告固定披露“单机自报、受保留期限制、外部采用未验证”。移除该边界不属于展示层改文案,而是证据治理变更。

权限

默认以当前用户运行,不请求管理员权限或 sudo。对于无权读取的进程,界面显示“可见性受限”,不会静默提权。macOS 的 lsof 非提权采集只保证当前用户可见端口;部分系统 PID、跨用户进程、命令和工作目录缺失属于明确披露的边界。

POSIX 数据目录尽力使用 0700,配置、数据库、日志和运行实例文件尽力使用 0600。Windows 使用所在目录继承的 ACL;不应把便携目录放到多用户共享位置。

支持版本

安全修复只进入当前未发布分支和最新发布版本。历史便携包不会被原地覆盖,使用者应升级后再报告问题。

构建与依赖

  • 0.8.3 构建/安装脚本使用 20 份按操作系统与 Python 3.10–3.12 区分的 wheel 锁;每个包必须精确版本、SHA-256 匹配、--require-hashes--only-binary=:all:,运行/构建锁再配合 --no-deps,避免隐式解析或执行源码包构建逻辑。
  • 本地发布检查包含依赖漏洞审计、Ruff、Bandit 中/高风险门槛、公开目录审计、测试、归档路径/体积/许可证/SBOM 校验。
  • scripts/Requirement-Locks.py --verify 离线核对源依赖摘要、锁文件集合与锁文件摘要;维护者显式执行 --generate 时只允许公开 PyPI HTTPS、清空 pip 私有配置并重新解析 wheel。哈希锁能固定已选择的归档,但不能替代上游维护者可信度审查、漏洞响应和发布签名。

报告漏洞

仓库已启用 GitHub Private Vulnerability Reporting。疑似安全漏洞请通过私密报告入口提交,并提供最小复现、受影响版本、平台、影响说明和已脱敏证据。

不要在公开 Issue、Discussion 或 PR 中披露可利用细节、密钥、本机数据库、原始日志、绝对路径或 Agent 会话文件。无法访问私密入口时,只能公开说明“需要私密安全联系方式”,不得附带漏洞细节;仓库目前不公布维护者私人邮箱,也不承诺固定响应时限。

There aren't any published security advisories