@blueking/bkui-knowledge 0.0.1-beta.1

package/knowledge/skills/nodejs-security-check/references/fix-examples.md

@@ -0,0 +1,384 @@
+# Node.js 安全问题修复示例
+
+各类安全问题的详细修复代码示例。
+
+## 1. 输入验证
+
+### INPUT-001: 缺少 Schema 验证
+
+```javascript
+// ❌ 危险：直接使用请求数据
+app.post('/transfer', (req, res) => {
+  const { to, amount } = req.body; // 未验证
+  paySvc.transfer(to, amount);
+});
+
+// ✅ 使用 Ajv Schema 验证
+import Ajv from 'ajv';
+const ajv = new Ajv({ coerceTypes: 'array', allErrors: true, removeAdditional: 'all' });
+
+const TransferSchema = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    to:    { type: 'string', minLength: 4, maxLength: 64, pattern: '^[a-zA-Z0-9_-]+$' },
+    amount:{ type: 'number', minimum: 0.01, maximum: 1000000 },
+    note:  { type: 'string', maxLength: 140 }
+  },
+  required: ['to','amount']
+};
+const validate = ajv.compile(TransferSchema);
+
+app.post('/transfer', (req, res, next) => {
+  if (!validate(req.body)) return res.status(400).json({ code:'INVALID_ARG' });
+  next();
+}, async (req, res) => {
+  const { to, amount, note } = req.body;
+  await paySvc.transfer(to, amount, note ?? '');
+  res.json({ ok: 1 });
+});
+```
+
+## 2. 命令执行安全
+
+### CMD-001/002: 命令注入
+
+```javascript
+// ❌ 危险模式
+exec(`ffmpeg -i ${req.body.in} -vf ${req.body.filter} ${req.body.out}`);
+spawn('sh', ['-c', userCmd]);
+
+// ✅ 使用 execFile + 参数数组 + 白名单
+import { execFile } from 'child_process';
+const FFMPEG = '/usr/bin/ffmpeg';
+const ALLOWED_FILTERS = new Set(['scale=320:-1', 'grayscale']);
+
+function mapArgs({ in: input, filter, out }) {
+  if (!ALLOWED_FILTERS.has(filter)) throw new Error('filter not allowed');
+  return ['-i', input, '-vf', filter, '-y', out];
+}
+
+app.post('/thumb', async (req, res) => {
+  const args = mapArgs(req.body);
+  execFile(FFMPEG, args, {
+    timeout: 20_000,
+    maxBuffer: 5 * 1024 * 1024,
+    cwd: '/srv/worker',
+    env: { PATH: '/usr/bin:/bin' },
+    uid: 1001, gid: 1001
+  }, (err) => {
+    if (err) return res.status(500).json({ code:'CMD_FAILED' });
+    res.json({ ok:1 });
+  });
+});
+```
+
+## 3. 文件路径安全
+
+### FILE-001: 路径穿越
+
+```javascript
+// ❌ 危险模式：路径穿越
+res.sendFile(path.join(ROOT, req.query.file)); // ../../etc/passwd
+
+// ✅ 根目录约束 + 符号链接检查
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+const ROOT = '/srv/uploads';
+
+async function resolveSafe(p) {
+  const abs = path.resolve(ROOT, p);
+  const real = await fs.realpath(path.dirname(abs)).then(d => path.join(d, path.basename(abs)));
+  if (!real.startsWith(ROOT + path.sep)) throw new Error('path escape');
+  return real;
+}
+
+app.get('/download', async (req, res) => {
+  const file = await resolveSafe(req.query.file);
+  res.sendFile(file, {
+    headers: { 'X-Content-Type-Options': 'nosniff', 'Content-Disposition': 'attachment' }
+  });
+});
+```
+
+## 4. SSRF 防护
+
+### SSRF-001/002: 出站请求未校验
+
+```javascript
+// ❌ 危险模式：直接请求用户 URL
+const r = await fetch(req.query.endpoint);
+
+// ✅ 协议 + 私网 + DNS 重绑定防护
+import dns from 'node:dns/promises';
+import net from 'node:net';
+
+function isPrivate(ip) {
+  if (net.isIPv4(ip)) {
+    const n = ip.split('.').map(Number);
+    const v = (n[0]<<24)|(n[1]<<16)|(n[2]<<8)|n[3];
+    const inRange = (a,b) => v>=a && v<=b;
+    return (
+      inRange(0x0A000000,0x0AFFFFFF) ||      // 10.0.0.0/8
+      inRange(0xAC100000,0xAC1FFFFF) ||      // 172.16.0.0/12
+      inRange(0xC0A80000,0xC0A8FFFF) ||      // 192.168.0.0/16
+      inRange(0x7F000000,0x7FFFFFFF) ||      // 127.0.0.0/8
+      inRange(0xA9FE0000,0xA9FEFFFF) ||      // 169.254.0.0/16
+      ip === '169.254.169.254'               // 元数据
+    );
+  }
+  return ip === '::1' || ip.startsWith('fe80:');
+}
+
+async function assertPublicHost(u) {
+  const url = new URL(u);
+  if (!['http:','https:'].includes(url.protocol)) throw new Error('protocol not allowed');
+  const addrs = await dns.lookup(url.hostname, { all: true });
+  if (addrs.some(a => isPrivate(a.address))) throw new Error('private address blocked');
+  return url;
+}
+
+async function safeFetch(u, { timeoutMs = 8000, redirects = 3, ...init } = {}) {
+  let url = await assertPublicHost(u);
+  let i = 0;
+  while (i++ <= redirects) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    const res = await fetch(url, { ...init, signal: ctrl.signal, redirect: 'manual' });
+    clearTimeout(t);
+    if ([301,302,303,307,308].includes(res.status)) {
+      const loc = res.headers.get('location');
+      if (!loc) break;
+      url = await assertPublicHost(new URL(loc, url).toString());
+      continue;
+    }
+    return res;
+  }
+  throw new Error('too many redirects');
+}
+```
+
+## 5. SQL 注入防护
+
+### SQL-001: SQL 字符串拼接
+
+```javascript
+// ❌ 危险模式
+await db.query(`SELECT * FROM users WHERE name='${req.query.name}'`);
+
+// ✅ 参数化查询
+// PostgreSQL
+await db.query('SELECT * FROM users WHERE name=$1', [req.query.name]);
+
+// MySQL2
+await db.execute('SELECT * FROM users WHERE name=?', [req.query.name]);
+
+// ✅ 白名单字段/排序
+const ORDER = new Set(['created_at','id']);
+const order = ORDER.has(req.query.order) ? req.query.order : 'created_at';
+const dir = req.query.dir === 'asc' ? 'ASC' : 'DESC';
+const size = Math.min(Math.max(+req.query.size||20, 1), 100);
+await db.query(
+  `SELECT id,name FROM users ORDER BY ${order} ${dir} LIMIT $1 OFFSET $2`,
+  [size, (+req.query.page||1-1)*size]
+);
+```
+
+## 6. NoSQL 注入防护
+
+### NOSQL-001: 未过滤操作符
+
+```javascript
+// ❌ 危险模式：操作符注入
+// 传 {"username": {"$ne": null}} 即可绕过
+const user = await col.findOne({ username: req.body.username });
+
+// ✅ 递归清洗 $ 和 . 操作符
+function sanitize(obj) {
+  if (obj && typeof obj === 'object') {
+    for (const k of Object.keys(obj)) {
+      if (k.startsWith('$') || k.includes('.')) delete obj[k];
+      else sanitize(obj[k]);
+    }
+  }
+  return obj;
+}
+const q = sanitize({ username: String(req.body.username || '') });
+const user = await col.findOne(q, { projection: { _id:0, id:1, nickname:1 } });
+
+// ✅ 限制可更新字段
+const ALLOW_SET = new Set(['nickname','avatar']);
+const update = {};
+for (const [k,v] of Object.entries(req.body)) if (ALLOW_SET.has(k)) update[k] = v;
+await col.updateOne({ id: req.user.id }, { $set: update }, { upsert: false });
+```
+
+## 7. 模板注入防护
+
+### SSR-001: 使用不转义输出
+
+```javascript
+// ❌ 危险模式
+<div><%- userInput %></div>   // EJS 不转义
+<div>{{{userInput}}}</div>    // Handlebars 不转义
+
+// ✅ EJS/Handlebars 默认转义
+<div><%= userInput %></div>   // EJS 自动转义
+<div>{{userInput}}</div>      // Handlebars 自动转义
+
+// ✅ 模板白名单
+const TPL = new Set(['home','profile','order']);
+const name = TPL.has(req.params.page) ? req.params.page : 'home';
+res.render(name, data);
+```
+
+## 8. JWT 安全
+
+### JWT-001/002: 未限制算法
+
+```javascript
+// ❌ 危险模式：未限制算法、未校验声明
+const payload = jwt.verify(token, PUBLIC_KEY);
+
+// ✅ 算法白名单 + 声明校验 + 固定 JWKS
+import * as jose from 'jose';
+
+const OIDC_ISS  = 'https://sso.tencent.com';
+const JWKS_URL  = new URL('https://sso.tencent.com/.well-known/jwks.json');
+const JWKS      = jose.createLocalJWKSet(JWKS_URL);
+
+export async function verifyJWT(token) {
+  const { payload, protectedHeader } = await jose.jwtVerify(token, JWKS, {
+    issuer: OIDC_ISS,
+    audience: 'my-service',
+    algorithms: ['RS256','ES256'],
+    maxTokenAge: '15m',
+    clockTolerance: '60s'
+  });
+  if (protectedHeader.typ && protectedHeader.typ !== 'JWT') throw new Error('bad typ');
+  return payload;
+}
+```
+
+## 9. Webhook 验签
+
+### WEBHOOK-001: 未验签
+
+```javascript
+// ❌ 危险模式：无验签
+app.post('/webhook', (req, res) => {
+  handleWebhook(req.body); // 直接处理
+});
+
+// ✅ HMAC 验签 + 时间窗 + 重放防护
+import crypto from 'node:crypto';
+import bodyParser from 'body-parser';
+
+app.post('/webhook/vendor-x',
+  bodyParser.raw({ type: 'application/json', limit: '512kb' }),
+  (req, res) => {
+    const sig = req.get('x-signature');
+    const ts  = Number((sig.match(/t=(\d+)/)||[])[1]);
+    const mac = (sig.match(/v1=([a-f0-9]+)/)||[])[1];
+    if (!ts || !mac) return res.status(400).end();
+
+    // 时间窗
+    if (Math.abs(Date.now() - ts*1000) > 5*60*1000) return res.status(400).end();
+
+    // 计算 HMAC
+    const secret = process.env.WEBHOOK_SECRET;
+    const base   = `t=${ts}.${req.body.toString('utf8')}`;
+    const calc   = crypto.createHmac('sha256', secret).update(base).digest('hex');
+
+    // 常量时间比较
+    const a = Buffer.from(mac, 'hex'); const b = Buffer.from(calc, 'hex');
+    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.status(401).end();
+
+    // 重放防护
+    const eventId = req.get('x-event-id');
+    if (!eventId || !tryConsumeOnce(`wh:${eventId}`, 10 * 60)) return res.status(409).end();
+
+    res.status(204).end();
+  }
+);
+```
+
+## 10. 容器安全
+
+### CONTAINER-001: 容器以 root 运行
+
+```dockerfile
+# ❌ 危险配置
+USER root
+
+# ✅ 多阶段构建 + 非 root
+FROM node:20-alpine AS build
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm i --frozen-lockfile
+COPY . .
+RUN pnpm build && pnpm prune --prod
+
+FROM gcr.io/distroless/nodejs20-debian12
+WORKDIR /srv/app
+COPY --from=build /app/dist ./dist
+COPY --from=build /app/node_modules ./node_modules
+USER 10001:10001
+ENV NODE_ENV=production TZ=Etc/UTC
+CMD ["dist/index.js"]
+```
+
+```yaml
+# ✅ K8s 安全上下文
+securityContext:
+  runAsNonRoot: true
+  allowPrivilegeEscalation: false
+  readOnlyRootFilesystem: true
+  capabilities: { drop: ["ALL"] }
+  seccompProfile: { type: RuntimeDefault }
+```
+
+## 11. 可自动修复的问题
+
+### 添加请求体大小限制
+
+```javascript
+// ❌ 检测：无限制
+app.use(express.json());
+
+// ✅ 修复：添加 limit 参数
+app.use(express.json({ limit: '100kb' }));
+```
+
+### 添加安全响应头
+
+```javascript
+// ✅ 修复：添加 helmet
+import helmet from 'helmet';
+app.use(helmet());
+```
+
+### 禁用 x-powered-by
+
+```javascript
+// ✅ 修复
+app.disable('x-powered-by');
+```
+
+### Cookie 安全属性
+
+```javascript
+// ❌ 检测：缺少安全属性
+res.cookie('sid', sid);
+
+// ✅ 修复：添加安全属性
+res.cookie('sid', sid, {
+  httpOnly: true, secure: true, sameSite: 'lax'
+});
+```
+
+---
+
+> 更多内容请按需加载：
+> - 安全工具库：`skill://nodejs-security-check/references/security-toolkit.md`

package/knowledge/skills/nodejs-security-check/references/report-format.md

@@ -0,0 +1,165 @@
+# 安全审查报告格式说明
+
+审查报告采用结构化格式，便于快速理解和处理。
+
+## 报告结构
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Node.js 安全审查报告
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+项目: {项目名}
+框架: {Express/Koa/Fastify/NestJS}
+扫描文件: {N} 个 JavaScript/TypeScript 文件
+扫描时间: {时间}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+问题摘要
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🔴 严重: N 个问题
+🟡 中等: N 个问题
+⚪ 建议: N 个改进项
+
+📊 安全评分: XX/100
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+严重问题详情
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🔴 {规则ID}: {问题标题}
+   文件: {文件路径}:{行号}
+   代码: {问题代码}
+
+   风险: {风险说明}
+
+   推荐修复:
+   {修复代码示例}
+
+   参考: Nodejs代码安全规范.md 第 X.X.X 节
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+配置建议
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. 依赖安全
+2. 请求体限制
+3. 安全响应头
+4. 日志脱敏
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+下一步行动
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. 优先修复 N 个严重问题
+2. 创建安全工具库
+3. 配置 Schema 验证中间件
+4. 在 CI/CD 中集成安全检查
+5. 配置 CodeCC/SAST 扫描
+```
+
+## 结论类型
+
+| 结论 | 安全评分 | 行动 |
+|------|----------|------|
+| `安全` | 90+ | 可以发布 |
+| `需要关注` | 80-89 | 有中等问题需要处理 |
+| `需要修复` | 70-79 | 有严重问题需要修复 |
+| `高风险` | < 70 | 阻止发布 |
+
+## JSON 报告格式
+
+```json
+{
+  "summary": {
+    "project": "my-backend",
+    "framework": "Express 4.18.2",
+    "filesScanned": 89,
+    "scanTime": "2026-01-19T20:15:32Z",
+    "issues": {
+      "critical": 3,
+      "medium": 8,
+      "low": 15
+    },
+    "score": 72
+  },
+  "issues": [
+    {
+      "id": "1",
+      "ruleId": "CMD-001",
+      "severity": "critical",
+      "category": "命令注入",
+      "file": "src/services/video.js",
+      "line": 42,
+      "column": 10,
+      "code": "exec(`ffmpeg -i ${req.body.input}`)",
+      "message": "使用字符串拼接构建命令，存在命令注入风险",
+      "recommendation": "使用 execFile + 参数数组 + 白名单过滤",
+      "fixable": false,
+      "references": ["Nodejs代码安全规范.md:1.2.1"]
+    }
+  ],
+  "config": {
+    "hasHelmet": false,
+    "hasRateLimit": false,
+    "hasSchemaValidation": false,
+    "dependencies": {
+      "hasVulnerabilities": true,
+      "vulnerablePackages": ["lodash@4.17.11"]
+    }
+  },
+  "recommendations": [
+    "配置 .npmrc 使用内网镜像源",
+    "添加请求体大小限制",
+    "使用 helmet 中间件"
+  ]
+}
+```
+
+## 问题详情格式
+
+每个问题包含以下字段：
+
+| 字段 | 说明 |
+|------|------|
+| ruleId | 规则唯一标识（如 CMD-001） |
+| severity | 严重程度（critical/medium/low） |
+| category | 问题类别（命令注入/SSRF 等） |
+| file | 文件路径 |
+| line | 行号 |
+| code | 问题代码片段 |
+| message | 问题描述 |
+| recommendation | 修复建议 |
+| fixable | 是否可自动修复 |
+| references | 参考文档 |
+
+## 配置检查报告
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+配置安全检查
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📦 依赖安全
+   ✅ 使用内网 NPM 镜像
+   ✅ 存在 package-lock.json
+   ⚠️ 发现 2 个高危漏洞依赖
+
+🔧 运行环境
+   ✅ Node.js LTS 版本 (20.x)
+   ⚠️ 未配置资源限制
+
+🔐 密钥管理
+   ✅ 未发现硬编码密钥
+   ⚠️ 建议使用 KMS
+
+🐳 容器安全
+   ⚠️ 以 root 用户运行
+   ⚠️ 未配置 seccomp
+```
+
+---
+
+> 报告示例请按需加载：
+> - 评分标准：`skill://nodejs-security-check/references/scoring-standard.md`

package/knowledge/skills/nodejs-security-check/references/scoring-standard.md

@@ -0,0 +1,88 @@
+# Node.js 安全评分标准
+
+审查时可参考此评分标准对代码安全性进行量化评估。
+
+## 基本要求（80分）
+
+### 输入验证（20分）
+
+| 检查项 | 分值 | 说明 |
+|--------|------|------|
+| Schema 验证请求数据 | 8 | 使用 Ajv/Zod/Joi |
+| 请求体大小限制 | 5 | 配置 limit 参数 |
+| HPP 防护 | 4 | 防止参数污染 |
+| 文件上传限制 | 3 | 大小/类型/魔数校验 |
+
+### 命令与文件安全（20分）
+
+| 检查项 | 分值 | 说明 |
+|--------|------|------|
+| 无命令注入风险 | 8 | 使用 execFile + 参数数组 |
+| 路径穿越防护 | 7 | 校验路径在根目录内 |
+| 文件上传安全 | 5 | 独立存储目录 |
+
+### 网络安全（15分）
+
+| 检查项 | 分值 | 说明 |
+|--------|------|------|
+| SSRF 防护 | 6 | 私网阻断 + DNS 重绑定防护 |
+| 安全响应头 | 5 | 使用 helmet |
+| CORS 配置合理 | 4 | 不反射 Origin |
+
+### 数据库安全（15分）
+
+| 检查项 | 分值 | 说明 |
+|--------|------|------|
+| 无 SQL 注入 | 7 | 参数化查询 |
+| 无 NoSQL 注入 | 5 | 过滤 $ 操作符 |
+| 字段白名单更新 | 3 | 防止 Mass Assignment |
+
+### 认证授权（10分）
+
+| 检查项 | 分值 | 说明 |
+|--------|------|------|
+| JWT 算法限制 | 4 | 白名单算法 |
+| 会话安全 | 3 | Cookie 安全属性 |
+| 后端鉴权 | 3 | 不依赖前端权限控制 |
+
+## 加分项（每项最高10分）
+
+- **密钥管理**：使用 KMS、环境隔离
+- **容器安全**：非 root、seccomp、资源限制
+- **依赖安全**：内网镜像、lockfile、SBOM
+- **日志脱敏**：结构化日志、敏感信息脱敏
+- **限速防护**：敏感接口限速、渐进惩罚
+
+## 评分等级
+
+| 分数区间 | 等级 | 结论 |
+|---------|------|------|
+| 90+ | 安全 | 可以发布 |
+| 80-89 | 需要关注 | 有中等问题 |
+| 70-79 | 需要修复 | 有严重问题 |
+| < 70 | 高风险 | 阻止发布 |
+
+## 一票否决项
+
+以下问题无论评分多高，都需要修复后才能发布：
+
+| 问题 | 规则 ID | 说明 |
+|------|---------|------|
+| 命令注入漏洞 | CMD-001 | exec 拼接用户输入 |
+| SSRF 漏洞 | SSRF-001 | 未校验出站请求 URL |
+| SQL 注入漏洞 | SQL-001 | SQL 字符串拼接 |
+| 路径穿越漏洞 | FILE-001 | 可访问任意文件 |
+| 密钥硬编码 | SECRET-001 | 代码中包含密钥/凭证 |
+| 容器 root 运行 | CONTAINER-001 | 生产环境以 root 运行 |
+| JWT none 算法 | JWT-001 | 允许 none 算法 |
+
+## 配置安全评分
+
+| 检查项 | 分值 | 说明 |
+|--------|------|------|
+| 使用内网 NPM 镜像 | 10 | DEP-001 |
+| 存在 lockfile | 5 | DEP-002 |
+| Node.js LTS 版本 | 5 | ENV-001 |
+| 禁用 --inspect | 5 | ENV-002 |
+| 非 root 运行 | 10 | ENV-003 |
+| rejectUnauthorized: true | 5 | TLS-001 |