CyberStrikeAI 插件开发指南：从 Burp 扩展到 Chromium DevTools 插件的完整实践

本篇技术指南以 CyberStrikeAI 仓库中的插件开发文档 docs/en-US/plugin-development.md 为骨架，系统讲解该项目的插件生态：插件在 plugins/ 目录下的组织结构、API 插件 / MCP 插件 / 资源包三种分层模型、仓库自带的两套参考实现（Burp Suite 扩展与 Chromium DevTools 扩展）的构建、加载与核心实现原理，以及 API 集成、MCP Schema 设计与安全边界的最佳实践。读完本文，你将掌握如何为 CyberStrikeAI 开发一个安全、可维护、与平台控制面（认证、HITL、授权边界）对齐的第三方集成。

插件生态概览与仓库布局

CyberStrikeAI 将插件定位为"可选的集成层"——把平台与外部工具连接起来（见 plugins/README.md）。仓库自带两套参考实现，覆盖了"桌面代理工具（Burp）"与"浏览器调试工具（Chromium DevTools）"两类典型场景：

plugins/
  README.md
  burp-suite/cyberstrikeai-burp-extension/
  browser-extension/cyberstrikeai-browser-extension/

集成方式通常有三类：HTTP API（直接调用平台接口）、MCP 服务器（把能力以工具形式暴露给 Agent 主动调用）、资源包（携带 tools、roles、Skills、agents 等声明式资源）。

插件分层模型：API 插件 / MCP 插件 / 资源包

原文档给出了清晰的分层决策表，这是选择集成形态的第一步：

分层	示例	收益	代价
API 插件	Burp / 浏览器扩展调用 Agent 流式接口	简单、专注 UI 集成	依赖 API 与认证
MCP 插件	向 Agent 暴露工具	Agent 可以直接调用该能力	需要设计 schema 与安全边界
资源包	携带 tools / roles / skills / agents	简单、可版本化管理	交互性较弱

原文档给出的决策原则值得强调：不要一上来就做 MCP。只有当 Agent 必须主动调用你的能力时才需要 MCP；如果需求只是"把这一个 HTTP 请求发给 AI"，一个 API 插件就足够了。这一判断直接关系到开发成本、schema 维护负担与攻击面大小。

Burp Suite 扩展：从 HTTP 到 AI 流式渗透测试

Java 扩展位于 plugins/burp-suite/cyberstrikeai-burp-extension/，源码在 src/main/java/burp/ 下，包含 BurpExtender.java、CyberStrikeAIClient.java、CyberStrikeAITab.java、HttpMessageFormatter.java、MarkdownRenderer.java、SendOptionsDialog.java、SimpleJson.java、SslTrustAll.java 等类。典型工作流是：

从 Burp 读取 HTTP 消息 → 格式化为 prompt → 调用 CyberStrikeAI 的 SSE 接口 → 在 Burp Tab 中展示 Progress / Final。

核心能力

• 配置 Host / Port / HTTPS / Password 并选择 Agent 模式；
• 点击 Validate 完成登录（POST /api/auth/login）与 Token 校验（GET /api/auth/validate）；
• 在 Burp 中右键任意 HTTP 消息发送到 CyberStrikeAI，进行流式 Web 渗透测试，Agent 模式包括 Eino Single、Deep、Plan-Execute、Supervisor，分别映射到 /api/eino-agent/stream 或 /api/multi-agent/stream；
• 保留可搜索的测试历史侧边栏，便于回看之前的 run；
• 输出区拆分为可折叠的 Progress 与 Final Response（支持 Markdown 渲染）；
• 可查看每次 run 捕获的 Request / Response 原文；
• Stop 中止正在运行的任务（拿到 conversationId 后调用 /api/agent-loop/cancel）。

构建方式

需要 JDK 11+，Maven 为推荐方式（无需定位 Burp 安装目录）：

cd plugins/burp-suite/cyberstrikeai-burp-extension
./build-mvn.sh
# 输出：dist/cyberstrikeai-burp-extension.jar

离线方式则需要先拿到 Burp Extender API jar：

mkdir -p lib
# 从 Burp 安装目录复制，例如：
# cp "/path/to/burp-extender-api.jar" lib/
./build.sh

仓库同时提供 build.gradle（Gradle 可选构建路径）。构建产物通过 Burp Suite → Extensions → Installed → Add，类型选择 Java 加载。

连接与认证细节

• 默认连接为 https://127.0.0.1:8080（HTTPS 默认勾选），自签名/本地证书被自动信任，无需手动导入；
• 仅当服务端运行纯 HTTP 时才取消勾选 HTTPS；
• 认证使用由配置密码换取得到的 Bearer Token。

Chromium DevTools 浏览器扩展：捕获 Network 流量并发送给 AI

MV3 DevTools 扩展位于 plugins/browser-extension/cyberstrikeai-browser-extension/，与 Burp 插件对齐：捕获 Network 流量 → 生成 HTTP/1.1 prompt → SSE 输出。当前版本 0.3.10，完整文档见该目录下 README.md 与 README.zh-CN.md。

安装与加载

# 1. chrome://extensions/ → 开发者模式 → 加载已解压的扩展程序
# 2. 选择目录：plugins/browser-extension/cyberstrikeai-browser-extension/
# 3. 打开目标页面 → F12 → CyberStrikeAI Tab → 填写 Host/Port/Password → Validate
# 4. 选中捕获请求 → Send → 在 Output 查看 AI 结果

打包发布：

bash plugins/browser-extension/cyberstrikeai-browser-extension/package.sh
# → dist/cyberstrikeai-browser-extension.zip

图标从项目根 images/logo.png 生成（sips 缩放为 16/48/128）。注意：扩展重载后必须完全关闭 DevTools 再重新打开 F12，否则旧面板上下文失效，会报 chrome.runtime.connect 错误。

manifest.json 展示了 MV3 的关键声明：devtools_page 指向 devtools.html，optional_host_permissions 声明 http://*/* 与 https://*/*（按需授权），后台使用 background/service-worker.js，弹窗为 popup/popup.html，权限仅申请 storage。

界面分工

位置	用途
DevTools 面板	连接、Validate、捕获、Send、Output（主工作区）
扩展 Popup	只读连接状态 + 版本号 + 打开 DevTools 引导

浏览器端认证最佳实践

服务端 POST /api/auth/login 返回 { token, expires_at }，没有 refresh token——不能假设会自动续期。浏览器扩展的认证设计要点（参考 lib/auth-session.js、lib/api.js、panel/panel.js）：

实践	说明
Session 存储	Token 与 expires_at 存放在 chrome.storage.session，绝不持久化密码
剩余时间提示	显示 OK · 11h 30m left；剩余不足 30 分钟时告警
本地检查	每 30s 复查 expires_at 并调用 GET /api/auth/validate
服务端探测	DevTools 面板变为可见时立即探测
服务不可达	显示警告；瞬时故障期间保留 Token
401/403	清空 Token（服务端重启会清空内存会话）
发送前	SSE 之前调用 ensureAuthReady()
权限	使用 optional_host_permissions——在 Validate 时按需请求服务 origin

权限申请直接绑定 Validate 点击事件，仅申请当前填写的 CyberStrikeAI 服务 origin，已授权地址不会重复弹窗；服务器识别格式合法的 Chrome/Edge 扩展 Origin，因此无需复制扩展 ID 或配置 CORS 白名单。

数据与性能设计（不无限增长）

• 捕获上限：200 条/ Tab、20 个 Tab、Progress 512KB/run；
• 默认仅捕获 XHR/Fetch，不捕获时使用暂停开关（● Capturing / ○ Paused）；
• 静态资源 URL/MIME 预过滤，命中前不读取响应体；请求体单条截断 64KB、响应 4KB；
• 发送给 Agent 前对大体积 body 进行截断或摘要；
• 流式阶段 Final 以纯文本呈现，结束后经 requestIdleCallback 渲染 Markdown，超过 100KB 降级纯文本；
• 关闭 DevTools 即清空面板内存；关闭浏览器即令 Session Token 失效。

性能表现：未开 DevTools 时零影响；捕获暂停时近零开销；仅捕获 XHR/Fetch 时只对匹配请求有轻微开销。已实现的优化包括过滤器内存缓存、列表增量插入、搜索防抖、rAF 节流流式 UI（lib/ 下的 capture.js、http-normalize.js、formatter.js 等负责 HAR 摘要、HTTP/2 → HTTP/1.1 归一化与 prompt 组装）。

与 Burp 插件的对比

能力	Burp 插件	浏览器扩展
流量来源	Proxy 历史	DevTools Network
连接配置	Tab 内	Tab 内（可折叠）
HTTP 格式	HTTP/1.1	展示/Prompt 归一化为 HTTP/1.1
项目/角色/模式	Send 弹窗	Send 弹窗
SSE 输出	Progress + Final	Progress + Final
捕获开关	—	● 捕获中 / ○ 已暂停

API 集成：认证、SSE 与大文件

API 集成的核心流程（OpenAPI 规格见 internal/handler/openapi.go）：

1. 登录：POST /api/auth/login，携带密码换取 { token, expires_at }（internal/handler/openapi.go 中 LoginResponse 的 expires_at 为 date-time 格式）；随后用 GET /api/auth/validate 校验 Token，响应同样包含 token 与 expires_at。
2. Token 生命周期：持久化 expires_at，过期后重新登录——没有静默续期机制。
3. 流式对话：优先使用 POST /api/eino-agent/stream（Eino ADK 单代理）或 POST /api/multi-agent/stream（Eino 多代理），均为 SSE（text/event-stream）。请求体最少只需 message，可选 conversationId、role、webshellConnectionId、finalization；多代理接口额外支持 orchestration 枚举 deep | plan_execute | supervisor（缺省 deep）。
4. 重要语义：response_start / response_delta 仅为候选/过程输出；只有 type: response 且 data.finalized=true 才表示成功最终回复。/api/multi-agent/stream 依赖 multi_agent.enabled: true，未启用时 SSE 内首条为 type: error 后接 done。
5. 大文件：通过 /api/chat-uploads 上传，然后在消息中引用，而不是把大响应整段粘贴进 prompt。
6. 完整规格：/api-docs 或 /api/openapi/spec。

API 插件 Payload 设计

发送给 Agent 的 prompt 应包含以下要素，缺一不可：

• 来源工具与上下文（流量来自哪个工具、什么场景）；
• 目标 URL、方法、关键请求头；
• 请求/响应体的截断策略；
• 用户意图（希望 Agent 做什么）；
• 授权边界（明确哪些目标是授权的，Agent 不得越界）。

大响应应该上传或摘要后再送入 prompt，而不是原样粘贴。

MCP Schema 设计：具体化才能安全

若选择 MCP 集成（服务端侧可参考 internal/handler/external_mcp.go 与 internal/mcp 相关实现），Schema 设计直接决定 HITL（人在回路）与 Agent 行为的可控性。

反面示例——语义空洞，Agent 可以随意传任意字符串：

{"cmd":{"type":"string"}}

推荐示例——类型、描述、枚举、上限都明确：

{
  "target_url": {"type":"string","description":"authorized target URL"},
  "scan_profile": {"type":"string","enum":["passive","active-safe"]},
  "max_requests": {"type":"integer","description":"request limit"}
}

具体的 schema 让 HITL 审批有依据、Agent 行为有约束、错误调用可被尽早拦截。

安全边界：插件不得绕过平台控制

插件开发必须遵守以下安全边界：

• 不隐藏破坏性的本地命令；
• 不存明文长期凭证：密码仅用于登录换取 Token，Token 放 session 存储；
• 默认不向第三方外传数据；
• 不依赖浏览器状态绕过登录；
• 401/403 时清空会话并要求重新认证，不静默重试。

源码锚点：继续深入的最佳路径

• Burp 插件源码：plugins/burp-suite/cyberstrikeai-burp-extension/src/main/java/burp/
• 浏览器扩展源码：plugins/browser-extension/cyberstrikeai-browser-extension/
  • 认证：lib/auth-session.js、lib/api.js、lib/storage.js
  • UI：panel/panel.js
  • 捕获：devtools.js、background/service-worker.js
• OpenAPI 规格：internal/handler/openapi.go
• 外部 MCP 接入：internal/handler/external_mcp.go
• Web 端认证参考：web/static/js/auth.js

小结

CyberStrikeAI 的插件体系围绕"平台控制面不可绕过"这一原则展开：API 插件专注 UI 集成、MCP 插件强调 schema 严谨、资源包强调可版本化，而认证（无 refresh token 的显式生命周期管理）、SSE 的 finalized 语义、payload 的授权边界声明则是所有插件共通的地基。无论是参考 Burp 扩展做桌面工具集成，还是参考浏览器扩展做浏览器侧流量接入，都可以在原文档与上述源码锚点的指引下，快速产出安全且可维护的插件。