Umbra

人人都在 vibe coding，却没人验证。Umbra 为其评分。

Umbra 为 AI 生成的代码提供确定性的信任评分（0–100）：这是一款 vibe coding 安全扫描器，用于验证 Agent 实际交付了什么，而不是它声称交付了什么。只需一条命令，即可完全在本地运行，并为每项发现提供证据。

→ umbra-badge.umbrabadge.workers.dev — 产品介绍页、实时徽章和报告页面

快速开始 · 演示 · 审计 · 工作原理 · 四个维度 · 常见问题 · 路线图 · 参与贡献 · 网站

Umbra 为何而生

研究显示，AI 生成的代码中有 40% 到 60% 存在可利用的漏洞；编码 Agent 也常声称“所有测试都通过了”，但实际上有三个测试失败。用于借助 AI 编写代码的工具，比用于信任代码的工具领先了一年。Umbra 填补了这一差距：针对当下软件编写方式重建的 SAST，再加上沙箱验证，捕获静态规则无法发现的问题。

只需一条命令，即可扫描任何由 Agent 生成的代码库（Claude Code、Cursor、Copilot、Windsurf、Lovable），并返回评分，为每项发现提供文件:行号证据。使用 --deep 可进行更深入的检查：Umbra 会在限制严格的 Docker 沙箱中构建并启动代码库，然后根据实际情况重放 Agent 自己的声明。如果 Agent 谎称测试通过，评分上限将低于通过标准，并附上证据。

审计：扫描 61 个 vibe coding 代码库

我们使用 Umbra 扫描了 61 个公开且持续维护的 AI 构建代码库，并公布了所有结果。Vibe Coding 安全审计：

平均信任评分：74/100。五分之一的代码库未通过。完整报告包含各类别的深入分析、示例代码片段和修复方案、完整的代码库明细表，以及坦诚的方法说明——包括我们在运行审计时发现自身规则中的误报，并已修复（评分标准 v4）。

快速开始

npx umbra-scan            # check — scans the directory you're standing in
npx umbra-scan --fix      # heal — applies provably-safe fixes, shows the score climbing
npx umbra-scan --setup    # protect — pre-commit gate, PR checks, agent guardrails

这就是全部接口。三个动词：检查、修复、保护。

正在使用 AI 编码 Agent？ Umbra 专为 Agent 驱动而构建，而不只是供人手动运行：

• 任何 Agent — 它会读取此仓库的 AGENTS.md / llms.txt，并知道该做什么。或者告诉你的 Agent：“用 umbra 检查这个仓库。”
• Claude Code / Kimi Code — --setup 会安装 PreToolUse 钩子，确保 Agent 写入的每个文件在落盘前都受到保护。
• Claude Code、Cursor、Copilot、Windsurf — trust-review 技能会让 Agent 在宣布完成前扫描自己的工作。
• 原生支持 MCP 的 Agent — 添加 umbra-mcp（npx --yes -p @elberacasa/umbra umbra-mcp），Agent 就能将 scan_repo、guard_content 和 get_score 用作工具。

扫描一个典型的氛围编程 Next.js 应用时的实际输出 （本仓库中的 fixtures/bad-app，信任评分为 30/100）：

$ npx umbra-scan ./fixtures/bad-app

UMBRA TRUST SCORE: 30/100  🔴

SAFE   🔴 5/100 — 14 findings
CLEAN  ✅ 87/100 — 10 findings
RUNS   — not measured — run with --deep
HONEST — not measured — run with --deep

Score computed over measured axes only (full rubric: SAFE 35%, RUNS 25%, HONEST 25%, CLEAN 15%). Rubric v4.
…plus 7 further findings beyond the per-rule cap (see report)

Top findings:
  [safe/hardcoded-secrets] Hardcoded Supabase service_role JWT — bypasses all row level security — .env:2
  [safe/hardcoded-secrets] Hardcoded Supabase service_role JWT — bypasses all row level security — lib/supabase.ts:5
  [safe/supabase-antipatterns] Supabase service_role key reachable from client-side code — full database bypass for anyone who opens the bundle — .env:2
  [safe/supabase-antipatterns] Supabase service_role key reachable from client-side code — full database bypass for anyone who opens the bundle — app/components/UserList.tsx:10
  [safe/hardcoded-secrets] Committed environment file with secret values: .env — .env:1

Notes (low confidence — not scored):
  [safe/missing-rate-limit] Auth endpoint with no rate-limiting signal in the repo — brute-force / credential-stuffing exposure (heuristic) — app/api/login/route.ts:3

Badge: [![Umbra Trust Score](https://img.shields.io/badge/Umbra_Trust_Score-30-red)](https://github.com/elberacasa/umbra)

评分低于 50 时，退出代码为 1，因此 CI 可以据此设置门禁。

umbra [path]               # path defaults to the current directory
umbra [path] --json        # machine-readable output
umbra [path] --offline     # skip npm registry checks, fully local
umbra [path] --deep        # verify RUNS and HONEST in a Docker sandbox
umbra [path] --report      # write UMBRA.md: an agent-actionable task list
umbra [path] --fix         # apply provably-safe fixes and re-scan (score before → after)
umbra [path] --dry-run     # preview --fix without writing anything
umbra [path] --baseline-write  # write .umbra-baseline.json: grandfather current findings, gate only on new ones
umbra [path] --baseline <path> # use an explicit baseline file ("write" is shorthand for --baseline-write)
umbra [path] --publish     # self-report the score to the hosted badge service (live README badge)
umbra setup                # install everything (hooks + Action + agent guards)
umbra init                 # only the pre-commit hook + GitHub Action
umbra protect              # only the agent PreToolUse hooks (--remove uninstalls)
umbra guard --stdin        # hook entrypoint (agents call this, not humans)
umbra mcp                  # run the MCP server (bin: umbra-mcp)

工作原理

repo in
   │
   ▼  Layer 0 · static rules (17 SAFE + CLEAN rules, 0 tokens, <1s)
   ▼  Layer 1 · evidence gating (confidence-scored, low never moves the score)
   ▼  Layer 2 · --deep sandbox (Docker: build, boot, HTTP probe, claim replay)
   │
   ▼  deterministic Trust Score + verdict + badge

每项发现都包含置信度级别以及文件和行号证据。只有高置信度和中置信度的发现会影响评分；推测则会列入备注部分。评分规则采用版本管理（当前为 v3），因此同一个仓库始终会得到相同的评分。完整计算方法见 RUBRIC.md。

免疫层：保护写入操作，而不只是扫描仓库

扫描会在问题落盘后才发现它们。免疫层会在 Agent 写入的每个文件落盘前进行检查。umbra protect 会在 Claude Code 和 Kimi Code 中安装 PreToolUse 钩子（自动检测，一条命令即可）；umbra-mcp 服务也使用相同的引擎，为原生支持 MCP 的 Agent 提供支持。

flowchart LR
    CC[Claude Code hook] --> E
    KC[Kimi Code hook] --> E
    MCP["umbra-mcp: guard_content"] --> E
    E{"guardContent(file, content)<br/>file rules + path guard"} -->|allow / warn| W[write lands]
    E -->|"block (exit 2)"| B["reason fed back:<br/>agent fixes the root cause"]

npx umbra-scan protect   # install the hooks; --remove uninstalls cleanly

泄露的 Stripe 密钥或 alg: none JWT 永远不会写入文件。路径防护会硬性阻止 Agent 向 .git/hooks 和 .git/config 写入内容 （CVE-2026-26268，即 Agent 植入 Git 钩子以逃逸沙箱），也会阻止有效凭据写入 .env。只有高置信度的严重/高危发现才会触发阻止；其他情况都会发出警告，而且任何故障都会采取放行策略。判定约需 0.2 ms，因此防护不会拖慢 Agent。完整介绍见： docs/immune-layer.md。

--deep：验证 AI 代码，而不是盲目信任

快速扫描是静态扫描。--deep 使用大模型验证代码，并提供证据。Umbra 会将仓库复制到一次性 Docker 容器中（运行时无网络，512 MB / 1 CPU 硬性限制，120 秒后强制终止），构建并启动应用，通过 HTTP 探测其端点，再根据实际运行情况重放 README 和 Agent 产物中发现的每项声明。速度较慢（以分钟计，而非秒），并且需要正在运行的 Docker 守护进程。如果没有 Docker，则会跳过沙箱执行的评估维度，并将其排除在评分之外；无法验证不会受到惩罚。

深度扫描 README 撒谎的仓库时的实际输出 （fixtures/claims-app，因撒谎上限而最高为 49/100）：

$ npx @elberacasa/umbra ./fixtures/claims-app --deep

UMBRA TRUST SCORE: 49/100  🔴

SAFE   ✅ 100/100 — 0 findings
CLEAN  ✅ 100/100 — 2 findings
RUNS   — not measured — No detectable run path (no Dockerfile, no package.json start script or main entry)
HONEST ⚠️ 50/100 — 2 claims failed, 2 verified, 1 unverifiable

Score computed over measured axes only (full rubric: SAFE 35%, RUNS 25%, HONEST 25%, CLEAN 15%). Rubric v4.
Score capped below passing: a documented claim was verified false. Trust is the product.

Claim receipts:
  CLAIM FAILED: "14 tests pass" — README.md:7 — actually 3 tests pass, 0 fail
  CLAIM FAILED: "build passes" — README.md:9 — actually build exits 1
  CLAIM VERIFIED: "All tests pass" — CLAUDE.md:3 — 3 tests pass
  CLAIM VERIFIED: "All tests are passing" — README.md:8 — 3 tests pass

任何经验证为假的声明都会将总分限制在 49：被发现撒谎的仓库无法获得及格的信任评分。相比之下，真正可运行的应用 （fixtures/runnable-app）在 --deep 下的评分为 100/100。

四个维度

SAFE 规则涵盖了 AI 生成代码在实际应用中常见的安全问题： 硬编码密钥（Stripe 密钥、JWT、连接字符串）、在客户端暴露 Supabase service-role 密钥，以及缺少 Supabase RLS；API 路由缺少身份验证、注入点、速率限制提示、虚构和仿冒依赖、携带凭据的 CORS 通配符、JWT 配置错误 （alg: none、无过期时间、将解码结果视为已授权）、调试标志和 堆栈跟踪泄漏、提交了敏感文件（.pem、id_rsa、SQL 转储）， 以及默认凭据。

它还会检查 Agent 自身的配置——其他工具都未覆盖的攻击面： 指令文件（CLAUDE.md、.cursor/rules）和技能中的提示词注入载荷（零宽 Unicode、HTML 注释中的覆盖指令），以及危险的 MCP 配置（.mcp.json 中的明文 API 密钥、未固定版本的 npx -y 服务、 curl | sh 安装程序）。这些检查也会在 guard 中运行，因此 Agent 编辑自身配置时也会在写入过程中接受检查。

Umbra 与现有工具的对比

现有工具会回答“这种代码模式是否危险？”。Umbra 回答的是氛围编程实际引发的问题：“这是 AI 写的，我能信任它吗？”

徽章

每次扫描都会打印徽章 Markdown。将它粘贴到 README 中，让仓库展示自身的可信度评分：

[![Umbra Trust Score](https://img.shields.io/badge/Umbra_Trust_Score-30-red)](https://github.com/elberacasa/umbra)

实时徽章只需启用一个标志：使用 --publish 运行（或将 Action 的 publish: true），评分就会提交到托管徽章服务，因此 README 始终显示当前分数，点击后还可查看完整报告页面——由你的 CI 自行报告，并明确标注：

[![Umbra Trust Score](https://umbra-badge.umbrabadge.workers.dev/badge/OWNER/REPO.svg)](https://umbra-badge.umbrabadge.workers.dev/OWNER/REPO)

一个引擎，覆盖所有使用场景

• CLI（npx @elberacasa/umbra）：核心功能，现已可用。简短别名： npx umbra-scan。
• Agent 技能：信任审查技能，可安装到 Claude Code、Cursor、Copilot 和 Windsurf 中，让 Agent 在你检查之前先检查自己的工作。在 Agent 内部进行 Claude Code / Cursor / Copilot 安全审查。
• GitHub Action：uses: elberacasa/umbra@v1 会在每个 PR 下评论信任评分。在 CI 中进行信任门控，无需本地设置。
• umbra setup：一键安装程序——包含 pre-commit 门控、PR 评分评论，以及为检测到的 Agent 配置 PreToolUse 守卫钩子；所有操作都可幂等执行，且不会覆盖现有内容。（init 和 protect 仍可用于分步安装。）
• umbra protect：将 PreToolUse 钩子安装到 Claude Code 和 Kimi Code 中（自动检测、幂等执行，可通过 --remove 卸载），让 Umbra 在 Agent 写入过程中审查每次写入，并在危险内容落地前将其拦截。
• MCP 服务（umbra-mcp）：Agent 可在运行过程中调用 Umbra，在代码落地前发现自身错误。使用 npx --yes -p @elberacasa/umbra umbra-mcp 添加。

日常使用方法（CI 门控、JSON 解析、钩子）：docs/daily-use.md。

路线图

• v0.1 （已发布）：CLI、SAFE + CLEAN 静态维度、确定性评分、判定结果输出、徽章 Markdown。
• v0.2 （已发布）：各种使用入口。Agent 技能、GitHub Action、umbra init。
• v0.3 （已发布，当前版本）：RUNS 维度（沙箱构建、启动、HTTP 探测）和 HONEST 维度（声明凭证及说谎者上限）。
• v1.0 （已发布）：免疫层。Umbra 位于 Agent 与你的代码库之间，在写入过程中拦截并评分，然后才让写入落地。完整介绍见 docs/immune-layer.md。
• 未来规划：跨依赖树的攻击图；对应用进行安全镜像并加以探测，避免生产环境受到探测；每个徽章背后都提供可托管的报告永久链接。

切入点是评分。最终目标是为每个 AI 构建的代码仓库提供一层验证机制。

常见问题

如何在已有检查结果的仓库中采用 Umbra？ 运行一次 npx umbra-scan --baseline-write。Umbra 会将 .umbra-baseline.json 写入仓库根目录。从此之后，门禁只会拦截新问题 — 已有检查结果会被视为既有问题（判定结果会显示 baseline: N existing findings grandfathered (M new)），因此你可以逐步修复， 而不用试图一次解决所有问题。提交基线文件，让整个团队和 CI 共用它。

Umbra 与 Semgrep、Snyk 或 trufflehog 有何不同？ 它们扫描代码模式；Umbra 验证实际结果。静态规则是 SAFE 轴的一个输入。 Umbra 还会在沙箱中启动应用，验证它确实能运行，并重放 Agent 文档中记录的声明，验证它没有说谎。 “README 说 14 项测试通过，实际只有 3 项通过”会导致仓库无法通过评估。

Umbra 会把我的代码发送到其他地方吗？ 不会。扫描完全在本地进行；--offline 甚至会跳过 npm registry 检查。 --deep 会在本地 Docker 容器中运行你的仓库，运行时不会联网。 任何内容都不会离开你的机器。

需要 Docker 吗？ 只有 --deep（RUNS 和 HONEST）需要。默认的快速扫描完全基于静态分析。 没有 Docker 时，会跳过沙箱检测的各个轴，并将其排除在评分之外，不会因此扣分。

支持哪些语言？ 目前对 JavaScript 和 TypeScript（包括 Next.js 和 Supabase 应用）的覆盖最深入，这也是大多数通过 vibe coding 编写的仓库所用的语言。规则引擎可扩展；新增规则需要提供 fixture 和测试。

评分可复现吗？ 可以。相同的仓库、相同的评分标准版本，每次都会得到相同的分数。评分标准经过版本管理（v2），并会显示在每份报告中；低置信度的检查结果不会影响评分。跳过的检测轴会被排除，并在其余部分中重新归一化，不会因此扣分。

它能发现哪些 AI Agent 不会提到的问题？ AI 生成代码中的典型问题：将 Supabase service_role JWT 放到浏览器端（绕过所有行级安全策略）、.env 中的 Stripe 有效密钥、没有身份验证检查的 API 路由、alg: none JWT、不安全的带凭据 CORS *、npm 上不存在的幻觉依赖项，以及 Agent 自己关于测试和构建的声明是否属实。

Umbra 能在我的 Agent 写入过程中将其拦截吗？ 可以，通过钩子实现。运行 npx @elberacasa/umbra protect，Umbra 会在 Claude Code 和/或 Kimi Code 中安装 PreToolUse 钩子，在每次 Write/Edit/MultiEdit 写入生效前进行检查。只有置信度高的严重和高危问题才会阻止操作（错误拦截会导致工具被卸载，因此有疑问时 Umbra 会发出警告）；.git/hooks 路径防护会直接阻止植入 git 钩子（CVE-2026-26268）；防护机制自身发生错误时会默认放行，因此绝不会中断你的工作流。钩子是安全护栏，不是沙箱；详情请参阅 docs/immune-layer.md。

我的 AI 编码 Agent 能直接使用 Umbra 吗？ 可以，这正是它的设计方式。仓库附带 AGENTS.md 和 llms.txt，让助手准确了解何时以及如何运行它；而 Agent 技能 会让 Claude Code、Cursor、Copilot 和 Windsurf 在宣告任务完成前扫描自己的工作。

参与贡献

欢迎提交问题和 PR。请参阅 CONTRIBUTING.md。目前最有价值的贡献包括：附带 fixture 和测试的新 SAFE/CLEAN 规则、误报报告（这里严重程度为一级的问题会被视为 bug）、针对真实 AI 生成仓库的渲染测试，以及用于 umbra protect 的新执行环境适配器。

提交前请先构建并测试：

npm install
npm run build
npm test

合乎伦理地使用

Umbra 是一款防御性工具。请扫描你拥有的仓库、即将依赖的仓库，或你获准审计的仓库。检查结果指出的是弱点，并非漏洞利用；公开他人的低分来羞辱他们，也不是本工具的目的。本工具旨在让“这是 AI 写的”不再成为验证讨论的终点。

许可证

MIT