AI Guardian

免责声明：本项目为社区维护的开源项目，与 Ollama、IGEL 或任何 AI 安全厂商均无隶属、背书或赞助关系。 所有产品及商标名称归其所有者所有。源代码托管于 github.com/AIops-tools/AI-Guardian，采用 MIT 许可证发布。

面向终端侧本地大语言模型（Ollama）的受管可观测性 + 治理能力 — 提供20 个 MCP 工具，每个工具均封装在统一的 @governed_tool 运行时中： 在 ~/.ai-guardian/ 下生成本地统一审计日志、设置 token/失控运行预算防护、记录 undo-token，并划分描述性风险等级。 它是IGEL AI Armor 的互补组件：AI Armor 控制本地模型是否允许运行； 而 ai-guardian 则记录模型实际执行了什么操作，并管控哪些内容可作为 prompt 离开客户端。

Ollama 本身不保存可查询的 prompt 历史记录（上下文由客户端在每次请求时提供），因此 ai-guardian 从两个层面实施观测： 被动式资产/状态审计 —— 调用 /api/tags、/api/ps、/api/show、/api/version 接口； 以及可选的路由穿透式内容治理 —— 调用方将 prompt 显式通过 guarded_generate / observe_chat 发送， 该调用会先完成扫描 + 策略拦截 + 记录，再转发至 Ollama。

独立运行：治理运行时已内置于软件包中（ai_guardian.governance），无需依赖外部技能族（skill-family）。 为其他客户端流量提供透明捕获代理（transparent capture proxy）的功能已在 v0.2 路线图中规划； 与 IGEL AI Armor 的互操作性目前仅处于文档级定位说明阶段。

本技能功能概览

scan_prompt 是纯函数（不调用 Ollama）。当 prompt 的风险等级 >= block_threshold（默认为 high）或 模型被禁止运行时， guarded_generate / observe_chat 将直接阻断请求 —— 此类被拦截的调用永远不会到达 Ollama，并被记录为“已拦截”事件。

快速安装

uv tool install ai-guardian-aiops
ai-guardian doctor          # 零配置即可对接本地 Ollama 实例
ai-guardian init            # 可选：配置 endpoint(s) + 可选 token + 模型白名单

适用场景

• 盘点本地模型并识别影子 AI（shadow AI）（list_models / anomaly_report）：未授权模型显示为 allowed:false
• 发送前扫描 prompt（scan_prompt）：检测密钥 / PII / 源码 / 绕过指令 → 输出加权风险等级，不触发模型调用
• 防止密钥或 PII 泄露至本地模型（guarded_generate / observe_chat）：扫描 + 策略拦截 + 记录，仅当允许时才执行模型调用
• 检测被篡改或静默重拉取的模型（model_provenance）：当前 digest 与 pinned digest 不一致 → 存在漂移（drift）
• 强制约束可运行模型（set_model_allowlist / set_model_denylist），并对可信 digest 进行固定（pin_model_digest）
• 检查 VRAM 占用情况（running_models / vram_usage），并审计已观测到的使用行为（usage_events）

不建议在以下场景使用：目标为 GPU 推理集群（多节点服务）—— 这属于 AIops-tools 产品线中另一款专用工具。 同样不适用于虚拟机监控程序（hypervisor）、存储设备、备份产品、容器集群或网络设备。

相关技能 — 技能路由规则

典型工作流

1. 查找并关停影子（未授权）本地模型

1. ai-guardian doctor → 在判断某终端集群“无模型”前，先确认 Ollama endpoint 可达（避免误判为无连接）
2. ai-guardian overview → 查看 endpoint 状态、模型总数及当前加载模型
3. ai-guardian model list（MCP：list_models）→ 列出所有已安装模型及其允许/拒绝判决；任何 allowed:false 均属影子 AI
4. ai-guardian guard anomalies（MCP：anomaly_report）→ 一次性汇总影子模型 + digest 漂移 + 高风险/被拦截 prompt，便于区分单次异常拉取与持续性模式
5. ai-guardian model running / vram_usage → 影子模型是仅安装，还是已加载并正在占用 VRAM？
6. 收紧策略以防复发：set_model_allowlist(["llama3.*", "qwen*"]) → 后续未授权模型将在 pull_model 阶段即被拒绝。该操作可逆：此前列表会被保存为 undo 描述符
7. 移除违规模型：ai-guardian model remove --dry-run，确认无误后再次执行（不带 --dry-run）→ 属于高危操作，需双重确认，并要求设置环境变量 AI_GUARDIAN_AUDIT_APPROVED_BY；undo 描述符将记录一次重拉取行为
8. 失败分支：若新白名单过于严格，误拦了已授权模型，则执行 ai-guardian undo list → undo apply 可精确恢复先前的白名单。若误删模型，重放 undo 将重新拉取模型 —— 但权重来自 registry，因此请务必在操作后按工作流 3 核验 digest，切勿假设其字节完全一致。

2. 阻止密钥与 PII 泄露至本地模型

1. ai-guardian guard scan "…text…"（MCP：scan_prompt）→ 一次纯函数调用，不涉及模型：输出确定性结果（密钥 / PII / 代码 / 绕过指令）及加权风险等级。可用于内容离线预检，确保其在抵达模型前已被筛查
2. ai-guardian guard policy（MCP：policy_view）→ 确认当前允许运行的模型及生效阈值
3. 将真实调用路由至防护层：guarded_generate(model, prompt, block_threshold="high") → 防护层完成扫描、记录至 usage 日志，并在风险等级 >= high 或模型被禁用时于 Ollama 调用前即阻断
4. ai-guardian guard usage（MCP：usage_events(allowed=False)）→ 审查被拦截内容。原始 prompt永不存储 —— 仅保留长度与脱敏后的发现项，因此审查日志本身不会导致密钥二次泄露
5. ai-guardian guard anomalies → 在用户教育或集成修复后，确认被拦截 prompt 的发生率是否下降
6. 失败分支：路由穿透式防护为显式启用 —— 任何直接调用 Ollama 的行为将完全绕过防护。若 usage_events 异常为空，而 running_models 显示活跃，则表明存在未路由流量，而非干净终端集群。透明捕获代理（transparent capture proxy）已列入 v0.2 路线图；在此之前，请将防护覆盖率视为“已路由流量”的覆盖率，并明确说明此限制。

3. 检测被篡改或静默重拉取的模型权重

1. ai-guardian model list / model_details → 获取你所授权模型的当前 digest
2. pin_model_digest(model, digest) → 在仍信任该模型时，一次性固定其可信 digest。若在疑似被攻陷后执行 pin，将同步固化攻击状态
3. 后续（或按计划）执行：ai-guardian guard provenance（MCP：model_provenance）→ 当前 digest 与 pinned digest 不一致的模型将报告 status: DRIFT —— 表明权重已被重拉取或篡改
4. 查看 drift 时间戳附近的 usage_events → 漂移模型是否已被使用？具体用途为何？
5. 失败分支：DRIFT 仅反映 digest 变化，不体现意图 —— 合法升级与恶意篡改均会导致相同漂移。应在移除前展开调查：检查 ~/.ai-guardian/audit.db 审计日志中是否存在 pull_model 记录。若不存在，则视作不可信，按工作流 1 移除；仅在重新确认正确 digest 后，方可重新执行 pin。

4. 上线前的终端集群健康度审查

1. ai-guardian overview → 快速掌握 endpoint 当前整体状态
2. ai-guardian model list → 全量模型清单及允许/拒绝判决
3. ai-guardian guard provenance → 所有已 pinned 模型是否仍与其 digest 匹配
4. vram_usage + running_models → 当前驻留模型及资源余量，判断是否具备上线新模型的条件
5. unload_model → 释放空闲模型所占 VRAM（无需卸载模型本身，实践中可逆 —— 下次使用时自动重载）
6. ai-guardian model pull → 拉取过程将校验白名单，未授权模型上线将被直接拒绝（而非仅记录）
7. ai-guardian guard anomalies → “干净汇总”是本次审查的退出标准
8. 失败分支：若 pull_model 被拒绝，说明模型不在白名单中 —— 应主动扩展策略（set_model_allowlist），该操作经审计且可逆，而非绕过防护机制。若因 VRAM 不足导致拉取失败，应先执行 unload_model 释放空闲模型；审计日志将记录失败尝试（status=error），且不生成 undo token。

治理与安全机制

本技能负责执行读写操作并进行记录；但它不决定某次写入是否被允许 —— 这取决于你的 agent 自身判断，或你所运行环境的宿主权限与账户权限（例如：将其指向一个当前账户无法管理的 runtime，或仅授予其 scan/observe 类工具权限）。 本技能无只读开关、deny-rules 文件或审批门控机制 —— 内容治理（包括模型允许/禁止策略及 guarded_generate 的拦截阈值）属于独立的产品级控制，保持长期有效。

• 审计即保障，且不可绕过。 所有操作 —— 无论 MCP 调用或 CLI 命令 —— 均记录至 ~/.ai-guardian/audit.db（可通过 AI_GUARDIAN_AIOPS_HOME 重定向路径）：参数、返回值、状态、耗时及风险等级。观测到的本地 LLM 使用行为则单独存于 ~/.ai-guardian/usage.db。
• AI_GUARDIAN_AUDIT_APPROVED_BY / AI_GUARDIAN_AUDIT_RATIONALE 为可选注释字段，记录在审计条目中（谁批准 / 为何批准）；它们既非必需，亦不会造成阻塞。
• 失控防护（Runaway guard） —— 作为安全兜底机制，而非授权手段：同一调用在极短时间内高频循环将触发熔断。可通过 AI_GUARDIAN_RUNAWAY_MAX=0 禁用。
• remove_model 支持 --dry-run + CLI 双重确认，并记录 undo（重拉取）；白名单/黑名单写入操作同样记录 undo → 回滚至先前列表。
• 扫描器为确定性、离线运行；所有发现项均经脱敏处理，确保密钥等敏感信息永不被二次输出。

参考文档

• references/capabilities.md —— 完整 20 个工具及 endpoint 接口参考
• references/cli-reference.md —— CLI 命令参考手册
• references/setup-guide.md —— 入门指南、可选 token 配置与连通性验证