Vibe Sentinel

MVP preview: local-first security scanner for AI-assisted code reviews.\n>\n> 中文简介：面向 AI 辅助开发的本地优先代码安全审计工具，支持 CLI、本地 Web 审计工作台和 GitHub Action。

vibe-sentinel 是一个面向 AI 辅助开发流程的轻量代码安全审计工具，提供 CLI、本地 Web 审计工作台和 GitHub Action。

它适合给 Cursor、Claude Code、Codex、Copilot 等 AI 辅助写出的代码加一道合并前安全门禁。

当前项目处于 v0.1.0-alpha / MVP 阶段。它可以帮助发现常见风险，但不能替代专业安全审计、渗透测试或合规评估。

Screenshots

本地 Web 审计工作台：

Markdown 报告页：

Quick Start

git clone https://github.com/Linuxzsx/vibe-sentinel.git vibe-sentinel
cd vibe-sentinel
npm install
npm run build
npm run web

打开：

http://127.0.0.1:8731

在页面中输入要扫描的本地项目路径，然后点击 开始扫描。

Who is this for?

适合：

• 使用 Cursor / Claude Code / Codex / Copilot 的独立开发者
• 小型 SaaS 团队
• 开源项目维护者
• 想给 PR 增加轻量安全检查的团队
• 想本地扫描代码、又不想上传源码的开发者

不适合：

• 需要完整企业级 SAST 的安全团队
• 需要正式合规认证的审计场景
• 需要完整依赖 CVE 扫描的场景
• 期待工具保证发现所有漏洞的场景

中文关键词

AI 编程安全 / 代码安全审计 / GitHub Action / 本地扫描 / Vibe Coding / Cursor / Claude Code / Codex / Copilot / Secrets 扫描 / CI 安全

功能特性

• 本地 CLI 扫描：vibe-sentinel scan
• 本地 Web 审计工作台：vibe-sentinel web
• GitHub Action 集成
• Markdown / JSON 报告
• PR 评论能力
• 配置文件支持
• 默认不上传源码
• 默认忽略依赖、构建产物和虚拟环境目录
• 覆盖 JavaScript / TypeScript、Python、Java、Shell、GitHub Actions 等常见文件

当前检测规则

规则	说明	默认等级
secret.possible_credential	疑似 API key、token、private key、数据库密码等凭证泄露	critical
shell.dangerous_execution	curl | bash、rm -rf $VAR、chmod 777 等危险 shell 模式	high
code.dynamic_eval	eval()、exec()、new Function() 等动态代码执行	high
shell.command_injection_risk	child_process.exec、subprocess(shell=True) 等命令注入风险	high
java.command_injection_risk	Runtime.exec、ProcessBuilder 拼接命令风险	high
java.sql_injection_risk	Java SQL 字符串拼接或直接执行风险	high
java.unsafe_deserialization	ObjectInputStream / readObject 不安全反序列化入口	high
ci.github_action_unpinned	GitHub Action 使用 @main、@master、@latest	medium
ci.github_actions_overpermissive_permissions	permissions: write-all 或高风险 pull_request_target	high

Example Output

Vibe Sentinel Report
Score: 78/100
Findings: 1 critical, 2 high, 1 medium, 0 low, 0 info
Scanned files: 42

Top findings:
- [critical] src/config.ts:12 secret.possible_credential - 检测到疑似真实凭证或 secret。
- [high] scripts/deploy.sh:8 shell.dangerous_execution - 检测到危险 shell 执行模式。
- [medium] .github/workflows/ci.yml:18 ci.github_action_unpinned - GitHub Action 使用了未固定版本 @main。

安装与构建

npm install
npm run build

快速试用 Demo

仓库内置了一个故意包含风险代码的示例项目，方便第一次使用时快速看到扫描结果。

npm run build
node dist/src/cli.js scan --path examples/insecure-demo

也可以运行 Web 控制台后选择 examples/insecure-demo 目录。

Demo 中的 token、API key 和危险代码都是假数据，仅用于触发规则，请不要复制到真实项目。

本地 Web 审计工作台

启动：

npm run web

打开：

http://127.0.0.1:8731

页面能力：

• 输入本地项目路径，或点击“选择文件夹”从资源管理器选择
• 点击扫描
• 查看风险总览
• 按严重等级筛选 findings
• 点击 finding 查看详细原因、影响、修复步骤和安全示例
• 切换到 Markdown 报告 页签复制完整报告

Web 控制台支持手动粘贴路径，也支持在本地 Windows 环境中点击“选择文件夹”打开系统文件夹选择器。

CLI 使用

扫描当前目录：

node dist/src/cli.js scan --path .

指定输出目录：

node dist/src/cli.js scan --path . --output vibe-sentinel-report

只输出 Markdown：

node dist/src/cli.js scan --path . --format markdown

只输出 JSON：

node dist/src/cli.js scan --path . --format json

发现 high 及以上风险时返回失败退出码：

node dist/src/cli.js scan --path . --fail-on high

使用配置文件：

node dist/src/cli.js scan --path . --config vibe-sentinel.config.json

GitHub Action 使用

注意：当前 Action 依赖已构建的 dist/src/cli.js。发布 GitHub Action 时需要先运行 npm run build 并提交 dist，或后续改为单文件打包 Action。

.github/workflows/vibe-sentinel.yml：

name: Vibe Sentinel

on:
  pull_request:
  workflow_dispatch:

permissions:
  contents: read
  pull-requests: write

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Linuxzsx/vibe-sentinel@main
        with:
          path: .
          fail-on: none
          format: both
          output: vibe-sentinel-report
          comment: true

如果你已经发布 tag，也可以使用：

- uses: Linuxzsx/vibe-sentinel@v0.1.0-alpha

严格模式示例：

- uses: Linuxzsx/vibe-sentinel@main
  with:
    fail-on: high

配置文件

配置文件应放在被扫描项目根目录。例如扫描：

D:\my-project

则配置文件路径为：

D:\my-project\vibe-sentinel.config.json

示例配置：

{
  "ignorePaths": [
    "docs/**",
    "tests/fixtures/**",
    "legacy/**"
  ],
  "disabledRules": [
    "code.dynamic_eval"
  ],
  "severityOverrides": {
    "ci.github_action_unpinned": "low"
  }
}

字段说明：

• ignorePaths：忽略路径，支持简单 * 和 /**
• disabledRules：禁用指定规则
• severityOverrides：覆盖规则严重等级

默认已忽略：

node_modules
.git
dist
build
.next
coverage
.venv
venv
env
site-packages
_vendor
vendor
__pycache__

Rule Details

secret.possible_credential

检测疑似 API key、token、private key、数据库连接密码等。

风险：

• 凭证泄露
• 云资源被盗用
• 数据库被访问
• CI/CD secret 被滥用

修复建议：

• 立即确认是否是真实凭证
• 如果属实，先轮换或吊销凭证
• 从代码中移除硬编码值
• 改用环境变量、密钥管理服务或 GitHub Actions secrets

shell.command_injection_risk

检测把变量、请求参数、文件名或模型输出拼进 shell 命令的风险。

风险：

• 任意命令执行
• 文件被读取或删除
• CI runner 或服务器被控制

修复建议：

• Node.js 使用 spawn / execFile 参数数组
• Python 使用 subprocess.run([...], shell=False)
• 对命令参数使用 allowlist

报告输出

扫描后默认生成：

vibe-sentinel-report/report.md
vibe-sentinel-report/report.json

Markdown 报告包含：

• 风险总览
• findings 列表
• 为什么重要
• 潜在影响
• 修复建议
• 推荐修复步骤
• 更安全的写法
• 检测到的代码片段
• 参考资料

隐私与安全边界

• 开源版在本地机器或 GitHub Actions runner 内扫描
• 默认不上传源码
• 不收集 secrets
• 不执行被扫描项目代码
• 不运行依赖安装脚本
• 只做轻量启发式检查，不保证发现所有漏洞

当前限制

• 仍是 MVP / alpha 版本
• 规则以高信号启发式为主，可能有误报或漏报
• 暂未支持 changed-only 扫描
• 暂未支持行内忽略注释
• 暂未提供完整依赖 CVE 扫描
• 暂未提供 SaaS dashboard

项目文档

• 安全报告流程：SECURITY.md
• 贡献指南：CONTRIBUTING.md
• 版本变更：CHANGELOG.md
• GitHub Action 示例：examples/github-action-basic.yml、examples/github-action-strict.yml
• 本地试用 Demo：examples/insecure-demo

Feedback

如果你遇到误报、漏报或希望支持新的规则，欢迎提交 issue。

建议附上：

• 技术栈
• 命中的规则 ID
• 相关代码片段，但不要贴真实 secret
• 你期望的行为
• 是否愿意提供一个最小复现示例

Security

如果你发现本项目自身存在安全问题，请不要公开提交可利用细节、真实 secret 或攻击 payload。

可以先通过 issue 简要说明问题类型，避免泄露敏感信息。

Contributing

欢迎提交：

• 新规则
• 误报案例
• UI 改进
• 文档改进
• GitHub Action 改进

本地开发：

npm install
npm run build
npm test
npm run web

路线图

近期计划：

• 扫描历史
• 依赖目录扫描开关
• 行内忽略：vibe-sentinel-ignore rule_id
• changed-only 扫描
• 单文件 GitHub Action 打包
• 更多规则包：Node.js、Python、Java、GitHub Actions hardening

License

Apache-2.0