opencode-api-security-testing 3.0.2 → 3.0.3

package/examples/basic-usage.md

@@ -0,0 +1,127 @@
+# API Security Testing Examples
+
+## 快速开始
+
+### 1. 基础扫描
+
+```
+@api-cyber-supervisor 对 https://example.com 进行全面安全扫描
+```
+
+### 2. 针对特定端点扫描
+
+```
+@api-cyber-supervisor 扫描 https://api.example.com/v1 端点
+```
+
+### 3. 使用工具直接扫描
+
+```
+api_security_scan target="https://api.example.com" scan_type="full"
+```
+
+---
+
+## 工具使用示例
+
+### 浏览器采集
+
+```
+browser_collect url="https://example.com"
+```
+
+### SQL 注入测试
+
+```
+sqli_test endpoint="https://api.example.com/user?id=1" param="id"
+```
+
+### IDOR 测试
+
+```
+idor_test endpoint="https://api.example.com/user/1" resource_id="1"
+```
+
+### GraphQL 测试
+
+```
+graphql_test endpoint="https://api.example.com/graphql"
+```
+
+### 云存储测试
+
+```
+cloud_storage_test bucket_url="https://bucket.s3.amazonaws.com"
+```
+
+---
+
+## Agent 委派示例
+
+### 使用 Cyber Supervisor
+
+```
+@api-cyber-supervisor 
+对 https://api.example.com 进行完整的安全测试
+包含以下漏洞测试：
+- SQL 注入
+- IDOR 越权
+- JWT 安全
+- 敏感数据泄露
+```
+
+### 使用资源探测专家
+
+```
+@api-resource-specialist
+发现 https://example.com 的所有 API 端点
+重点关注：
+- 认证相关端点
+- 用户数据端点
+- 支付相关端点
+```
+
+### 使用漏洞挖掘专家
+
+```
+@api-probing-miner
+针对发现的端点进行漏洞挖掘
+优先测试：
+- SQL 注入
+- XSS
+- IDOR
+```
+
+### 使用漏洞验证专家
+
+```
+@api-vuln-verifier
+验证以下漏洞：
+- 类型: SQL 注入
+- 端点: https://api.example.com/user?id=1
+```
+
+---
+
+## 报告输出示例
+
+当扫描完成时，会输出类似以下的报告：
+
+```markdown
+## 安全测试报告
+
+### 目标信息
+- URL: https://api.example.com
+- 端点总数: 42
+- 发现漏洞: 5
+
+### 漏洞详情
+| # | 类型 | 端点 | 严重程度 |
+|---|------|------|---------|
+| 1 | SQL注入 | /api/user?id=1 | HIGH |
+| 2 | IDOR | /api/user/:id | MEDIUM |
+| 3 | 敏感数据 | /api/config | LOW |
+
+### PoC
+curl "https://api.example.com/api/user?id=1'%20OR%201=1--"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-api-security-testing",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "API Security Testing Plugin for OpenCode - Automated vulnerability scanning and penetration testing",
   "type": "module",
   "main": "src/index.ts",
@@ -9,11 +9,14 @@
     "agents/",
     "core/",
     "references/",
+    "examples/",
     "SKILL.md",
-    "postinstall.mjs"
+    "postinstall.mjs",
+    "preuninstall.mjs"
   ],
   "scripts": {
-    "postinstall": "node postinstall.mjs"
+    "postinstall": "node postinstall.mjs",
+    "preuninstall": "node preuninstall.mjs"
   },
   "keywords": [
     "opencode",

package/preuninstall.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+/**
+ * preuninstall.mjs - API Security Testing Plugin
+ * 
+ * Removes installed files when the package is uninstalled.
+ */
+
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+function getOpencodeBaseDir() {
+  const home = process.env.HOME || process.env.USERPROFILE || "/root";
+  return join(home, ".config", "opencode");
+}
+
+function deleteFile(filePath) {
+  try {
+    if (existsSync(filePath)) {
+      rmSync(filePath);
+      console.log(`  ✓ Removed: ${filePath}`);
+      return true;
+    }
+  } catch (err) {
+    console.error(`  ✗ Failed to remove: ${filePath} - ${err.message}`);
+  }
+  return false;
+}
+
+function deleteDirectory(dirPath) {
+  try {
+    if (existsSync(dirPath)) {
+      rmSync(dirPath, { recursive: true });
+      console.log(`  ✓ Removed directory: ${dirPath}`);
+      return true;
+    }
+  } catch (err) {
+    console.error(`  ✗ Failed to remove directory: ${dirPath} - ${err.message}`);
+  }
+  return false;
+}
+
+function main() {
+  const baseDir = getOpencodeBaseDir();
+  const agentsDir = join(baseDir, "agents");
+  const skillDir = join(baseDir, "skills", "api-security-testing");
+  
+  console.log("[api-security-testing] Uninstalling...");
+  console.log(`  Base directory: ${baseDir}`);
+
+  let removedCount = 0;
+  let totalCount = 0;
+
+  // 1. Remove agent files
+  console.log("\n[1/2] Removing agents...");
+  if (existsSync(agentsDir)) {
+    const agentFiles = readdirSync(agentsDir).filter(f => f.endsWith(".md"));
+    totalCount += agentFiles.length;
+    
+    for (const file of agentFiles) {
+      const filePath = join(agentsDir, file);
+      // Only remove our agents (prefix with our plugin name)
+      if (file.startsWith("api-")) {
+        if (deleteFile(filePath)) removedCount++;
+      } else {
+        console.log(`  - Skipped (not our agent): ${file}`);
+      }
+    }
+  }
+
+  // 2. Remove skill directory
+  console.log("\n[2/2] Removing skill...");
+  if (existsSync(skillDir)) {
+    if (deleteDirectory(skillDir)) {
+      removedCount++;
+    }
+  }
+
+  // Summary
+  console.log("\n========================================");
+  console.log(`Uninstall complete.`);
+  console.log("\nNote: If you reinstall the package, the postinstall script will re-install the files.");
+}
+
+main();

package/src/index.ts

@@ -7,23 +7,38 @@ import { existsSync } from "fs";
 const SKILL_DIR = "skills/api-security-testing";
 const CORE_DIR = `${SKILL_DIR}/core`;
 
-function getSkillPath(ctx: { directory: string }): string {
-  return join(ctx.directory, SKILL_DIR);
-}
-
 function getCorePath(ctx: { directory: string }): string {
   return join(ctx.directory, CORE_DIR);
 }
 
-function checkDeps(ctx: { directory: string }): string {
-  const skillPath = getSkillPath(ctx);
-  const reqFile = join(skillPath, "requirements.txt");
+function checkAndInstallDeps(ctx: { directory: string }): string {
+  const corePath = getCorePath(ctx);
+  const reqFile = join(corePath, "..", "requirements.txt");
   if (existsSync(reqFile)) {
-    return `pip install -q -r "${reqFile}" 2>/dev/null; `;
+    return `pip install -q -r "${reqFile}" 2>/dev/null || pip install -q requests beautifulsoup4 playwright 2>/dev/null; `;
   }
   return "";
 }
 
+async function execPython(ctx: { directory: string }, script: string, timeout = 60): Promise<string> {
+  const corePath = getCorePath(ctx);
+  const deps = checkAndInstallDeps(ctx);
+  
+  try {
+    const result = await ctx.$`${deps}timeout ${timeout} python3 -c ${script}`;
+    return result.toString();
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    if (errorMessage.includes("timeout")) {
+      return `错误: 执行超时 (${timeout}秒)。目标可能无响应或需要更长时间。`;
+    }
+    if (errorMessage.includes("ModuleNotFoundError")) {
+      return `错误: 缺少 Python 依赖模块。请运行: pip install -r requirements.txt`;
+    }
+    return `错误: ${errorMessage}`;
+  }
+}
+
 const CYBER_SUPERVISOR_PROMPT = `你是 API 安全测试的**赛博监工**，代号"P9"。
 
 ## 职责
@@ -54,7 +69,29 @@ const CYBER_SUPERVISOR_PROMPT = `你是 API 安全测试的**赛博监工**，
 | vuln_verify | 漏洞验证 |
 | sqli_test | SQL注入测试 |
 | idor_test | IDOR测试 |
-| auth_test | 认证测试`;
+| auth_test | 认证测试
+
+## 工作流程
+
+1. 使用 browser_collect 采集端点
+2. 使用 js_parse 分析 JS 文件
+3. 使用 api_security_scan 进行全面扫描
+4. 使用特定工具进行针对性测试
+
+## 输出格式
+
+\`\`\`markdown
+## 安全测试报告
+
+### 目标
+- URL: {target}
+
+### 发现漏洞
+| 类型 | 端点 | 严重程度 |
+|------|------|---------|
+| SQL注入 | /api/user?id=1 | HIGH |
+\`\`\`
+`;
 
 const PROBING_MINER_PROMPT = `你是**API漏洞挖掘专家**，专注于发现和验证安全漏洞。
 
@@ -97,7 +134,16 @@ const RESOURCE_SPECIALIST_PROMPT = `你是**API资源探测专家**，专注于
 使用 js_parse 解析 JS 文件
 
 ### 3. 目录探测
-常见路径: /api/v1/*, /graphql, /swagger, /.well-known/*`;
+常见路径: /api/v1/*, /graphql, /swagger, /.well-known/*
+
+## 端点分类
+
+| 风险 | 类型 | 示例 |
+|------|------|------|
+| 高 | 认证 | /login, /oauth/* |
+| 高 | 数据 | /api/*/list |
+| 中 | 用户 | /users, /profile |
+| 极高 | 管理 | /admin, /manage`;
 
 const VULN_VERIFIER_PROMPT = `你是**漏洞验证专家**，专注于验证和确认安全漏洞。
 
@@ -105,10 +151,18 @@ const VULN_VERIFIER_PROMPT = `你是**漏洞验证专家**，专注于验证和
 
 1. **快速验证** - 确认漏洞是否存在
 2. **风险评估** - 判断实际影响
-3. **PoC 生成** - 提供可执行的证明`;
+3. **PoC 生成** - 提供可执行的证明
+
+## 验证流程
+
+1. 构造 payload
+2. 发送测试请求
+3. 分析响应
+4. 判断结果
+5. 生成 PoC`;
 
 const ApiSecurityTestingPlugin: Plugin = async (ctx) => {
-  console.log("[api-security-testing] Plugin loaded");
+  console.log("[api-security-testing] Plugin loaded, version: 3.0.2");
 
   return {
     tool: {
@@ -119,18 +173,15 @@ const ApiSecurityTestingPlugin: Plugin = async (ctx) => {
           scan_type: tool.schema.enum(["full", "quick", "targeted"]).optional(),
         },
         async execute(args, ctx) {
-          const deps = checkDeps(ctx);
-          const corePath = getCorePath(ctx);
-          const cmd = `${deps}python3 -c "
+          const script = `
 import sys
-sys.path.insert(0, '${corePath}')
+sys.path.insert(0, '${getCorePath(ctx)}')
 from deep_api_tester_v55 import DeepAPITesterV55
 tester = DeepAPITesterV55(target='${args.target}', headless=True)
 results = tester.run_test()
 print(results)
-"`;
-          const result = await ctx.$`${cmd}`;
-          return result.toString();
+`;
+          return await execPython(ctx, script, 120);
         },
       }),
 
@@ -141,18 +192,15 @@ print(results)
           method: tool.schema.enum(["GET", "POST", "PUT", "DELETE", "PATCH"]).optional(),
         },
         async execute(args, ctx) {
-          const deps = checkDeps(ctx);
-          const corePath = getCorePath(ctx);
-          const cmd = `${deps}python3 -c "
+          const script = `
 import sys
-sys.path.insert(0, '${corePath}')
+sys.path.insert(0, '${getCorePath(ctx)}')
 from api_fuzzer import APIFuzzer
 fuzzer = APIFuzzer('${args.endpoint}')
 results = fuzzer.fuzz(method='${args.method || 'GET'}')
 print(results)
-"`;
-          const result = await ctx.$`${cmd}`;
-          return result.toString();
+`;
+          return await execPython(ctx, script, 60);
         },
       }),
 
@@ -163,18 +211,15 @@ print(results)
           endpoint: tool.schema.string(),
         },
         async execute(args, ctx) {
-          const deps = checkDeps(ctx);
-          const corePath = getCorePath(ctx);
-          const cmd = `${deps}python3 -c "
+          const script = `
 import sys
-sys.path.insert(0, '${corePath}')
+sys.path.insert(0, '${getCorePath(ctx)}')
 from verifiers.vuln_verifier import VulnVerifier
 verifier = VulnVerifier()
 result = verifier.verify('${args.vuln_type}', '${args.endpoint}')
 print(result)
-"`;
-          const result = await ctx.$`${cmd}`;
-          return result.toString();
+`;
+          return await execPython(ctx, script, 30);
         },
       }),
 
@@ -184,20 +229,17 @@ print(result)
           url: tool.schema.string(),
         },
         async execute(args, ctx) {
-          const deps = checkDeps(ctx);
-          const corePath = getCorePath(ctx);
-          const cmd = `${deps}python3 -c "
+          const script = `
 import sys
-sys.path.insert(0, '${corePath}')
+sys.path.insert(0, '${getCorePath(ctx)}')
 from collectors.browser_collect import BrowserCollector
 collector = BrowserCollector(headless=True)
 endpoints = collector.collect('${args.url}')
 print(f'发现 {len(endpoints)} 个端点:')
 for ep in endpoints:
     print(ep)
-"`;
-          const result = await ctx.$`${cmd}`;
-          return result.toString();
+`;
+          return await execPython(ctx, script, 90);
         },
       }),
 
@@ -207,18 +249,15 @@ for ep in endpoints:
           file_path: tool.schema.string(),
         },
         async execute(args, ctx) {
-          const deps = checkDeps(ctx);
-          const corePath = getCorePath(ctx);
-          const cmd = `${deps}python3 -c "
+          const script = `
 import sys
-sys.path.insert(0, '${corePath}')
+sys.path.insert(0, '${getCorePath(ctx)}')
 from collectors.js_parser import JSParser
 parser = JSParser()
 endpoints = parser.parse_file('${args.file_path}')
 print(f'从 JS 发现 {len(endpoints)} 个端点')
-"`;
-          const result = await ctx.$`${cmd}`;
-          return result.toString();
+`;
+          return await execPython(ctx, script, 30);
         },
       }),
 
@@ -228,18 +267,15 @@ print(f'从 JS 发现 {len(endpoints)} 个端点')
           endpoint: tool.schema.string(),
         },
         async execute(args, ctx) {
-          const deps = checkDeps(ctx);
-          const corePath = getCorePath(ctx);
-          const cmd = `${deps}python3 -c "
+          const script = `
 import sys
-sys.path.insert(0, '${corePath}')
+sys.path.insert(0, '${getCorePath(ctx)}')
 from smart_analyzer import SmartAnalyzer
 analyzer = SmartAnalyzer()
 result = analyzer.graphql_test('${args.endpoint}')
 print(result)
-"`;
-          const result = await ctx.$`${cmd}`;
-          return result.toString();
+`;
+          return await execPython(ctx, script, 60);
         },
       }),
 
@@ -249,18 +285,15 @@ print(result)
           bucket_url: tool.schema.string(),
         },
         async execute(args, ctx) {
-          const deps = checkDeps(ctx);
-          const corePath = getCorePath(ctx);
-          const cmd = `${deps}python3 -c "
+          const script = `
 import sys
-sys.path.insert(0, '${corePath}')
+sys.path.insert(0, '${getCorePath(ctx)}')
 from cloud_storage_tester import CloudStorageTester
 tester = CloudStorageTester()
 result = tester.full_test('${args.bucket_url}')
 print(result)
-"`;
-          const result = await ctx.$`${cmd}`;
-          return result.toString();
+`;
+          return await execPython(ctx, script, 60);
         },
       }),
 
@@ -271,18 +304,15 @@ print(result)
           resource_id: tool.schema.string(),
         },
         async execute(args, ctx) {
-          const deps = checkDeps(ctx);
-          const corePath = getCorePath(ctx);
-          const cmd = `${deps}python3 -c "
+          const script = `
 import sys
-sys.path.insert(0, '${corePath}')
+sys.path.insert(0, '${getCorePath(ctx)}')
 from testers.idor_tester import IDORTester
 tester = IDORTester()
 result = tester.test('${args.endpoint}', '${args.resource_id}')
 print(result)
-"`;
-          const result = await ctx.$`${cmd}`;
-          return result.toString();
+`;
+          return await execPython(ctx, script, 30);
         },
       }),
 
@@ -293,18 +323,15 @@ print(result)
           param: tool.schema.string(),
         },
         async execute(args, ctx) {
-          const deps = checkDeps(ctx);
-          const corePath = getCorePath(ctx);
-          const cmd = `${deps}python3 -c "
+          const script = `
 import sys
-sys.path.insert(0, '${corePath}')
+sys.path.insert(0, '${getCorePath(ctx)}')
 from testers.sqli_tester import SQLiTester
 tester = SQLiTester()
 result = tester.test('${args.endpoint}', '${args.param}')
 print(result)
-"`;
-          const result = await ctx.$`${cmd}`;
-          return result.toString();
+`;
+          return await execPython(ctx, script, 30);
         },
       }),
 
@@ -314,18 +341,15 @@ print(result)
           endpoint: tool.schema.string(),
         },
         async execute(args, ctx) {
-          const deps = checkDeps(ctx);
-          const corePath = getCorePath(ctx);
-          const cmd = `${deps}python3 -c "
+          const script = `
 import sys
-sys.path.insert(0, '${corePath}')
+sys.path.insert(0, '${getCorePath(ctx)}')
 from testers.auth_tester import AuthTester
 tester = AuthTester()
 result = tester.test('${args.endpoint}')
 print(result)
-"`;
-          const result = await ctx.$`${cmd}`;
-          return result.toString();
+`;
+          return await execPython(ctx, script, 30);
         },
       }),
     },