goklab/guardvibe

# GuardVibe [](https://www.npmjs.com/package/guardvibe) [](https://opensource.org/licenses/Apache-2.0) [](https://github.com/goklab/guardvibe/actions/workflows/ci.yml) [](https://www.npmjs.com/package/guardvibe) **为 vibe coding 打造的安全 MCP。** 包含 277 条安全规则，覆盖了从首行代码到生产部署的整个 AI 生成代码生命周期。 可与 **Claude Code, Cursor, Gemini CLI, Codex, Windsurf** 以及任何兼容 MCP 的编码 Agent 配合使用。 ## 为什么选择 GuardVibe 大多数安全工具都是为企业安全团队构建的。GuardVibe 是为**你**而构建的——为那些使用 AI 快速构建和发布 Web 应用的开发者。 - **277 条安全规则**，专为 AI Agent 生成的技术栈定制 - **零配置门槛** — 执行 `npx guardvibe` 即可开始扫描 - **无需账号** — 100% 本地运行，无需 API 密钥，无需上云 - **懂你的技术栈** — 并非通用的 SAST，而是熟悉 Next.js, Supabase, Stripe, Clerk 以及你实际使用的工具的规则 - **CVE 版本情报** — 检测 `package.json` 中 21 个已知存在漏洞的依赖包版本 - **AI Agent 安全** — 检测 MCP 服务器漏洞、AI 权限过大、间接提示注入 - **自动修复建议** — `fix_code` 工具返回 AI Agent 可直接应用的具体补丁 - **Pre-commit 钩子** — 在不安全代码进入你的仓库前将其拦截 - **适配 CI/CD** — 支持 GitHub Actions 工作流并将 SARIF 上传至 Security 标签页 - **对 Agent 友好的输出** — JSON 格式供 AI Agent 使用，Markdown 格式供人类阅读，SARIF 供 CI/CD 使用 - **插件系统** — 使用社区或高级规则包进行扩展 ## GuardVibe 与其他工具的对比 GuardVibe 是专为 AI 编码工作流构建的。传统工具非常适合企业 CI/CD 流水线——而 GuardVibe 填补了另一个空白。 | 功能 | GuardVibe | 传统 SAST | 依赖扫描器 | |-----------|-----------|-----------------|-------------------| | 在 AI Agent 内运行 (MCP) | 原生支持 | 不支持 | 不支持 | | 零配置安装 | `npx guardvibe` | 需要账号和配置 | 内置（有限） | | Vibecoding 技术栈规则 (Next.js, Supabase, Clerk, tRPC, Hono) | 100+ 专用规则 | 通用模式 | 不适用 | | AI/LLM 安全（提示注入，MCP，工具滥用） | 17 条规则 | 实验性/无 | 无 | | 面向 AI Agent 的自动修复建议 | `fix_code` 工具 | CLI 自动修复 | 不支持 | | CVE 版本检测 | 21 个软件包 | 范围广 | 范围广 | | 合规性映射 (SOC2, PCI-DSS, HIPAA) | 内置 | 付费层级 | 无 | | SARIF CI/CD 导出 | 是 | 是 | 有限 | | 规则数量 | 277 条（精准） | 5000+ 条（宽泛） | N/A | **何时使用 GuardVibe：** 你正在使用 AI Agent 构建，并希望将安全扫描整合到你的编码工作流中——无需仪表盘，无需账号，无需配置 CI。 **何时使用传统工具：** 你需要深度 AST 分析、企业级仪表盘、组织级策略执行，或覆盖数百种语言。 ## 快速开始 ### MCP 设置（推荐） ``` npx guardvibe init claude # Claude Code npx guardvibe init cursor # Cursor npx guardvibe init gemini # Gemini CLI npx guardvibe init all # All platforms ``` ### Pre-commit 钩子 ``` npx guardvibe hook install # Blocks commits with critical/high findings npx guardvibe hook uninstall # Remove hook ``` ### CI/CD (GitHub Actions) ``` npx guardvibe ci github # Generates .github/workflows/guardvibe.yml ``` ### 手动 MCP 配置 ``` { "mcpServers": { "guardvibe": { "command": "npx", "args": ["-y", "guardvibe"] } } } ``` ## GuardVibe 扫描内容 ### 应用程序代码 Next.js App Router, Server Actions, Server Components, React, Express, Hono, tRPC, GraphQL, FastAPI, Go ### 身份验证与授权 Clerk, Auth.js (NextAuth), Supabase Auth, OAuth/OIDC (state parameter, PKCE) — 中间件检查、密钥暴露、会话处理、SSR cookie 认证、管理员方法保护 ### 数据库与 ORM Supabase (RLS, anon vs service role), Prisma (原生查询注入, CVEs), Drizzle (SQL 注入), Turso/LibSQL (客户端暴露, SQL 注入), Convex (认证绕过, 内部函数暴露) ### 支付 Stripe (webhook 签名, 重放保护, 密钥), Polar.sh, LemonSqueezy ### 第三方服务 Resend (邮件 HTML 注入), Upstash Redis, Pinecone, PostHog, Google Analytics (PII 追踪), Uploadthing (认证, 文件类型/大小) ### AI / LLM 安全 提示注入检测, LLM 输出接收器, 系统提示泄露, MCP 服务器 SSRF/路径遍历/命令注入, `dangerouslyAllowBrowser`, 缺少 `maxTokens`, AI API 密钥客户端暴露, 通过外部数据的间接提示注入 ### OWASP API 安全 BOLA/IDOR (对象级别授权破坏), 批量赋值 (展开请求体, Object.assign), 缺少分页, 速率限制, 管理员端点授权, 冗余错误信息泄露 ### 现代技术栈 Zod `.passthrough()` 批量赋值, `z.any()` 绕过, 文件上传验证, `server-only` 导入守卫, webhook 重放保护, CSP 响应头, `unsafe-inline`/`unsafe-eval` 检测, 定时任务端点认证 ### 移动端 React Native, Expo — AsyncStorage 密钥, Deep Link Token 暴露, 硬编码 API URL, ATS 配置 ### Firebase Firestore 安全规则, Firebase Admin SDK 暴露, 存储规则, 自定义 Token 验证 ### CVE 版本情报 (21 个 CVE) Next.js (3 个 CVEs), React, Express, Axios, jsonwebtoken, lodash, node-fetch, tar, xml2js, crypto-js, Prisma (2 个 CVEs), next-auth (2 个 CVEs), sharp, ws, undici (2 个 CVEs) ### 部署与配置 Vercel (vercel.json, 定时任务密钥, 请求头), Next.js 配置, Docker, Docker Compose, Fly.io, Render, Netlify, Cloudflare ### 基础设施 Dockerfile 安全, GitHub Actions CI/CD, Terraform (S3, IAM, RDS, 安全组) ### 密钥与环境变量 API 密钥 (AWS, GitHub, Stripe, OpenAI, Resend, Turso), .env 管理, .gitignore 覆盖范围, 高熵检测, NEXT_PUBLIC 暴露 ### 合规性 SOC2, PCI-DSS, HIPAA 控制措施映射及合规报告 ### 供应链 恶意 postinstall 脚本, 未固定版本的 GitHub Actions, 抢注检测 ## 工具 (22 个 MCP 工具) | 工具 | 功能 | |------|-------------| | `check_code` | 分析代码片段中的安全问题 | | `check_project` | 扫描多个文件并提供安全评分 (A-F) | | `scan_directory` | 从磁盘扫描项目目录 | | `scan_staged` | 针对 git 暂存文件的 pre-commit 扫描 | | `scan_dependencies` | 检查所有依赖项的已知 CVE (OSV) | | `scan_secrets` | 检测泄露的密钥、API 密钥、Token | | `check_dependencies` | 对照 OSV 检查单个软件包 | | `check_package_health` | 抢注检测、维护状态、采用率指标 | | `compliance_report` | SOC2 / PCI-DSS / HIPAA 合规映射 | | `export_sarif` | 用于 CI/CD 集成的 SARIF v2.1.0 导出 | | `get_security_docs` | 安全最佳实践与指南 | | `fix_code` | **自动修复建议**，为 AI Agent 提供具体的代码补丁 | | `audit_config` | 审计项目配置文件，排查跨文件的安全配置错误 | | `generate_policy` | 检测项目技术栈并生成量身定制的安全策略 (CSP, CORS, RLS) | | `review_pr` | 审查 PR 差异以发现安全问题，并具备严重性门控机制 | | `scan_secrets_history` | 扫描 git 历史记录以查找泄露的密钥（包含有效和已移除的） | | `policy_check` | 根据在 `.guardviberc` 中定义的合规策略检查项目 | | `analyze_dataflow` | 追踪从用户输入到危险接收器的污点数据流 | | `check_command` | 在执行前分析 Shell 命令的安全风险 | | `scan_config_change` | 比较配置文件版本以检测安全降级 | | `repo_security_posture` | 评估整体仓库安全态势并映射敏感区域 | | `explain_remediation` | 获取详细的修复指导，包含漏洞利用场景和修复策略 | 所有扫描工具均支持 `format: "json"` 以提供机器可读的输出。 ## 安全规则（涵盖 23 个模块的 277 条规则） | 分类 | 规则数 | 覆盖范围 | |----------|-------|----------| | 核心 OWASP | 19 | SQL 注入, XSS, CSRF, 命令注入, CORS, SSRF, 硬编码密钥 | | Next.js App Router | 13 | Server Actions, 密钥暴露, 认证绕过, CSP, 重定向 | | 认证 (Clerk / Auth.js / Supabase Auth) | 16 | 中间件, 密钥, 会话存储, 角色检查, SSR cookies | | 数据库 (Supabase / Prisma / Drizzle) | 8 | 原生查询, 客户端暴露, 服务角色泄露 | | OWASP API 安全 | 10 | BOLA/IDOR, 批量赋值, 分页, 速率限制, 错误泄露 | | 现代技术栈 | 30 | Zod, tRPC, Hono, GraphQL, Uploadthing, Turso, Convex, OAuth, CSP, webhooks, AI SDK | | 部署配置 | 16 | Vercel, Next.js 配置, Docker Compose, Fly, Render, Netlify | | 支付 (Stripe / Polar / Lemon) | 9 | Webhook 签名, 密钥暴露, 价格篡改 | | 服务 (Resend / Upstash / Pinecone / PostHog) | 11 | API 密钥泄露, PII 追踪, 邮件注入 | | Web 安全 | 14 | Webhooks, CSP, .env 安全, AI 密钥暴露, Cloudflare | | React Native / Expo | 10 | AsyncStorage 密钥, Deep Links, ATS, 硬编码 URL | | Firebase | 7 | Firestore 规则, Admin SDK, 存储, 自定义 Token | | AI / LLM 安全 | 14 | 提示注入, MCP SSRF, 过度授权, 间接注入 | | CVE 版本情报 | 20 | `package.json` 中的已知漏洞版本 (21 个 CVEs) | | Shell / Bash | 5 | 管道至 bash, chmod 777, rm -rf, sudo 密码 | | SQL | 4 | 不带 WHERE 的 DROP/DELETE, 堆叠查询, GRANT ALL | | 供应链 | 2 | 恶意安装脚本, 未固定版本的 actions | | Go | 6 | SQL 注入, 命令注入, 模板转义 | | Dockerfile | 5 | Root 用户, ENV 中的密钥, 未标记的镜像 | | CI/CD (GitHub Actions) | 4 | 密钥插值, 未固定版本的 actions, write-all 权限 | | Terraform | 5 | 公开 S3, 开放安全组, IAM 通配符 | | 其他服务 | 5 | AWS, GCP, MongoDB, Convex, Sentry, Twilio | ## CLI 命令 ``` npx guardvibe init # Setup MCP server (claude, cursor, gemini, all) npx guardvibe hook install # Install pre-commit hook npx guardvibe hook uninstall # Remove pre-commit hook npx guardvibe ci github # Generate GitHub Actions workflow npx guardvibe-scan # Scan staged files (for pre-commit) npx guardvibe-scan --format sarif --output results.sarif # CI mode ``` ## 插件系统 使用自定义或社区规则包扩展 GuardVibe。 ``` npm install guardvibe-rules-awesome ``` 匹配 `guardvibe-rules-*`、`@guardvibe/rules-*` 或 `@guardvibe-pro/rules-*` 的插件会被自动发现。 ### 编写插件 插件是一个导出 `GuardVibePlugin` 对象的 npm 包： ``` // index.ts import type { GuardVibePlugin } from "guardvibe/plugins"; const plugin: GuardVibePlugin = { name: "my-rules", version: "1.0.0", description: "My custom security rules", rules: [ { id: "CUSTOM001", name: "My Custom Rule", severity: "high", // "critical" | "high" | "medium" | "low" | "info" owasp: "A01:2025 Broken Access Control", description: "What this rule detects and why it's dangerous", pattern: /vulnerable_pattern_here/g, // RegExp with global flag languages: ["javascript", "typescript"], // which file types to scan fix: "How to fix the vulnerability", fixCode: "// Copy-paste secure code example", compliance: ["SOC2:CC6.1"], // optional compliance mapping }, ], }; export default plugin; ``` ### 插件规则结构 | 字段 | 类型 | 必填 | 描述 | |-------|------|----------|-------------| | `id` | string | 是 | 唯规则 ID（例如："CUSTOM001"） | | `name` | string | 是 | 易于人类阅读的规则名称 | | `severity` | string | 是 | `critical`、`high`、`medium`、`low` 或 `info` | | `owasp` | string | 是 | OWASP 类别映射 | | `description` | string | 是 | 规则检测的内容 | | `pattern` | RegExp | 是 | 用于匹配漏洞代码的正则表达式（使用 `/g` 标志） | | `languages` | string[] | 是 | 要扫描的文件类型 | | `fix` | string | 是 | 如何修复该问题 | | `fixCode` | string | 否 | 可直接复制粘贴的安全代码示例 | | `compliance` | string[] | 否 | SOC2/PCI-DSS/HIPAA 控制 ID | ### 加载插件 插件从以下三个来源加载： 1. **自动发现：** 任何已安装且匹配 `guardvibe-rules-*` 或 `@guardvibe/rules-*` 的 npm 包 2. **配置指定：** 在 `.guardviberc` 的 `plugins` 数组中列出的包 3. **本地路径：** 在 `.guardviberc` 的 `plugins` 数组中指定的相对路径 ``` // .guardviberc { "plugins": [ "guardvibe-rules-awesome", "./my-local-rules" ] } ``` ## 配置 在你的项目根目录创建一个 `.guardviberc` 文件： ``` { "rules": { "disable": ["VG030"], "severity": { "VG002": "medium" } }, "scan": { "exclude": ["fixtures/", "coverage/"], "maxFileSize": 1048576 }, "plugins": ["guardvibe-rules-awesome"] } ``` ## 行内忽略 ``` const key = process.env.API_KEY; // guardvibe-ignore VG001 // guardvibe-ignore-next-line VG002 app.get("/api/health", (req, res) => res.json({ ok: true })); ``` 支持 `//`、`#` 和 `` 注释风格。 ## 工作原理 ``` You write code with AI | AI agent calls GuardVibe MCP tools | GuardVibe scans locally (no cloud, no API) | Returns findings with severity, OWASP mapping, and fix suggestions | AI agent fixes issues before they reach production ``` ## 性能 在一个包含 644 个文件的真实 Next.js + Supabase 项目上测试： - 扫描时间：**502ms** - 误报率：**接近于零**（通过注释/字符串过滤，人类可读文本检测） - 检出率：对已知漏洞模式达到 **100%** ## 故障排除 ### MCP 连接问题 如果你的 AI Agent 无法连接到 GuardVibe： 1. **重启你的 IDE/Agent。** MCP 服务器由宿主应用程序启动。在运行 `npx guardvibe init` 后，需重启 Claude Code、Cursor 或 Gemini CLI 才能使配置生效。 2. **检查配置路径。** 再次运行 `npx guardvibe init claude` 并验证输出是否显示了正确的配置文件位置（对于 Claude Code 是项目根目录的 `.claude.json`，对于 Cursor 是 `.cursor/mcp.json`）。 3. **验证 Node.js 版本。** GuardVibe 要求 Node.js >= 18.0.0。请使用 `node --version` 进行检查。 4. **检查 npx 缓存。** 如果你升级了 GuardVibe 但缓存了旧版本，请运行 `npx -y guardvibe@latest` 以强制使用最新版本。 ### Node.js 版本要求 GuardVibe 要求 **Node.js >= 18.0.0**。早期版本将因语法错误或缺少 API 而失败。推荐使用 Node.js 22 LTS。 ### 误报 如果某条规则对安全的代码触发了警报： - **行内忽略：** 在同一行添加 `// guardvibe-ignore VG001`，或在上一行添加 `// guardvibe-ignore-next-line VG001`。支持 `//`、`#` 和 `` 注释风格。 - **配置排除：** 将规则 ID 添加到 `.guardviberc` 的 `rules.disable` 中： { "rules": { "disable": ["VG030"] } } - **路径排除：** 将目录添加到 `.guardviberc` 的 `scan.exclude` 中： { "scan": { "exclude": ["fixtures/", "test-data/"] } } ### Pre-commit 钩子问题 - **钩子未运行：** 验证钩子文件是否存在于 `.git/hooks/pre-commit` 并且是否可执行 (`chmod +x .git/hooks/pre-commit`)。 - **钩子阻断了正常的提交：** 使用 `git commit --no-verify` 临时跳过钩子，然后调查发现的问题。 - **移除钩子：** 运行 `npx guardvibe hook uninstall`。 ## 安全模型 GuardVibe 专为在敏感和专有代码库上使用而设计： - **100% 本地执行。** 所有扫描均在你的机器上进行。不会将任何代码、发现结果或元数据发送到任何服务器。 - **无需账号、无需 API 密钥、无遥测数据。** 没有注册流程，没有云端仪表盘，也没有任何形式的使用追踪。 - **仅一次可选的网络请求。** `scan_dependencies` 和 `check_dependencies` 工具会查询 [OSV API](https://osv.dev/) 以检查已知 CVE。这是可选操作——只有在你明确使用这些工具时才会调用。没有任何其他工具会发起网络请求。 - **适用于物理隔离环境。** 所有代码分析规则完全离线运行。只有依赖项漏洞检查需要网络访问。 ## 配置（.guardviberc） 在你的项目根目录创建一个 `.guardviberc` JSON 文件以自定义 GuardVibe 的行为。 ### 完整示例 ``` { "rules": { "disable": ["VG030", "VG045"], "severity": { "VG002": "medium", "VG010": "low" } }, "scan": { "exclude": ["fixtures/", "coverage/", "dist/", "vendor/"], "maxFileSize": 1048576 }, "plugins": [ "guardvibe-rules-awesome", "./my-local-rules" ], "compliance": { "frameworks": ["SOC2", "HIPAA"], "failOn": "high", "exceptions": [ { "ruleId": "VG030", "reason": "Accepted risk per security review 2026-03", "approvedBy": "security-team", "expiresAt": "2026-12-31", "files": ["src/legacy/**"] } ], "requiredControls": ["SOC2:CC6.1"] } } ``` ### 配置字段 | 字段 | 类型 | 默认值 | 描述 | |-------|------|---------|-------------| | `rules.disable` | `string[]` | `[]` | 扫描期间要跳过的规则 ID | | `rules.severity` | `Record` | `{}` | 覆盖特定规则的严重性 | | `scan.exclude` | `string[]` | `[]` | 用于跳过目录/文件的 Glob 模式 | | `scan.maxFileSize` | `number` | `512000` | 最大文件大小（以字节为单位，超过此大小的文件将被跳过） | | `plugins` | `string[]` | `[]` | 作为插件加载的 npm 包名或本地路径 | | `compliance.frameworks` | `string[]` | -- | 要映射的合规框架（`SOC2`、`PCI-DSS`、`HIPAA`、`GDPR`、`ISO27001`） | | `compliance.failOn` | `string` | `"high"` | 导致合规性失败的最低严重性级别 | | `compliance.exceptions` | `PolicyException[]` | `[]` | 带有到期日期的已批准例外 | | `compliance.requiredControls` | `string[]` | -- | 无论何种例外都必须通过的控制措施 | ## 安全性 GuardVibe 高度重视供应链安全： - **npm 来源验证** — 每个已发布的版本均通过 Sigstore 进行加密签名，将包链接到此确切的 GitHub 仓库和提交记录。可通过 `npm audit signatures` 进行验证 - **启用 2FA** — npm 账号受双因素认证保护 - **分支保护** — main 分支禁用了 force push，并启用了管理员强制执行 - **标签保护** — 版本标签 (`v*`) 不能被删除或 force push - **最小 CI 权限** — GitHub Actions 工作流仅使用 `permissions: contents: read` - **零运行时依赖** — 仅包含 MCP SDK 和 Zod（两者均经过广泛审计） 如需报告漏洞，请发送电子邮件至 info@goklab.com 或提交 GitHub issue。 ## 许可证 Apache 2.0 — 开源、专利安全、企业就绪。由 [GokLab](https://github.com/goklab) 构建。

标签：AI代码生成, AI编程助手, CI/CD安全, CISA项目, Claude, Claude Code, Clerk, Convex, Cursor, CVE检测, DevSecOps, GitHub Actions, GNU通用公共许可证, GraphQL, Hono, Llama, MCP Server, MITM代理, Node.js, npm包, Pre-commit Hook, Prisma, SARIF, SAST, Stripe, Supabase, tRPC, Turso, Uploadthing, URL发现, Vibe Coding, Web安全, Windsurf, 上游代理, 前端安全, 安全检测, 开源安全工具, 提示注入防护, 模型上下文协议, 盲注攻击, 自动修复, 自动化攻击, 自动笔记, 蓝队分析, 请求拦截, 调试插件, 逆向工程平台, 静态应用安全测试