js-security

一个轻量级的 JavaScript 安全防护工具库，提供 XSS 攻击和 SQL 注入检测功能，支持自定义富文本字段白名单管理。

安装

使用 npm：

npm install js-security

使用 yarn：

yarn add js-security

使用方法

CommonJS 导入

const { security, Security, SecurityChecker, SecurityConfig } = require('js-security')

// 使用默认实例
const result = security.checkField('<script>alert("xss")</script>', 'userInput')
console.log(result) // { isValid: false, errors: [...] }

// 创建新实例
const mySecurity = new Security()
const checkResult = mySecurity.checkRequestData({
  username: 'admin',
  password: 'password123',
  comment: '<script>alert("xss")</script>'
})

ES6 模块导入

import { security, Security, SecurityChecker, SecurityConfig } from 'js-security'

// 使用方法同上

API 文档

Security 类

主要的安全检测类，提供完整的安全检测功能。

方法

checkField(value, fieldName = '')

检测单个字段的安全性。

参数：

• value (any): 要检测的值
• fieldName (string): 字段名称，可选

返回值：

• Object: 检测结果
  • isValid (boolean): 是否通过检测
  • errors (Array): 错误信息数组

示例：

const result = security.checkField('<script>alert("xss")</script>', 'userInput')
// { isValid: false, errors: ['字段 userInput 包含潜在的XSS攻击代码'] }

checkRequestData(data)

检测请求数据对象的安全性。

参数：

• data (Object): 要检测的数据对象

返回值：

• Object: 检测结果
  • isValid (boolean): 是否通过检测
  • errors (Array): 错误信息数组

示例：

const result = security.checkRequestData({
  username: 'admin',
  password: 'password123',
  comment: '<script>alert("xss")</script>'
})

updateConfig(newConfig)

更新安全配置。

参数：

• newConfig (Object): 新的配置对象

示例：

security.updateConfig({
  xssEnabled: false,
  maxStringLength: 5000
})

SecurityChecker 类

底层安全检测器，提供具体的检测方法。

方法

checkXSS(input, fieldName = '')

检测 XSS 攻击。

checkSQLInjection(input, fieldName = '')

检测 SQL 注入攻击。

checkObjectRecursively(obj, prefix = '', depth = 0)

递归检测对象中的所有字段。

SecurityConfig 类

安全配置管理类。

配置选项

• globalEnabled (boolean): 是否全局启用安全防护，默认 true
• xssEnabled (boolean): 是否启用 XSS 检测，默认 true
• sqlInjectionEnabled (boolean): 是否启用 SQL 注入检测，默认 true
• maxStringLength (number): 最大字符串长度，默认 10000
• maxObjectDepth (number): 最大对象深度，默认 10
• maxArrayLength (number): 最大数组长度，默认 1000

检测功能

XSS 攻击检测

自动检测以下 XSS 攻击模式：

• <script> 标签
• javascript: 协议
• on* 事件处理器（如 onclick, onload 等）
• <iframe>, <object>, <embed> 等危险标签
• eval(), setTimeout(), setInterval() 等危险函数

SQL 注入检测

自动检测以下 SQL 注入模式：

• UNION 查询
• SELECT, INSERT, UPDATE, DELETE 语句
• DROP, ALTER, CREATE 等 DDL 语句
• --, /**/ 等 SQL 注释
• OR 1=1, AND 1=1 等逻辑注入

富文本字段支持

对于包含 content, description, detail, rich 等关键词的字段名，会使用更宽松的 XSS 检测规则，允许部分 HTML 标签。

自定义富文本字段白名单

从 1.1.0 版本开始，支持自定义富文本字段白名单功能：

updateRichTextWhitelist(newWhitelist, append = false)

批量更新富文本字段白名单。

参数：

• newWhitelist (Array): 新的白名单数组
• append (boolean): 是否追加到现有白名单，默认 false（替换模式）

示例：

// 替换整个白名单
security.checker.updateRichTextWhitelist(['note', 'comment', 'customField'])

// 追加到现有白名单
security.checker.updateRichTextWhitelist(['newField1', 'newField2'], true)

错误处理

所有检测方法都会返回详细的错误信息，包括：

• 具体的错误类型（XSS 攻击、SQL 注入等）
• 出错的字段名
• 检测到的危险内容

3. 安全检查集成

// 在API请求处理中使用
function validateRequestData(req, res, next) {
  const result = security.checkRequestData(req.body)

  if (!result.isValid) {
    return res.status(400).json({
      error: '数据安全检查失败',
      details: result.errors
    })
  }

  next()
}

// 在Express中间件中使用
app.use('/api', validateRequestData)

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！

贡献指南

1. Fork 项目并创建您的功能分支
2. 添加测试用例确保功能正确性
3. 更新文档和示例代码
4. 提交 Pull Request 并描述您的更改

开发环境

# 克隆项目
git clone https://github.com/your-username/js-security.git

# 安装依赖
npm install

# 运行测试
npm test

# 运行示例
node test-risk-analysis.js

更新日志

1.1.0

• 新增自定义富文本字段白名单功能
• 支持动态添加/移除富文本字段
• 支持批量更新白名单
• 支持通配符模式匹配
• 新增 updateRichTextWhitelist() 方法

1.0.0

• 初始版本
• 支持 XSS 攻击检测
• 支持 SQL 注入检测
• 支持递归对象检测
• 支持配置管理