@wuipkg/security-review

面向构建前与 CI 阶段的安全审查工具包，提供 CLI、Vite、webpack 与 ESLint 子入口。旨在从代码规范、静态资源暴露、第三方依赖风险等多维度阻断潜在安全隐患。

核心特性

• 多环节覆盖: 支持在 pre-commit (Git 暂存区), build (构建流程), post-build (构建产物检查) 及 ci 环境无缝运行。
• 全链路适配: 提供 CLI 原生命令执行，同时内置无缝衔接 Vite 和 Webpack 的构建插件。
• 丰富的审查规则: 内置近 20 种前沿前端与 Node 服务安全审查规则，包含：避免明文硬编码密钥、拦截非法 Npm 源仓库、排查 Target=_blank 与不安全的 URL 伪协议、防范 Prototype Pollution、禁用危险的深拷贝、排查 SourceMap 泄露与 .env 环境变量文件泄露、规避 ReDoS 攻击的正则与客户端 Cookie 非安全配置等。
• 灵活动态的配置: 支持 wui-security.config.ts 以及基于辅助函数的系统环境变量动态配置，快速适应复杂工程与自动化流水线。

安装

pnpm add @wuipkg/security-review -D

全局配置 (wui-security.config.ts)

在项目根目录创建 wui-security.config.ts，这里将作为所有工具链检查逻辑的真相来源 (Single Source of Truth)：

import { defineSecurityConfig } from '@wuipkg/security-review'

export default defineSecurityConfig({
  // 1. 指定 lockfile 与 .npmrc 允许出现的 npm 源域名
  allowedRegistryDomains: ['registry.npmjs.org', 'npm.company.com'],

  // 2. 指定执行 npm / pnpm audit 时使用的审计源
  audit: {
    registry: 'https://registry.npmjs.org'
  },

  // 3. 检查特定文件中是否忘记配置安全 Meta 标签或 SRI 属性
  advisoryFiles: {
    'csp-policy': ['index.html'],
    'subresource-integrity': ['index.html'],
    'referrer-policy': ['index.html']
  },

  // 4. 构建产物目录（用于 source-map-leak 泄露扫描规则）
  outDirs: ['dist', 'build'],

  // 5. 豁免的内部安全路由/持久化存储函数名单（供特定的规则检查器使用）
  safeNavigationFunctions: ['safeNavigate', 'router.push'],
  safeStorageFunctions: ['encryptedStorage'],

  // 6. 扫描的目标源代码扩展名及需要过滤忽略的路径
  sourceExtensions: ['.js', '.jsx', '.ts', '.tsx', '.vue'],
  ignore: ['node_modules', '.git', 'dist', '.turbo'],

  // 7. Trufflehog (高价值密钥扫描器) 集成支持
  trufflehog: {
    enabled: false, // 默认关闭
    command: 'trufflehog'
  },

  // 8. 导出离线 HTML 分析报告
  htmlReport: {
    enabled: false, // 默认关闭。可通过命令行 --html 覆盖
    outputFile: 'security-report.html', // 可选，指定输出的文件路径
    // template: './custom-template.html' // 可选，使用自定义 HTML 仪表盘模板
  },

  // 9. 自定义各个规则等级与参数配置 (off | warn | error)
  rules: {
    'hardcoded-secret': 'error',
    'dependency-audit': 'error',
    'unsafe-deep-clone': 'warn',
    'sensitive-storage': {
      level: 'error',
      options: { sensitiveKeys: ['token', 'idCard', 'passport'] }
    },
    'source-map-leak': {
      level: 'error',
      options: { outDirs: ['dist'] }
    },
    // 以下为内建的高级安全检测规则
    'env-file-exposure': 'error',         // 检测构建产物泄漏 .env
    'unsafe-url-scheme': 'error',         // 拦截 javascript: 等不安全协议
    'deprecated-crypto': 'error',         // 检测前端是否使用了由于年久而弱密码学的 MD5/SHA1
    'postmessage-wildcard': 'error',      // 拦截 postMessage 使用通配符 '*' origin
    'unsafe-target-blank': 'warn',        // 检测 target="_blank" 缺少 rel="noopener"
    'unsafe-regex': 'warn',               // 静态分析容易引发 ReDoS 攻击的正则漏洞
    'client-cookie-security': 'warn'      // 检测 Cookie 未设置 Secure 或 SameSite
  }
})

环境变量与动态配置

在 Node.js 运行时，wui-security.config.ts 会被动态加载解析。你可以直接通过 process.env 配合辅助函数灵活读取字符串、布尔及数组类型变量。

// wui-security.config.ts
import { defineSecurityConfig } from '@wuipkg/security-review'

/**
 * 辅助函数：将以逗号分隔的字符串转换为去重、无空值的纯净数组
 */
const parseEnvToArray = (envValue?: string, fallback: string[] = []): string[] => {
  if (!envValue) return fallback
  return envValue.split(',').map((item) => item.trim()).filter(Boolean)
}

export default defineSecurityConfig({
  allowedRegistryDomains: parseEnvToArray(
    process.env.SECURITY_ALLOWED_DOMAINS,
    ['registry.npmjs.org']
  ),
  audit: {
    registry: process.env.SECURITY_AUDIT_REGISTRY
  },
  outDirs: parseEnvToArray(
    process.env.SECURITY_OUT_DIRS,
    ['dist']
  )
})

在执行具体构建或 CLI 命令时，你可以通过注入环境变量来覆盖默认值（Node 20+ 环境直接注入 --env-file=.env 会更方便）：

SECURITY_ALLOWED_DOMAINS="npm.company.com,registry.npmjs.org" pnpm wui-security-review check --phase build

说明：

• allowedRegistryDomains 只用于校验 .npmrc、package-lock.json、pnpm-lock.yaml、yarn.lock 中出现的源域名是否可信
• audit.registry 只用于指定 npm audit / pnpm audit 请求的审计接口地址

使用指南

本工具库为您提供了在开发、提交以及 CI 等任意环节切入审查的能力：

1. CLI 命令行直接使用

推荐直接跑在 CI 流水线或通过 Husky 的 pre-commit 钩子调用：

# 全局全量源文件构建前审查
pnpm wui-security-review check --phase build

# 自动适配 CI 阶段（使用 json 格式化输出方便程序化解析截断流水线）
pnpm wui-security-review check --phase ci --format json

# 针对 Husky / lint-staged（通过 --staged 指令，仅检查 git 暂存区发生变更的文件提升速度）
pnpm wui-security-review check --phase pre-commit --staged

# 检查并额外输出可视化 HTML 大屏报告（默认输出至项目根目录 security-report.html）
pnpm wui-security-review check --phase build --html

# 指定独立输出 HTML 报告的自定义路径
pnpm wui-security-review check --phase build --html ./reports/dashboard.html

2. Vite 插件集成

如果不希望额外配 CLI，你可以把它当成普通打包环节的 Plugin 挂载，使得开发（dev）或生产构建（build）时同步报错拦截。

// vite.config.ts
import { defineConfig } from 'vite'
import { createViteSecurityPlugin } from '@wuipkg/security-review/vite'

export default defineConfig({
  plugins: [
    // 默认会自动寻址当前工程下的 wui-security.config.ts 全局配置
    createViteSecurityPlugin()
  ]
})

3. Webpack 插件集成

为传统的 Webpack 工程提供完全一致的使用体验：

// webpack.config.ts
import { createWebpackSecurityPlugin } from '@wuipkg/security-review/webpack'

export default {
  plugins: [
    createWebpackSecurityPlugin()
  ]
}

4. ESLint 静态代码提示并轨

我们将可做静态 AST 分析的安全规则单独整理到了此配置下，让你在写代码的第一时间就在 IDE 收到红色波浪线提示：

// eslint.config.js / .eslintrc.js
module.exports = [
  ...require('@wuipkg/lint/eslint'),
  // 接入专属的 AST 静态安全审查引擎池
  ...require('@wuipkg/security-review/eslint')
]