vite-plugin-security-scan

一个用于前端代码安全风险扫描的 Vite 插件。在开发和构建阶段自动检测代码中的安全隐患，帮助开发者提前发现并修复潜在的安全漏洞。

特性

• 🔍 AST 深度分析 - 基于 Babel 解析器对源码进行抽象语法树分析，精准定位安全问题
• 🛡️ 30 条内置规则 - 覆盖 XSS、开放重定向、敏感数据存储、危险 API 调用、原型链污染等常见安全风险
• ⚡ 无缝集成 Vite - 作为 Vite 插件零配置接入，不影响构建性能
• 📊 多种报告格式 - 支持 console、JSON、summary 三种输出格式
• 🚫 构建拦截 - 可配置在发现高/中级安全问题时阻止构建通过
• 📁 灵活的文件过滤 - 支持自定义包含/排除文件模式
• ⚙️ 规则可配置 - 支持白名单/黑名单模式，按需启用或禁用规则
• 📦 构建产物检查 - 检测 source map 泄露、环境变量暴露到客户端
• 🌐 HTML 安全检查 - 检测 CDN 资源缺少 SRI、缺少 CSP 策略
• 🔗 依赖漏洞预警 - 自动检查项目依赖中的已知安全漏洞
• 🛠️ 自定义规则 - 可添加自定义规则，对项目进行深度扫描

安装

npm install vite-plugin-security-scan -D

yarn add vite-plugin-security-scan -D

pnpm add vite-plugin-security-scan -D

快速开始

在 vite.config.ts 中引入并使用插件：

import { defineConfig } from 'vite'
import viteSecurityScan from 'vite-plugin-security-scan'

export default defineConfig({
  plugins: [
    viteSecurityScan()
  ]
})

配置选项

viteSecurityScan({
  // 需要扫描的文件模式，默认扫描 js/ts/jsx/tsx/vue 文件
  include: ['**/*.{js,ts,jsx,tsx,vue}'],

  // 排除的文件模式，默认排除 node_modules
  exclude: ['**/node_modules/**'],

  // 报告输出格式：'console' | 'json' | 'summary'
  reporter: 'console',

  // 是否在发现高/中级问题时使构建失败
  failOnError: false,

  // 严重等级阈值：'low' | 'medium' | 'high'
  severityThreshold: 'low',

  // 是否启用开发模式（开发时输出详细信息）
  devMode: false,

  // 白名单模式：仅启用指定的规则（设置后只运行列表中的规则）
  rules: ['xss-innerHTML-assignment', 'dangerous-eval', 'hardcoded-credentials'],

  // 黑名单模式：禁用指定的规则
  disableRules: ['unsafe-math-random', 'console-sensitive-info'],

  // 自定义规则
  customRules: []
})

配置项说明

参数	类型	默认值	说明
include	string | string[]	['**/*.{js,ts,jsx,tsx,vue}']	需要扫描的文件 glob 模式
exclude	string | string[]	['**/node_modules/**']	排除的文件 glob 模式
reporter	'console' | 'json' | 'summary'	'console'	报告输出格式
failOnError	boolean	false	发现高/中级问题时是否中断构建
severityThreshold	'low' | 'medium' | 'high'	'low'	最低报告的严重等级
devMode	boolean	false	开发模式，输出更详细的信息
rules	string[]	undefined	白名单模式，仅启用指定规则
disableRules	string[]	undefined	黑名单模式，禁用指定规则
customRules	SecurityRule[]	undefined	自定义安全规则
checkBuildOutput	boolean	true	是否检查构建产物安全（source map、环境变量泄露）
checkHtmlSecurity	boolean	true	是否检查 HTML 安全（SRI、CSP）
checkDependencies	boolean	true	是否检查依赖漏洞

规则配置示例

只启用部分规则（白名单模式）

viteSecurityScan({
  // 只检测 XSS 和硬编码凭证
  rules: [
    'xss-v-html',
    'xss-innerHTML-assignment',
    'xss-dangerously-set-inner-html',
    'xss-document-write',
    'xss-outerhtml-assignment',
    'hardcoded-credentials'
  ]
})

禁用部分规则（黑名单模式）

viteSecurityScan({
  // 项目中 Math.random 仅用于非安全场景，关闭该规则
  // 项目允许 Object.assign 使用
  disableRules: [
    'unsafe-math-random',
    'prototype-pollution',
    'console-sensitive-info'
  ]
})

添加自定义规则

import viteSecurityScan from 'vite-plugin-security-scan'
import type { SecurityRule } from 'vite-plugin-security-scan'

const myRule: SecurityRule = {
  name: 'no-alert',
  severity: 'low',
  message: '不允许使用 alert()，请使用自定义弹窗组件。',
  match: (node) => {
    if (node.type !== 'CallExpression') return false
    return node.callee?.name === 'alert'
  }
}

export default defineConfig({
  plugins: [
    viteSecurityScan({
      customRules: [myRule]
    })
  ]
})

内置安全规则

XSS 攻击检测

规则名	严重等级	说明
xss-v-html	🔴 高	检测 Vue 模板中的 v-html 指令，用户输入直接插入 HTML 可能导致 XSS
xss-dangerously-set-inner-html	🔴 高	检测 React 的 dangerouslySetInnerHTML 属性
xss-innerHTML-assignment	🔴 高	检测对 innerHTML 的直接赋值操作

开放重定向检测

规则名	严重等级	说明
unsafe-location-href	🟡 中	检测 location.href 赋值使用不可信输入
unsafe-window-open	🟡 中	检测 window.open 使用不可信 URL
unsafe-link-target	🔵 低	检测 target="_blank" 链接缺少 rel="noopener noreferrer"

敏感数据存储检测

规则名	严重等级	说明
sensitive-storage-localStorage	🔴 高	检测在 localStorage 中存储 token、密码等敏感信息
sensitive-storage-sessionStorage	🔴 高	检测在 sessionStorage 中存储 token、密码等敏感信息（需 key 命中敏感关键词）

危险 API 调用检测

规则名	严重等级	说明
dangerous-eval	🔴 高	检测 eval() 调用，可执行任意代码
dangerous-new-function	🔴 高	检测 new Function() 动态创建函数
dangerous-settimeout-string	🟡 中	检测 setTimeout/setInterval 使用字符串参数

凭证安全检测

规则名	严重等级	说明
hardcoded-credentials	🔴 高	检测代码中硬编码的账号、密码、token 等凭证信息
hardcoded-internal-ip	🔵 低	检测硬编码的内网地址/IP，避免暴露内部基础设施

传输安全检测

规则名	严重等级	说明
unsafe-http-url	🟡 中	检测网络请求中使用 HTTP 明文传输（仅在 fetch/axios/request 调用中触发）
unsafe-cookie-operation	🟡 中	检测 document.cookie 赋值，缺少 secure/httpOnly 保护

随机数与加密检测

规则名	严重等级	说明
unsafe-math-random	🟡 中	检测 Math.random() 用于安全场景，应使用 crypto.getRandomValues()

DOM 安全检测

规则名	严重等级	说明
xss-document-write	🔴 高	检测 document.write() 调用，可被利用进行 XSS
xss-outerhtml-assignment	🔴 高	检测 outerHTML 赋值，与 innerHTML 类似有 XSS 风险
xss-insertAdjacentHTML	🔴 高	检测 insertAdjacentHTML() 调用，可将未过滤 HTML 插入 DOM
dangerous-dom-script-injection	🔴 高	检测动态 document.createElement('script') 创建脚本元素
unsafe-iframe-no-sandbox	🟡 中	检测 iframe 缺少 sandbox 属性

跨域与模块安全检测

规则名	严重等级	说明
unsafe-postmessage-handler	🟡 中	检测 postMessage 监听缺少 origin 来源验证
unsafe-postmessage-wildcard	🔴 高	检测 postMessage() 使用通配符 * 作为目标源，可能泄露敏感数据
unsafe-dynamic-import	🟡 中	检测动态 import() 使用变量参数，可能加载任意模块

开放重定向（函数调用）

规则名	严重等级	说明
unsafe-url-redirect	🔴 高	检测 location.replace()/location.assign() 调用，可能导致开放重定向

正则与代码质量检测

规则名	严重等级	说明
redos-vulnerable-regex	🟡 中	检测嵌套量词正则，可能导致 ReDoS 灾难性回溯
unsafe-regexp-constructor	🟡 中	检测 new RegExp() 动态构造正则，参数来自用户输入可导致注入；已排除常量、配置对象访问、转义函数等安全场景
prototype-pollution	🟡 中	检测 Object.assign({}, ...) 合并不可信对象，存在原型链污染风险
prototype-pollution-__proto__	🔴 高	检测直接操作 __proto__ 属性，可导致原型链污染攻击
console-sensitive-info	🔵 低	检测 console 输出中包含 token、密码等敏感关键词

使用示例

基础使用

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import viteSecurityScan from 'vite-plugin-security-scan'

export default defineConfig({
  plugins: [
    vue(),
    viteSecurityScan()
  ]
})

CI/CD 中强制安全检查

// vite.config.ts
import { defineConfig } from 'vite'
import viteSecurityScan from 'vite-plugin-security-scan'

export default defineConfig({
  plugins: [
    viteSecurityScan({
      failOnError: true,        // 发现问题时构建失败
      reporter: 'summary',      // 输出统计摘要
      severityThreshold: 'medium' // 只报告中级及以上问题
    })
  ]
})

生成 JSON 报告

// vite.config.ts
import { defineConfig } from 'vite'
import viteSecurityScan from 'vite-plugin-security-scan'

export default defineConfig({
  plugins: [
    viteSecurityScan({
      reporter: 'json'  // 输出 JSON 格式，便于工具集成
    })
  ]
})

自定义扫描范围

// vite.config.ts
import { defineConfig } from 'vite'
import viteSecurityScan from 'vite-plugin-security-scan'

export default defineConfig({
  plugins: [
    viteSecurityScan({
      include: ['src/**/*.{ts,vue}'],     // 只扫描 src 目录
      exclude: ['**/node_modules/**', '**/test/**']  // 排除测试文件
    })
  ]
})

输出示例

Console 模式

[HIGH] vite-plugin-security-scan: 潜在的XSS风险：检测到innerHTML赋值。
  -> src/components/Editor.vue:42

[MED] vite-plugin-security-scan: 潜在的开放重定向风险：location.href赋值使用了潜在的不可信输入。
  -> src/utils/redirect.ts:15

Summary 模式

🔒 Security Scan Summary:
   Total: 5 | High: 2 | Medium: 2 | Low: 1

📋 Detailed Findings:
[HIGH] src/components/Editor.vue:42 - 潜在的XSS风险：检测到innerHTML赋值。
[MED] src/utils/redirect.ts:15 - 潜在的开放重定向风险：location.href赋值使用了潜在的不可信输入。
...

JSON 模式

{
  "total": 5,
  "high": 2,
  "medium": 2,
  "low": 1,
  "findings": [
    {
      "rule": "xss-innerHTML-assignment",
      "severity": "high",
      "message": "潜在的XSS风险：检测到innerHTML赋值。用户输入的内容直接插入HTML可能导致XSS攻击。",
      "location": {
        "file": "src/components/Editor.vue",
        "line": 42,
        "column": 4
      }
    }
  ]
}

API 导出

插件除了默认导出外，还提供以下具名导出：

import viteSecurityScan, {
  Reporter,    // 报告生成器类
  getRules,    // 获取所有内置规则
  scanCode     // 独立的代码扫描函数
} from 'vite-plugin-security-scan'

// 类型导出
import type {
  PluginOptions,    // 插件配置选项类型
  SecurityFinding,  // 安全发现记录类型
  ScanResult        // 扫描结果统计类型
} from 'vite-plugin-security-scan'

独立使用 scanCode

import { scanCode } from 'vite-plugin-security-scan'

const code = `document.getElementById('app').innerHTML = userInput;`
const findings = scanCode(code, 'example.ts')

console.log(findings)
// [{ rule: 'xss-innerHTML-assignment', severity: 'high', ... }]

支持的文件类型

• .js / .jsx - JavaScript
• .ts / .tsx - TypeScript
• .vue - Vue 单文件组件
• .mjs / .cjs - ES Module / CommonJS

severityThreshold 配置说明

severityThreshold 控制两个行为：

1. 报告输出过滤：只输出指定级别及以上的问题
2. 构建失败判断（需配合 failOnError: true）：只有指定级别及以上问题才会阻断构建

viteSecurityScan({
  severityThreshold: 'high', // 只报告和拦截 high 级别问题
  failOnError: true,
  reporter: 'summary'
})

severityThreshold 值	报告输出	构建失败条件
'low'（默认）	所有 low + medium + high	有任何问题即失败
'medium'	medium + high	medium 或 high 时失败
'high'	仅 high	high 时失败

兼容性

• Vite >= 4.0.0
• Node.js >= 18

非代码层安全检查

除代码层 AST 分析外，插件还提供以下维度的安全检测：

构建产物检查（checkBuildOutput）

在 writeBundle 阶段自动扫描构建产物：

规则名	严重等级	说明
build-sourcemap-exposed	🔴 高	检测生产构建中是否输出 .map 文件，暴露源码逻辑
build-env-process-exposed	🟡 中	检测 bundle 中残留的 process.env 引用
build-secret-key-exposed	🔴 高	检测 bundle 中是否包含硬编码密钥模式（AWS Key、GitHub Token 等）

viteSecurityScan({
  checkBuildOutput: true  // 默认开启
})

HTML 安全检查（checkHtmlSecurity）

在 transformIndexHtml 阶段检查 index.html：

规则名	严重等级	说明
html-missing-sri	🟡 中	外部 CDN 脚本/样式缺少 integrity 属性，可能遭受供应链攻击
html-missing-csp	🔵 低	未设置 Content-Security-Policy meta 标签
html-iframe-no-sandbox	🟡 中	HTML 中 iframe 缺少 sandbox 属性

viteSecurityScan({
  checkHtmlSecurity: true  // 默认开启
})

依赖漏洞预警（checkDependencies）

在 buildStart 阶段读取 package.json 检查已知漏洞：

规则名	严重等级	说明
dep-known-vulnerability	视漏洞而定	检测依赖中已知 CVE 漏洞（lodash、axios、jsonwebtoken 等）
dep-deprecated-package	🔵 低	检测已废弃的不安全包（如 request）

viteSecurityScan({
  checkDependencies: true  // 默认开启
})

跳过特定行的安全检查

使用 @security-ignore 注释可以跳过某一行或代码块的安全扫描：

<template>
  <!-- @security-ignore -->
  <div v-html="trustedContent"></div>
</template>

<script setup>
// @security-ignore
const html = document.createElement('script') // 此行不会被扫描
</script>

支持的注释格式：

• // @security-ignore — JavaScript 单行注释
• /* @security-ignore */ — JavaScript 多行注释
• <!-- @security-ignore --> — HTML/Vue 模板注释

关闭非代码层检查

viteSecurityScan({
  checkBuildOutput: false,
  checkHtmlSecurity: false,
  checkDependencies: false
})

开发

# 安装依赖
npm install

# 开发模式（监听文件变化）
npm run dev

# 构建
npm run build

# 运行测试
npm test

License

MIT