@lnng/dsh-ai-pentest-pathfinder
v0.9.2
Published
AI Pentest Pathfinder (探径): testing tasks, decision graphs, methods and searchable security references
Readme
探径 · AI Pentest Pathfinder
面向 DeepSeek Harness 的安全测试规划与知识管理插件。
English · 发布版本:0.9.2
探径把安全测试任务、决策图、共享测试方法和参考资料放在同一个工作区。你可以在页面中整理测试范围、路径、证据和进展,也可以让 AI 按需查询资料、创建任务、修改任务图、记录战术,以及在人工授权后维护共享库。适合需要持续整理思路与过程的授权安全评估、渗透测试和攻防演练。
探径本身不执行安全测试、扫描、PoC 或脚本,也不自动访问工具平台地址、判定漏洞或宣布任务完成。 图中的步骤、资料中的规则和黑板中的代码都是供用户与 AI 阅读的内容;实际执行能力由你另外选择的工具提供。
与 Harness 的关系
探径通过 Harness 的插件接口提供页面、数据存储和 14 个 AI 工具。AI 根据任务需要自行调用这些工具;探径不侵入或改写 Harness 的上下文组装、压缩、循环、调度和执行机制,不把整套知识库自动注入每轮上下文。
可以搭配 Harness 官方团队能力,让多个会话围绕同一任务协作;探径不依赖团队插件,单个用户或单个 AI 会话也能使用。它也不会自动分配成员、启动代理或调度测试。
基线 Skill(0.9.2)
插件通过 Harness 官方 Skills 服务提供 pentest-pathfinder-baseline。在用户消息中写 /pentest-pathfinder-baseline 可明确启用,AI 也可从技能目录按需加载。技能讲解决策图、方法库、PoC、Web/服务指纹及工具平台的搜索与原文读取;通过现有黑板保存基线覆盖,并用反证、对照和执行证据修正判断。无需新增数据库或咨询/调度系统。
目录包含简短名称与描述,完整说明由官方机制按需进入会话;不是零上下文开销。探径不注册自己的系统提示 section、不主动推送图或黑板、不修改压缩/循环/调度。缺少官方 Skills 服务时原有页面与14个工具仍可用。Skill 提供工作方法,不保证模型一定调用或执行绝不遗漏。
指定 node_id 的读取只返回当前正文与相邻分支,nodeIndex 标明被省略的目录及概览读取参数;不指定节点或明确 include_graph=true 时保留目录。方法概览新增有效入口ID与依据:declared 是资料声明,candidates 仅是无入边候选,unknown 不猜入口。
兼容要求
| 项目 | 要求 |
| --- | --- |
| DeepSeek Harness | >=0.2.1-rc.5 <0.3.0-0 |
| 当前开发与测试基准 | 0.2.2-rc.1 |
| 已验证宿主版本 | 0.2.1-rc.5、0.2.2-rc.1 |
| 从源码构建 | Node.js >=24、pnpm |
宿主提供工具与通信 SDK,插件通过 peer dependencies 声明兼容范围。范围内后续版本仍可能改变接口;0.3.x(包括预发布版本)需要重新验收。版本范围不是对未来版本的无条件兼容保证。
安装本地 release 目录
- 获取发布包并解压,把
release/dsh-ai-pentest-pathfinder-0.9.2目录放在准备长期保留的位置。该运行发布包包含预构建 Client、Host、默认资料、中英文 README 和第三方声明,无需安装开发依赖或重新构建。 - 打开 Harness 的插件管理器,以该目录的绝对路径安装本地插件包。路径应指向包含
package.json与cordis.patch.yml的目录。 - 按管理器返回的应用状态和后续操作提示完成启用、刷新或重启。
- 在 Harness 原生侧栏打开“探径”,确认可以进入五个页面。
也可以把安装工作交给当前 Harness AI,例如:
请通过 Harness 插件管理器安装我提供的本地 release 目录。先确认目录中的包信息,再使用该目录的绝对路径安装,并根据返回的应用状态和 nextStep 完成必要操作。
AI 使用 Harness 提供的 plugin_manager,安装操作为 action=install_bundle,target 为实际发布目录的绝对路径。这里不需要额外的探径安装 CLI。
本地目录安装会关联该目录;安装后移动或删除它可能导致插件无法加载。普通用户使用发布产物即可,无需重新构建前端。仅看到相同的侧栏入口不足以确认更新成功,还应核对插件管理器中的版本和应用状态。
五个页面
从侧栏“探径”进入后,页面依次为:
| 页面 | 可以做什么 | | --- | --- | | 测试任务 | 从模板创建任务,填写对象、重点、范围、最终目标和状态,编辑独立任务图、按目标维护防护信息,并使用自由战术黑板。 | | 决策图库 | 查看、创建和编辑场景模板,维护节点、条件、分支与方法引用,导入或导出场景包。 | | 测试方法库 | 搜索和维护共享方法,编辑正文、示例和方法图;方法图以“整理完成”收束。 | | 工具库 | 搜索和维护漏洞 / PoC、Web 指纹、端口服务指纹与工具平台资料,读取完整原文,导入和导出资料。 | | AI 查询记录 | 查看 AI 查询与成功修改的系统记录,按任务筛选,检查参数、结果与回执,并导出 JSON。 |
图支持拖动节点、连接分支、编辑条件和局部 / 全图查看。普通滚轮滚动页面,Ctrl / ⌘+滚轮或画布按钮缩放,拖动画布空白处平移。保存失败和版本冲突会显示提示;遇到冲突应保留草稿,读取新内容后比较合并。
从一个任务开始
- 在“决策图库”选择合适的模板,或让 AI 先搜索模板并按需读取节点。
- 创建任务,明确测试对象、授权范围、重点和最终目标。例如使用
https://app.example.test作为示例目标。 - 根据当前证据调整任务图,阅读节点引用的方法;把自由发现、多步交互和证据线索写入黑板。
- 在工具库按关键词查找指纹、平台资料或自行导入的 PoC。按需读取原文,再由用户或 AI 判断如何使用。
- 按实际进展更新状态,并通过查询记录和导出文件复核过程。
你也可以直接对 AI 说:
为示例测试环境创建一个任务,先查找合适的场景模板。范围仅限我提供的测试环境,重点是访问控制,目标是形成可复核的问题与证据清单。先整理规划,不执行测试。把后续发现保存在任务黑板中。
任务独立图与共享方法
创建任务时,所选模板的图会完整复制成任务独立图。以后修改模板只影响模板及后续创建的任务;修改某个任务图也只影响该任务。
方法通过稳定 ID 共享引用。修改共享方法后,已有模板和任务的引用会读到更新后的方法内容。因此,“任务图独立”不代表方法内容被冻结。维护方法前应检查引用影响。
任务最终目标由任务信息统一维护,任务摘要、最终目标节点和 AI 读取保持一致。按目标记录的防护信息包括类型、适用范围、判断状态、产品、证据和确认时间;“当前未观察到”仅描述当时的观察结果,不等于不存在防护。
自由战术黑板
任务详情提供“决策图 / 战术黑板”切换。黑板条目包含标题、自由类型、自由状态、正文与关联节点,可从节点建立条目,也可独立新增。
黑板适合保存发现、前置条件、可利用原语、候选分支、多步交互、变量传递、脚本片段和证据。正文按普通文本保存和展示,代码不会被执行。节点关联可以保留已删除或尚未创建的节点 ID。
黑板与图分别维护,使用独立的 blackboard.revision。AI 先读摘要,再按条目分段读取正文;无需把整块黑板反复加载进上下文。页面会保留冲突时的草稿,刷新或关闭前仍应主动保存。
0.9.2 默认内容
本版本默认内容来自整理后的 out 导出包:
| 分类 | 默认内容 | | --- | --- | | 决策图库 | 渗透测试:59 个节点、176 条连线;攻防演练:40 个节点、103 条连线 | | 测试方法库 | 83 个方法,保留其图、正文和示例 | | 指纹库 | 共 6,732 条:Web 6,391 条、端口服务 341 条 | | 工具平台 | 1 条平台资料 | | 漏洞 / PoC | 0 条,默认空库;保留新增、编辑、搜索、读取与导入导出功能,可自行导入 |
默认库用于新建数据存储。普通启动和升级不会用默认场景或方法覆盖现有用户库。 工具库中用户新增、修改及删除的结果通过本地数据保留;未修改的随包条目可能随发布资料更新。需要采用新的默认内容时,先备份,再通过页面预览并导入,核对实际合并结果。
条目数量以实际发布包和页面显示为准。资料用于辅助查阅,不代表插件已经验证其中的每个规则或结论。
14 个 AI 工具
工具名称均以 pentest_pathfinder_ 开头。以下为完整清单。
查找与只读资料(6 个)
| 工具 | 用途 |
| --- | --- |
| pentest_pathfinder_find | 按 task / scene / method 查找任务、模板或方法,返回稳定 ID 与版本。 |
| pentest_pathfinder_read_task | 读取任务、防护记录、版本、节点和分支;按需获取完整任务图。 |
| pentest_pathfinder_read_scene | 读取模板概览、节点、引用与分支;按需获取完整图。 |
| pentest_pathfinder_read_method | 读取方法原文、图和引用影响。 |
| pentest_pathfinder_search_resources | 搜索 PoC、指纹与平台资料,返回摘要、来源、命中位置和分页。 |
| pentest_pathfinder_read_resource | 分段读取资料原文,用哈希检查续读时内容是否变化。 |
任务与任务图写入(3 个)
| 工具 | 用途 |
| --- | --- |
| pentest_pathfinder_create_task | 从所选模板复制独立任务,保存目标、范围、状态等信息。 |
| pentest_pathfinder_update_task | 局部修改任务信息、最终目标、状态与防护记录。 |
| pentest_pathfinder_patch_task_graph | 批量增删改任务节点、连线、条件、正文及现有方法引用。 |
任务黑板(2 个)
| 工具 | 用途 |
| --- | --- |
| pentest_pathfinder_read_blackboard | 读取条目摘要与独立版本,或分段读取指定条目正文。 |
| pentest_pathfinder_patch_blackboard | 原子批量新增、修改或删除任务内黑板条目。 |
人工授权的共享库维护(3 个)
| 工具 | 用途 |
| --- | --- |
| pentest_pathfinder_library_status | 查看当前 profile 的 AI 库维护锁状态。 |
| pentest_pathfinder_library_history | 分页读取维护历史、修改前快照与回执。 |
| pentest_pathfinder_maintain_library | 人工解锁后创建、修改、删除或恢复模板、方法及工具资料。 |
通常先 find,再按 ID 读取,最后提交修改。任务写入使用最近读取的 task.revision;黑板写入使用 blackboard.revision。图与黑板批量操作每批 1–100 项,任一项失败整批不提交。
写入使用唯一 request_id。相同请求重试应复用原标识与全部参数;发生 CONFLICT 时重新读取、合并并使用新标识。重放回执可能不是当前状态,继续修改前应再读取。防护记录是整体替换列表,修改前需保留其他条目。
AI 工具不提供删除整个任务、修改已有查询记录或库导入导出的入口。导入导出通过页面操作。
人工维护锁与维护历史
AI 共享库维护默认加锁。用户在页面顶部亲自解锁后,AI 才能维护决策图库、共享方法和工具库;AI 无法调用工具解锁。该权限作用于当前 profile 的全部 AI 会话,插件重载或进程重启后恢复加锁。
锁定不妨碍手工编辑,也不妨碍 AI 修改任务和任务黑板。共享方法的修改会影响已有引用;仍被引用的方法不能由 AI 直接删除。
维护历史保留修改前原文与回执,可供核对和恢复。恢复需要当前版本仍与该历史匹配;后续已有编辑时拒绝覆盖,应先比较合并。人工可在锁定时恢复,AI 恢复仍需解锁。历史与记录不自动清理,会随使用增长。
这个锁约束探径的 AI 工具与业务入口。Harness 中通用文件工具的主机写入权限属于另外的授权边界。
导入、导出与记录
| 内容 | 入口与行为 |
| --- | --- |
| 场景与方法 | 各自页面可导出当前或全部条目;场景包同时包含引用的方法。导入先校验预览,再确认追加;同内容复用,不同内容的 ID 冲突生成副本。方法库也能从场景包提取方法。 |
| 工具库 | 可导入插件 JSON 备份,或把 YAML、JSON、文本文件各自作为原文资料导入。默认 merge 按 ID 更新,也可 copy 生成新 ID。先预览再确认;同名不会自动合并。 |
| 工具库导出 | 可选全部、当前搜索与分类筛选结果或单条 JSON;单条也能导出原始正文。筛选导出覆盖全部匹配项,不限当前页。 |
| AI 查询记录 | 可导出当前任务筛选、全部记录或选中单条 JSON,包含已经保存的参数、返回结果、摘要与回执。筛选 / 全部导出覆盖尚未加载的记录。 |
场景 / 方法包、工具库备份与记录导出使用不同格式,不能互相替代。场景 / 方法包不包含任务独立图、黑板和查询记录;记录导出也不是可恢复的全量业务备份。
查询与成功修改的记录由系统追加,AI 不能修改或删除已有记录。工具库与黑板记录按设计省略部分正文,导出只包含实际保存的字段,不会补出省略内容。页面浏览工具资料不会产生 AI 查询记录。
工具资料正文按原文保存,不验证具体规则语法,也不执行内容。单条正文最多 4,194,304 个 UTF-16 代码单元;工具库单次导入最多 100,000 条,所选文件合计与序列化导入包分别不超过 128 MiB。无效批次和持久化失败不会部分导入。
数据、隐私与备份
数据默认保存在当前 Harness profile 的相对位置 data/pentest-pathfinder/;如配置 dataRoot,则以配置目录为准:
state.json:任务、任务图、黑板、场景、方法、记录与维护历史等业务数据。resource-data.json:用户工具资料、随包资料的本地覆盖和删除标记等。- 旧安装可能保留
tool-platforms.json,升级备份时应一并保留整个目录。
探径自身不提供云同步,也不自动上传资料。AI 调用工具时,返回内容会进入 Harness 会话,并可能由 Harness 发送给你配置的模型服务;数据的后续处理取决于 Harness、模型提供方和其他工具的设置。
目标、账号线索、请求响应、证据与脚本可能包含敏感信息。查询记录和维护快照可能保留相关内容,导出包也可能包含这些字段。公开分享前自行检查和脱敏,并按需求保护本地数据目录及备份。
更新与恢复
- 保存页面草稿,记录当前插件版本;停用插件或停止相关 Harness 进程,避免备份期间并发写入。
- 备份整个
data/pentest-pathfinder/(或实际dataRoot)及原发布目录。页面 JSON 导出可作补充,不能替代完整目录备份。 - 获取新 release 目录,通过 Harness 插件管理器安装更新,根据返回提示刷新或重启。
- 检查版本、五个页面、已有任务、库和资料。默认更新不会重置已有用户库。
需要回退时,先停用插件,保留当前数据副本,再配套恢复先前发布目录与更新前数据备份。旧版本不一定能读取新版本写出的数据;不要直接覆盖正在运行的存储文件。
从源码构建与测试
以下命令仅适用于完整开发源码仓库,在其根目录运行。运行 release 不附开发回归脚本,解压后直接交给 Harness 插件管理器安装,无需执行这些命令:
pnpm install --frozen-lockfile --ignore-scripts
pnpm run build
pnpm testbuild 生成自包含 Client 发布产物并处理样式和第三方声明;React 与 ReactDOM 由 Harness 提供。插件页面挂载在 Harness 内,无需单独启动 Web 服务。
pnpm run build:check 可单独检查生成产物是否与源码一致。pnpm test 覆盖构建、语法、默认数据、资源管理、宿主注册、任务和黑板、权限与持久化、维护历史、Client 行为及工具 / RPC 契约等回归。测试使用独立临时数据,浏览器中的主题、布局和交互仍需单独验收。具体检查项以当前源码脚本为准;这份说明不替代该发布版本的实际测试结果。
第三方资料与许可说明
界面使用 React Flow / xyflow 及相关依赖,具体版本、许可文本和随包第三方声明见发布包中的 THIRD_PARTY_NOTICES.md。指纹、平台和自行导入资料的归属与使用条件以其来源和相应声明为准。
本 README 不为探径项目声明未指定的开源许可证,也不把第三方依赖的许可等同于整个项目的许可。使用和再分发时请保留适用声明。
0.9.2 工具易用性
工具描述补充按需使用场景。AI 创建任务后返回 entryGuide:最多 3 个入口、每项至多 240 个 UTF-16 字符的正文摘要、截断标记及读取参数;可用 read_task 取完整内容。入口只是可选参考,不自动选路或调用工具。回执重试保留当时的入口快照。黑板操作说明增加正确的嵌套示例,node_ids 放入 entry 或 patch,严格校验及原始文本保存规则不变。不注入系统提示词,不介入上下文组装、压缩或循环。
