aiglare

aiglare

检查 AI 功能是否符合治理护栏要求——模型能在哪里做出你无法撤销的操作？

在线网站： nugehs.github.io/aiglare-web

将它指向任意 JS/TS 代码库，它就会找出每处 LLM/AI 输出触达用户或触发副作用（付款、预订、邮件、数据库写入）的位置，然后标记其中哪些没有置信度处理、没有回退方案、没有输出验证，也没有人工参与环节。

大多数 AI 事故并非模型故障，而是治理失效：模型输出直接流向用户或不可逆操作，中间没有任何防护。这个工具能让这些路径一目了然，并让你在 CI 中阻止它们。

npx @nugehs/aiglare                                        # audit current repo
npx @nugehs/aiglare ./src --ci                             # fail the build on a red side-effectful surface
npx @nugehs/aiglare --compliance all --format html         # HTML evidence report for auditors
npx @nugehs/aiglare --compliance soc2,eu-ai-act --format lint --ci  # compliance linter in CI

报告内容

每个 AI 作用点都会按接收目标分类——也就是输出的去向：

• user-facing — 从路由/控制器返回，或在组件中渲染
• side-effectful — 用于付款、预订、邮件、数据库/文件写入或 shell
• internal — 仅记录日志或缓存

……并从五个护栏维度评分：置信度处理、回退/不确定路径、输出验证、人工参与（针对副作用）和错误隔离。

严重程度	含义
🔴 red	模型输出触达用户或触发副作用，且没有护栏——请立即审查
🟡 amber	部分覆盖
🟢 green	已具备护栏

CI 门禁（--ci）只会在红色 + 有副作用的作用点上失败——也就是“AI 在没有确认的情况下自动触发不可逆操作”这一情形——因此可以放心采用，不会让团队淹没在警告中。

合规报告

传入 --compliance，将每条发现映射到具体的监管控制项，然后选择输出格式：

# HTML evidence report — branded, collapsible per-framework sections, guardrail matrix
aiglare --compliance all --format html > report.html

# ESLint-style linter — pipe into CI, editors, or reviewers
aiglare --compliance soc2,eu-ai-act --format lint

# Markdown evidence doc — ready to hand to an auditor
aiglare --compliance all --format markdown > AUDIT.md

# Guardrail linter (no framework) — rule IDs like guardrail/human-in-loop
aiglare --format lint

支持的框架：

框架	映射的控制项
soc2	SOC 2 信任服务准则 — CC7.2、CC7.4、CC9.1、A1.2、PI1.2、PI1.3
eu-ai-act	EU AI Act — 第 9、13、14、17 条
nist	NIST AI RMF — GOVERN-1.2、MAP-2.3、MEASURE-2.5/2.6、MANAGE-1.3/2.2
owasp	OWASP LLM Top 10 — LLM02、LLM04、LLM08、LLM09

使用 all 可包含所有框架。--json 输出中的每个作用点都会新增一个 violations[] 数组，其中包含框架、控制项 ID、描述以及错误/警告级别。

**多代码库：**传入多个路径即可生成一份合并报告：

aiglare ./api ./web --compliance all --format html > report.html

与提供方无关

检测由提供方注册表驱动，覆盖 OpenAI、Anthropic、Google、Cohere、Mistral、Replicate、Vercel AI SDK、LangChain/LangGraph、Ollama、AWS Bedrock、Cloudflare Workers AI 和 Hugging Face，也支持对已知推理主机发起的原始 fetch/axios 调用。添加提供方只需提交一行 PR。

可选：使用 repoctx 加速

如果存在 repoctx 索引（.dev-context/index.json），工具会自动使用它来优先处理可能包含 AI 的文件，并借助 repoctx 的 kind/domain 数据提高接收目标分类的准确度（例如，即使原生扫描器无法追踪调用图，repoctx 标记为 controller 路由的文件也会被正确视为面向用户）。如果没有索引，内置的 TypeScript 编译器扫描器也会完成相同工作，但准确度较低。同一工具，两种准确度等级——所有人都能独立使用，repoctx 用户还能获得更丰富的分析结果。

MCP 服务

aiglare 内置了 Model Context Protocol 服务，让 Agent 可以直接运行审计：

aiglare mcp        # stdio JSON-RPC server (no SDK dependency)

它提供三个工具：

工具	功能
ai_surface_audit	对代码库进行完整审计（path、可选的 sinks、severity）→ 返回与 --json 相同的结构化报告
ai_surface_gate	对代码库给出 CI 门禁判定：passed + 阻断性红色副作用面的数量
list_providers	扫描器检测到的提供商注册表

在 MCP 主机（Claude Desktop、Cursor、VS Code，……）中注册：

{
  "mcpServers": {
    "aiglare": {
      "command": "npx",
      "args": ["-y", "@nugehs/aiglare", "mcp"]
    }
  }
}

aiglare 与其他方案的比较

方案	功能	aiglare 的不同之处
guardrails-ai / NeMo Guardrails / 运行时验证器	在运行时逐次调用验证或修正每次模型输出	aiglare 采用静态分析：它会在任何代码运行前找出完全没有护栏的 AI 面，然后你可以在那里添加运行时验证器
semgrep / 自定义 lint 规则	编写并自行维护通用静态规则	aiglare 开箱即提供 AI 专属知识：提供商注册表、接收端分类和五个护栏维度，无需编写规则
人工审查 AI 功能	能发现扫描器无法识别的细节	aiglare 为审查人员提供 AI 面的完整清单和严重程度分级，让审查时间集中在风险所在之处

这些方案可以互相补充：aiglare 告诉你护栏缺失在哪里；运行时验证器则是添加护栏的方式。

开展为期 1 周的试点

想在启用 CI 门禁前，先在真实代码库上评估 aiglare？PILOT.md 提供了一份逐步开展的为期一周操作指南：安装、首次审计后端和前端代码库、阅读报告、调整 --severity/--sinks，以及决定是否启用 --ci。

客观说明其局限性

这是静态的建议性分析工具——是 lint 工具，而非验证器。它会产生误报（可能漏掉相隔两次调用的护栏），也会产生漏报（实际上并未起到门控作用的 confidence 变量也会被判定为存在）。请将输出视为待审查的面，而非违规项。单文件原生扫描器无法追踪调用图；repoctx 适配器正是为弥补这一不足而存在的。

选项

aiglare [path...] [options]
  --compliance <fw>   Map findings to compliance controls.
                      Comma-separated: soc2, eu-ai-act, nist, owasp, or "all"
  --format <fmt>      Output format: terminal (default), json, lint, markdown, html
  --json              JSON output (alias for --format json)
  --ci                Exit non-zero on a red side-effectful surface
  --severity <lvl>    Show only red, or amber-and-worse
  --sinks <list>      Filter: user-facing,side-effectful,internal

aiglare mcp           Start the MCP server (stdio)

MCP 工具 ai_surface_audit 可接受可选的 compliance 数组；设置后，响应中的每个面都会包含一个 violations[] 数组。

许可证

MIT

---

工具链的一部分

aiglare 是构成 AI 辅助开发确定性信任层的四个工具之一。每个工具都用静态分析来回答人们总是交给大模型的问题。

• repoctx — 上下文：这项更改实际影响了什么？
• tieline — 契约：前端和后端是否在不知不觉中不再一致？
• bouncer — 合规：你能为此向 Ofcom 作出合理说明吗？
• aiglare（本工具）— 治理：模型在哪些地方可能做出你无法撤销的操作？

更多信息请访问 segunolumbe.com。静态分析，绝不依赖模型。