@blueking/bkui-knowledge 0.0.1-beta.1 → 0.0.1-beta.11

package/knowledge/skills/web-security-guide/references/xss.md

@@ -0,0 +1,134 @@
+# XSS（跨站脚本攻击）
+
+## 1. 漏洞原理
+
+- XSS（Cross-Site Scripting） 是指攻击者将恶意脚本注入到网页中，当其他用户访问该网页时，恶意脚本在其浏览器中执行，从而窃取用户信息、劫持账号或控制浏览器。
+- **本质是**：用户输入 -> 未转义输出 -> 浏览器执行脚本。
+
+## 2. 漏洞影响
+
+- 会话劫持：获取 document.cookie，冒用用户身份
+- 页面伪造：嵌入钓鱼表单，诱导用户操作
+- 权限滥用：使用 JS 执行接口请求，冒用用户操作（CSRF + XSS 联合攻击）
+- 木马注入：植入脚本实现远程控制、广告弹窗、挖矿脚本等
+- 数据篡改：修改页面结构，引导转账、误导点击等
+
+## 3. 典型业务场景
+
+### 3.1 【反射型 XSS】URL/表单参数未过滤即输出
+
+- 原理：攻击者构造 URL，诱导用户点击，恶意代码随参数被反射到页面并执行。
+- 特点：代码不落地，不存储，仅当前响应携带。
+- 漏洞示例代码如下：
+
+```python
+from flask import Flask, request, render_template_string
+app = Flask(__name__)
+
+@app.route('/greet')
+def greet():
+    name = request.args.get("name")
+    return render_template_string("Hello %s" % name)
+```
+
+- 访问 URL：`/greet?name=<script>alert(1)</script>`
+
+### 3.2 【存储型 XSS】恶意脚本被写入数据库并展示
+
+- 原理：攻击者提交评论、工单内容等含 JS 的文本，系统将其存入数据库并在前端原样输出。
+- 特点：影响持续存在，攻击范围广，可批量感染用户。
+- 漏洞示例代码如下：
+
+```python
+# 假设以下是评论展示逻辑
+@app.route("/comment/<int:id>")
+def show_comment(id):
+    content = db.get_comment(id)  # 数据库中含 <script> 标签
+    return render_template("comment.html", content=content)
+```
+
+- 若 content 来自用户输入，且未转义
+
+```html
+<!-- HTML 模板（Jinja2） -->
+{{ content }}
+```
+
+### 3.3 【DOM 型 XSS】JavaScript中操作DOM时拼接用户输入
+
+- 原理：客户端 JavaScript 使用 innerHTML、document.write() 等方式拼接不可信输入，导致脚本执行。
+- 特点：漏洞存在于前端代码，绕过后端防御。
+- 漏洞示例代码如下：
+
+```javascript
+<!-- 不可信输入拼接到 innerHTML 中 -->
+<script>
+  const param = new URLSearchParams(location.search).get('msg');
+  document.getElementById("result").innerHTML = param;
+</script>
+```
+
+- 访问：`http://example.com/?msg=<img src=1 onerror=alert(1)>`
+
+### 3.4 【混合型 XSS】后端输出配合前端执行形成复合攻击
+
+- 原理：后端将可控输入存入响应，前端再将该值通过 DOM 操作执行，形成复合型 XSS。
+- 特点：攻击链复杂，漏洞位置跨层。
+- 漏洞示例代码如下：
+
+```javascript
+<!-- 后端输出：<input id="msg" value="{{ user_input }}" hidden> -->
+<!-- 前端JS拼接未清洗的input值 -->
+<script>
+  const msg = document.getElementById("msg").value;
+  document.getElementById("box").innerHTML = msg;
+</script>
+```
+
+- 攻击者输入字段：`"><img src=1 onerror=alert(1)>`
+
+## 4. 漏洞修复方案
+
+### 4.1 【必须】使用 CSP（内容安全策略）
+
+- 限制页面只能加载自身 JS，禁止外链与内联脚本：
+
+```
+Content-Security-Policy: default-src 'self'; script-src 'self'; object-src 'none'
+```
+
+### 4.2 【必须】后端模板引擎开启自动转义
+
+- Flask（Jinja2）：默认开启，不要使用 |safe
+- Django：默认开启，严禁对用户输入使用 |safe
+
+### 4.3 【必须】所有输入内容严格做 XSS 过滤（非转义）
+
+```python
+from markupsafe import escape
+html = escape(user_input)
+```
+
+### 4.4 【必须】严禁前端 innerHTML 拼接用户输入
+
+```javascript
+// Bad Code:
+document.getElementById("box").innerHTML = location.search.slice(1);
+```
+
+```javascript
+// Good Code:
+document.getElementById("box").textContent = location.search.slice(1);
+```
+
+### 4.5 【必须】禁止在模板中使用 |safe 修饰用户可控字段
+
+- 禁止使用：{{ user_input|safe }}
+
+### 4.6 【建议】启用 HttpOnly cookie
+
+- 避免 JS 读取 cookie
+
+### 4.7 【建议】启用 SameSite=Strict
+
+- 防止 XSS 联合 CSRF

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@blueking/bkui-knowledge",
-  "version": "0.0.1-beta.1",
-  "description": "蓝鲸前端知识库 MCP 服务 - 自动同步 skills，支持 Cursor/VSCode",
+  "version": "0.0.1-beta.11",
+  "description": "蓝鲸前端知识库 MCP 服务 - 自动同步 skills，支持 Cursor/CodeBuddy",
   "main": "server/mcp-core.js",
   "bin": {
     "bkui-knowledge": "./bin/bkui-knowledge.js"
@@ -20,7 +20,7 @@
   "repository": {
     "type": "git"
   },
-  "keywords": ["mcp", "cursor", "ai", "knowledge-base", "bkui", "vue3"],
+  "keywords": ["mcp", "cursor", "codebuddy", "ai", "knowledge-base", "bkui", "vue3"],
   "author": "ielgnaw",
   "license": "ISC"
 }

package/server/mcp-core.js

@@ -21,31 +21,17 @@ const KNOWLEDGE_DIR = path.join(ROOT_DIR, 'knowledge');
 // 重要: 工具描述会被自动注入到 AI 上下文，因此在此嵌入核心规则
 // ---------------------------------------------------------
 const TOOLS = [
-  // L0 工具: 获取索引 (核心工具，描述中嵌入规则)
+  // L0 工具: 获取索引
   {
     name: "get_knowledge_index",
-    description: `【蓝鲸前端知识库】当用户需要使用 bk- 组件、bkui-vue、蓝鲸组件库、MagicBox 时，必须使用此知识库的工具。
-
-## 自动触发条件
-遇到以下关键词时，应主动调用本知识库工具：
-- bk-navigation, bk-menu, bk-table, bk-form, bk-dialog 等 bk- 前缀组件
-- bkui-vue, 蓝鲸组件库, MagicBox, 蓝鲸前端
-- 设计稿还原, 管理后台页面
-
-## 强制规范
-- 组件库: bkui-vue (前缀 bk-)
-- 语法: Vue 3 <script setup lang="ts">
-- 样式: MagicBox 原子类 (mt10, mb20)
-
-## ⚠️ 常见错误
-- bk-navigation 用 default-open，不是 default-open-keys
-- bk-menu 用 opened-keys，不是 default-open-keys
-- bk-dialog 用 v-model:isShow，不是 v-model
-
-## 工作流程
-1. 使用 bk- 组件前，先调用 get_component_api 获取 API
-2. 需要页面模板时，调用 get_skill({ skillId: 'bkui-builder' }) 获取规则
-3. 根据布局分析报告按需加载模版资源`,
+    description: `【蓝鲸前端知识库】遇到 bk- 组件、bkui-vue、蓝鲸组件库时必须使用。
+
+首次使用时，请先读取 .cursor/skills/bkui-quick-start.md 获取完整规范和索引。
+
+快速参考：
+- bk-dialog 用 v-model:isShow（不是 v-model）
+- bk-menu 用 opened-keys（不是 default-open-keys）
+- bk-navigation 用 default-open（不是 default-open-keys）`,
     inputSchema: {
       type: "object",
       properties: {
@@ -61,7 +47,7 @@ const TOOLS = [
   // L1 工具: 获取 Skill 详情
   {
     name: "get_skill",
-    description: "获取技能文档 (Markdown)。可用 ID: bkui-builder(设计稿还原), layout-rules(布局规范), api-standard(请求封装), pinia-setup(状态管理), vite-migration(Vite迁移), bundle-optimization(构建优化), virtual-list(虚拟滚动), unit-testing(单测), bkui-cheatsheet(速查表)",
+    description: "获取技能文档 (Markdown)。可用 ID: bkui-quick-start(入门指南), bkui-builder(设计稿还原), bkui-cheatsheet(速查表), api-standard(请求封装), pinia-setup(状态管理), vite-migration(Vite迁移), bundle-optimization(构建优化), virtual-list(虚拟滚动), unit-testing(单测), code-review(代码评审)",
     inputSchema: {
       type: "object",
       properties: {
@@ -119,6 +105,22 @@ const TOOLS = [
       type: "object",
       properties: {}
     }
+  },
+
+  // L3 工具: 获取资源文件 (绕过 Cursor FetchMcpResource bug)
+  {
+    name: "get_resource",
+    description: "获取 skill 或 example 资源文件内容。URI 格式: skill://skillId/subDir/path 或 example://componentId/exampleName。用于获取布局模板、代码示例等资源。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        uri: {
+          type: "string",
+          description: "资源 URI，如: skill://bkui-builder/assets/layouts/admin-layout-dark.vue, example://table/basic"
+        }
+      },
+      required: ["uri"]
+    }
   }
 ];
 
@@ -167,8 +169,9 @@ function buildResources() {
     if (manifest.skills && manifest.skills.items) {
       const skillsBasePath = path.join(KNOWLEDGE_DIR, manifest.skills.base_path);
       manifest.skills.items.forEach(skill => {
-        const skillDir = path.join(skillsBasePath, skill.id);
-        ['scripts', 'references', 'assets'].forEach(subDir => {
+        // 使用 skill.path 推断目录（支持外部 skill）
+        const skillDir = path.join(skillsBasePath, path.dirname(skill.path));
+        ['scripts', 'references', 'assets', 'rules'].forEach(subDir => {
           const subDirPath = path.join(skillDir, subDir);
           if (fs.existsSync(subDirPath)) {
             scanSkillDir(subDirPath, '').forEach(filePath => {
@@ -289,7 +292,7 @@ const Handlers = {
 
     // 检查 skill 目录下的附属资源，生成 skill:// URIs
     const skillDir = path.dirname(filePath);
-    const subDirs = ['scripts', 'references', 'assets'];
+    const subDirs = ['scripts', 'references', 'assets', 'rules'];
     const availableResources = [];
 
     subDirs.forEach(dir => {
@@ -447,7 +450,6 @@ ${recommendedIds.map(id => {
 ### 同步位置
 
 - \`.cursor/skills/*.md\` - 技能文档
-- \`.cursor/commands/*.md\` - 斜杠指令 (可通过 /${recommendedIds[0]} 调用)
 - \`.cursor/rules/bkui.mdc\` - 规则文件 (自动注入 AI 上下文)
 - \`.cursor/.bkui-knowledge-version\` - 版本标记
 
@@ -462,6 +464,17 @@ ${recommendedIds.map(id => {
     return { content: [{ type: "text", text: result }] };
   },
 
+  // L3: 获取资源文件 (绕过 Cursor FetchMcpResource bug)
+  async get_resource({ uri }) {
+    const result = await readResource(uri);
+    // readResource 返回 { content: string } 或 { contents: [{ text }] }
+    const text = result.content || (result.contents && result.contents[0] && result.contents[0].text);
+    if (!text) {
+      throw new Error(`Resource not found or empty: ${uri}`);
+    }
+    return { content: [{ type: "text", text }] };
+  },
+
   // Prompt 处理
   async get_prompt({ name }) {
     if (name === "BKUI-EXPERT") {
@@ -566,8 +579,8 @@ async function handleExampleResource(uri) {
     throw new Error(`Example '${exampleName}' not found for ${componentId}. Available: ${compExamples.examples.map(e => e.name).join(', ')}`);
   }
 
-  // 读取示例文件
-  const examplePath = path.join(ROOT_DIR, manifest.componentExamples.base_path, example.file);
+  // 读取示例文件 (base_path 相对于 KNOWLEDGE_DIR)
+  const examplePath = path.join(KNOWLEDGE_DIR, manifest.componentExamples.base_path, example.file);
   if (!fs.existsSync(examplePath)) {
     throw new Error(`Example file not found: ${example.file}`);
   }
@@ -588,8 +601,8 @@ async function handleSkillResource(uri) {
 
   const [, skillId, subDir, filePath] = match;
 
-  if (!['scripts', 'references', 'assets'].includes(subDir)) {
-    throw new Error(`Invalid skill subDir: ${subDir}. Must be scripts, references, or assets`);
+  if (!['scripts', 'references', 'assets', 'rules'].includes(subDir)) {
+    throw new Error(`Invalid skill subDir: ${subDir}. Must be scripts, references, assets, or rules`);
   }
 
   const manifest = loadManifest();
@@ -598,7 +611,9 @@ async function handleSkillResource(uri) {
     throw new Error(`Skill not found: ${skillId}`);
   }
 
-  const fullPath = path.join(KNOWLEDGE_DIR, manifest.skills.base_path, skillId, subDir, filePath);
+  // 使用 skill.path 推断目录（支持外部 skill）
+  const skillDir = path.dirname(skill.path);
+  const fullPath = path.join(KNOWLEDGE_DIR, manifest.skills.base_path, skillDir, subDir, filePath);
   if (!fs.existsSync(fullPath)) {
     throw new Error(`Skill resource not found: ${subDir}/${filePath}`);
   }