VulnClaw 插件体系开发指南：从零写一个低耦合漏洞检测插件的完整教程

VulnClaw 插件体系开发指南从零写一个低耦合漏洞检测插件的完整教程【免费下载链接】VulnClaw基于 AI Agent MCP 工具链 渗透 Skill 编排 配合大语言模型 自然语言输入 → 自动完成「信息收集 → 漏洞发现 → 漏洞利用 → 报告生成」全流程。项目地址: https://gitcode.com/GitHub_Trending/vu/VulnClawVulnClaw 是一个基于 AI Agent MCP 工具链 渗透 Skill 编排的自动化渗透测试框架它的漏洞检测插件机制允许你把任意的检测逻辑封装成标准插件挂进「信息收集 → 漏洞发现 → 漏洞利用 → 报告生成」全流程。本指南带你从零写一个低耦合的漏洞检测插件插件只依赖 4 个核心抽象不碰网络、不碰全局状态写完即可被运行时托管执行并自动汇入报告。一、先认识 VulnClaw 插件体系的 5 个核心模块整个插件体系位于 vulnclaw/plugins/ 目录职责分工非常清晰模块文件职责基类与上下文base.py定义VulnPlugin抽象基类和PluginContext输入上下文插件注册表registry.py按plugin_id注册、查询、按阶段/标签筛选插件结果模型result.pyPluginFinding漏洞发现与PluginResult执行结果运行时runtime.py预检、超时、请求预算、目标范围校验统一托管执行结果桥接integration.py把插件发现转成 Agent 的漏洞发现去重后合并进报告链路内置的 3 个 Web 检测插件在 vulnclaw/plugins/web/ 下是最好的参考范例安全响应头检测web/headers.pyJWT 声明分析web/jwt.pyJavaScript 端点提取web/js_endpoints.py 设计思想插件是「纯函数式」的——输入PluginContext输出PluginResult所有网络访问、权限约束、超时控制全部由运行时负责这就是低耦合的来源。二、5 分钟上手查看内置漏洞检测插件先 clone 仓库并安装git clone https://gitcode.com/GitHub_Trending/vu/VulnClaw pip install -e .CLI 内置了插件子命令见 vulnclaw/cli/main.pyvulnclaw plugins list # 列出所有已注册的检测插件 vulnclaw plugins info builtin.web.jwt # 查看单个插件的完整元数据运行list会看到内置插件的 ID、版本、适用阶段与默认风险等级——这正是你稍后要写的插件将呈现的样子。三、从零写一个低耦合漏洞检测插件我们以「检测弱 API Key 命名」为例走一遍完整流程。第 1 步继承 VulnPlugin 基类基类定义在 base.py所有插件只需声明元数据 实现一个run方法from vulnclaw.plugins.base import PluginContext, VulnPlugin from vulnclaw.plugins.result import ( PluginFinding, PluginResult, PluginStage, RiskLevel, ) class WeakApiKeyPlugin(VulnPlugin): plugin_id community.web.weak_api_key name Weak API Key version 0.1.0 description Flag suspicious API key literals in supplied JavaScript. stages (PluginStage.RECON, PluginStage.DISCOVERY) default_risk RiskLevel.MEDIUM tags (api-key, js)关键点详见 base.pyplugin_id全局唯一注册表靠它索引registry.py建议用命名空间.类别.功能风格stages声明插件适用的阶段recon/discovery/verification/exploitation等 6 档见 result.py运行时会按阶段精准调度destructive默认为False非破坏性插件无需显式开启。第 2 步实现 run 方法只读 options、不碰网络输入统一来自PluginContextbase.pytarget是目标、options是数据入参、stage是当前阶段。参考内置 JWT 插件的写法web/jwt.pydef run(self, context: PluginContext) - PluginResult: content str(context.options.get(content) or ) if not content: return PluginResult( plugin_idself.plugin_id, stagecontext.stage, messages[No content was supplied.], ) # 纯本地分析逻辑正则、词表、启发式……低耦合三原则输入只从context.options取不自己发请求——数据由上游 Agent/流量模块提供缺失输入时优雅跳过返回带messages的正常结果而不是抛异常所有发现走结构化PluginFinding不打印、不写文件。第 3 步返回结构化 PluginResult 与 PluginFindingPluginFinding字段定义在 result.py一条合格的发现应包含title、risk、evidence证据、remediation修复建议和confidence0~1 置信度findings [ PluginFinding( titleSuspicious API key literal in JavaScript, riskRiskLevel.MEDIUM, targetcontext.target, vuln_typeweak_api_key, descriptionHard-coded key-like string detected., evidence{matches: hits}, remediationMove secrets to environment variables or a key service., confidence0.8, ) ] return PluginResult( plugin_idself.plugin_id, stagecontext.stage, findingsfindings, metadata{hit_count: len(hits)}, )出错时使用工厂方法PluginResult.error_result(...)result.py跳过场景用skipped_result(...)保持结果语义一致。第 4 步注册插件并交给运行时执行注册只需两行参考 plugins/__init__.py 的内置注册方式from vulnclaw.plugins import registry, PluginRuntime registry.register(WeakApiKeyPlugin, replaceTrue) runtime PluginRuntime(registry) result runtime.execute( community.web.weak_api_key, PluginContext( targethttps://example.com, stagePluginStage.DISCOVERY, options{content: js_source}, ), )四、运行时如何保证插件低耦合又安全PluginRuntimeruntime.py在执行每个插件前会做一整套预检见 runtime.py你写的插件完全不用操心这些目标范围校验allowed_targets/scope_targets之外的目标直接拦截防止越权扫描任务约束校验按 host / port / path 黑白名单与动作约束拦截违规操作runtime.py超时保护同步/异步run都会被asyncio.wait_for包裹超时自动转为timeout错误结果请求预算按request_cost扣减每个目标的请求额度耗尽即跳过异常兜底任何未捕获异常都会被收敛为error_result不会拖垮整个扫描任务。五、让插件结果进入报告桥接层说明插件输出如何变成报告里的漏洞条目答案在 integration.pyplugin_finding_to_vuln_finding将PluginFinding转为 Agent 的VulnerabilityFinding风险等级自动映射到严重度integration.py按finding_id去重后合并进会话状态integration.py随后进入报告生成链路。 所以你只要认真填好evidence和confidence置信度 ≥ 0.8 的发现会被标记为 L2 证据等级直接影响报告的说服力。六、自测给漏洞检测插件写一个单元测试参考 tests/plugins/test_builtin_plugins.py 的写法测试极其简单——直接构造上下文、断言结果from vulnclaw.plugins import PluginContext, PluginStage from my_plugin import WeakApiKeyPlugin def test_flags_hardcoded_key(): result WeakApiKeyPlugin().run( PluginContext( targethttps://example.com, stagePluginStage.DISCOVERY, options{content: const k sk-live-abcdef123456;}, ) ) assert result.ok and result.findings完整测试集可参考 tests/plugins/ 目录下的注册表、运行时、内置插件三类用例。七、优质插件的 4 个检查清单 ✅#检查项反例1输入只来自context.options插件内requests.get()直接发请求2无输入时返回友好messages直接抛KeyError3发现带evidenceremediationconfidence只给标题不给证据4plugin_id带命名空间前缀、stages精确声明所有插件都声明 6 个阶段写在最后VulnClaw 的插件体系把「检测逻辑」与「执行环境」彻底解耦你只需专注写检测算法注册表负责发现运行时负责安全托管桥接层负责汇入报告。下一步建议精读内置插件 web/headers.py 与 web/js_endpoints.py它们分别展示了「静态规则检测」与「正则提取」两种典型插件形态照着改就是你第一个可发布的生产级漏洞检测插件。【免费下载链接】VulnClaw基于 AI Agent MCP 工具链 渗透 Skill 编排 配合大语言模型 自然语言输入 → 自动完成「信息收集 → 漏洞发现 → 漏洞利用 → 报告生成」全流程。项目地址: https://gitcode.com/GitHub_Trending/vu/VulnClaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考