v0.3.3

新增 association 模糊搜索机制，支持对索引内所有实体的子串模糊匹配；修复 CyberHub POC 导出默认状态过滤导致零结果的问题。

New Features

association — 模糊搜索

• 新增 WithSearch 查询构建器，支持跨指纹/别名/模板的子串模糊搜索
• Lookup 空查询（无 terms 且无 search）返回索引内全部实体
• 新增 FingersWithTemplates 便捷方法，返回有关联模板的指纹及模板数量
• 模糊搜索可与精确 terms 组合使用，结果自动去重并展开关联实体

// 模糊搜索
result := idx.Lookup(association.NewQuery().WithSearch("nginx"))
// 模糊 + 精确组合
result = idx.Lookup(association.NewQuery().WithSearch("splunk").WithTags("webserver"))
// 查询有关联模板的指纹
fwt := result.FingersWithTemplates(idx)

Bug Fixes

• cyberhub: applyDefaultPOCStatus 不再默认注入 status=active，修复 CyberHub 实例 POC 无 status 字段时导出零结果的问题

Tests

• 新增 8 个 search 机制单元测试（子串匹配、去重、大小写无关、组合查询等）
• 新增 7 个 CyberHub 集成测试（真实数据验证，通过 CYBERHUB_URL/CYBERHUB_KEY 环境变量控制）

v0.3.2

v0.3.2

新增 CPE 自动关联机制，重构 httpx 为通用 client generator，升级 neutron/fingers 大幅提升主动指纹匹配准确率。

Breaking Changes

• 全引擎: Execute(nil, task) 不再静默 fallback 到 NewContext()，改为返回 error。调用方必须显式传入 Context

New Features

association — CPE 自动关联（新模块）

• 新增 pkg/association 模块，基于 CPE vendor:product 自动建立指纹 ↔ POC 关联索引
• BuildFromProvider 一行代码从 CyberHub 加载指纹与 POC 数据并构建索引
• 支持按指纹名、CPE、POC ID、tag、CVE 等多维度查询，结果包含关联的指纹、别名和 POC 模板
• LookupFrameworks 直接从扫描结果的 Frameworks 查询关联 POC
• QueryFromResult 从 gogo/spray/zombie 的 types.Result 自动提取查询条件

// 构建关联索引
idx, _ := association.BuildFromProvider(ctx, cyberhub.NewProvider(url, key))

// 指纹名查询关联 POC
result := idx.Lookup(association.NewQuery().WithFingers("tomcat"))
for _, tpl := range result.Templates {
    fmt.Println(tpl.ID) // "CVE-2017-12615"
}

// 直接从 Frameworks 查询
related := idx.LookupFrameworks(scanResult.Frameworks)

// 从扫描结果自动提取查询条件
related = idx.Lookup(association.QueryFromResult(engineResult))

httpx — 通用 client generator

• 重构 pkg/httpx 为带预设的 HTTP client 工厂
• 新增 BrowserConfig() 预设（自动注入浏览器 UA/Accept/Accept-Language）和 DefaultConfig() 裸配置
• 新增 WithTimeout/WithProxy/WithRedirects/WithHeaders builder 方法
• NewClient 内聚 proxy fallback：代理解析失败自动回退无代理 client

client, _ := httpx.NewClient(httpx.BrowserConfig().WithProxy("socks5://127.0.0.1:1080"))

neutron — redirect 策略对齐 + per-context CookieJar

• redirect 策略三态化（DontFollow / FollowAll / FollowSameHost），对齐 nuclei RedirectFlow 语义
• per-context CookieJar：每次模板执行自动创建独立 CookieJar，redirect 链内 Set-Cookie 正确传递
• xray 转换器修正 follow_redirects 默认行为，自动检测依赖跳转响应的规则并保留原始响应

fingers — 主动探测优化

• 主动探测新增跨 finger 的 cachingSender 请求缓存，相同 send_data 路径只发一次 HTTP 请求
• hub/xray 引擎改用 ExecuteWithTransport 整模板执行，修复多请求模板 body_N 塌陷为 body_1 的漏匹配

Bug Fixes

• 全引擎: emitStats 在 context 取消后跳过回调，避免 send on closed channel panic
• neutron: favicon 探测增强——最终跳转 URL 做 base、增加 favicon.ico 探测路径、独立 context 避免超时误判
• neutron: 修正 RootURL 挂载路径拼接

Dependencies

• fingers f5c144e → 7e07a99
• neutron 1a0a5a8 → a9bbe4f

v0.3.1

修复 xray 指纹引擎的模板路由和误报问题，新增统一主动探测 API。

Bug Fixes

• fingers: CyberHub 平台使用 xray tag 标记模板，但 SDK 仅识别 source1 tag，导致 5400+ xray 模板全部错误路由到 fingerprinthub 引擎。现在同时支持 source1 和 xray 两个路由 tag
• neutron: 转换后的 xray 多步模板在中间 request 上带有 internal-matchers: true 标志，但 neutron 的 Request 结构体无此字段，YAML 反序列化时被静默丢弃。中间 request 的通用 word matcher（如 location.href）被当作正常 matcher 执行，导致大量误报。新增 InternalMatchers bool 字段，当为 true 时 matcher 仍执行（保证 extractor 和 req-condition 数据正常），但不上报 Matched=true

New Features

• fingers: 新增 Engine.ActiveMatch(baseURL, level, transport) 统一主动探测 API。调用方只需提供 URL、探测级别和自定义 http.RoundTripper，内部自动调度 native fingers、fingerprinthub、xray 三个引擎的 HTTPActiveMatch，无需感知底层引擎差异

Dependencies

• neutron e112381 → 1a0a5a8（internal-matchers 支持）

v0.3.0 — proton 集成 + SSL/JSON/XPath 协议扩展 + Engine 统一重构

v0.3.0 — proton 集成 + SSL/JSON/XPath 协议扩展 + Engine 统一重构

本版本包含 Breaking Changes。核心变更：集成 proton 敏感信息扫描引擎，neutron 新增 SSL/TLS 协议和 JSON/XPath 匹配能力，全引擎 API 统一重命名。

Breaking Changes

• gogo/spray/zombie: GogoEngine、SprayEngine 统一重命名为 Engine；NewEngine 签名统一返回 (*Engine, error)
• proton: ProtonFinding 重命名为 ProtonResult
• types: 移除 pkg/types/registry.go，各引擎 init 注册逻辑移除

New Features

proton 敏感信息扫描引擎（新引擎）

• 集成 proton 文件扫描引擎到 SDK，支持本地文件/内存数据的敏感信息匹配（密码、密钥、凭证、连接字符串等）
• 提供 ScanData(data, label) 和 ScanBlock(data, label) 两种 API，分别面向文本数据和二进制数据块（进程内存、网络流）
• proton 类型统一收归 pkg/types，与 gogo/spray/zombie/neutron 风格一致

neutron — SSL/TLS 协议 + JSON/XPath matcher

• 新增纯 TLS 探测协议（标准库实现），支持 ssl/tls 协议槽位、cipher_suites 注入
• 新增 common/tlsx 共享包：标准库 TLS/证书提取、IsUntrusted/IsRevoked 判断、cfssl 撤销检查子模块可选启用
• cert DSL 字段扩展到 8 项 + raw_cert，XrayCertFields 单源注册表统一 http/ssl 双命名空间
• ScanContext.PathPrefix → RootURL 挂载路径前缀
• 新增 operators/full 子模块：JSON/XPath extractor 和 matcher 支持（gojq + antchfx），替代原 mini-jq 实现
• 新增 DSL dir() 函数
• Go 1.11 全面兼容修复（io.NopCloser/strings.ReplaceAll/Duration.Milliseconds 替换、build tags、testify 降级）

fingers — xray 引擎 + AC 快速匹配

• 新增 xray 指纹引擎，基于 xray POC 转换实现
• 新增 AC 关键词预过滤 + RE2 默认正则引擎，1MB 基准测试验证
• 新增 templates.Load 接口，xray POC 支持 opt-in 加载
• 引擎级 CaseInsensitive 开关统一大小写匹配策略
• TinyGo 兼容：模板 sanitizer + sender 适配

Bug Fixes

• spray: 修复 context 取消后 emitStats panic 的问题
• proton: 修复 Template.Execute 未遍历 Request path + 多行 opResult 合并错误
• neutron: 隔离模板编译变量，避免并发执行时变量污染
• fingers: 修复 AC fast path 丢失匹配详情、multi-request 模板 extractor 结果未串联、nil-map panic

Refactor

• 移除未使用代码和冗余抽象（-284 行）
• 各引擎 init.go 注册逻辑移除，简化初始化流程
• proton: 架构重构为 pure matching engine SDK — 文件遍历移出 scanner，Runner 公开扫描阶段 API，FFI export 恢复
• neutron: common/tlsx 抽离、operators/full 独立子模块、cert 字段映射收口

Dependencies

• fingers v1.2.1 → v1.2.2-0.2026..f5c144e（xray 引擎 + AC 预过滤 + CaseInsensitive + TinyGo 兼容）
• neutron c816917 → e112381（SSL/TLS 协议 + JSON/XPath operators/full + cert DSL 扩展 + Go 1.11 兼容）
• proton 03df34b → 89c10c8（pure matching SDK 重构 + FFI export + Template.Execute bugfix）
• zombie 705f548 → bdd2cdf（ProxyDial 注入 + 依赖更新）

Full Changelog: v0.2.4...v0.3.0

v0.2.4

Features

• neutron: 新增 VulnResult 类型，提供可序列化的漏洞扫描结果结构（types.VulnResult + ExecuteResult.VulnResult()）
• neutron: 集成 pluggable POC 格式转换器注册表，支持 templates.Load 自动加载 xray 格式 POC
• neutron: xray 转换器全面重构 — 变量别名、req-condition 多请求标准形、三引号、favicon hash（PR #28）
• neutron: HTTP 运行期支持 favicon_content、字面量 payload、未解析模板阻断
• neutron: 模板级静态变量模拟 randstr/randnum 预处理器并跨请求块共享
• neutron: shot 工具增加 flag-CLI/JSON 输出与统计，harness 支持 HTTP 状态码范围解析
• neutron: DSL codegen 透传 field 包裹函数 + header/status_code 运算符 + 字符串转义

Bug Fixes

• neutron: 修复 FollowRedirects bool 类型与 nil 比较错误
• neutron: operators/templates Compile 入口 fail-fast 遇 nil 接收者/列表项
• neutron: ToQuery 加 nil 守卫；抽取器结果在匹配判断之后返回
• neutron: active-match 并发安全 + 类型断言守卫
• fingers: 修复 source1 tag 覆盖引擎实例而非复制副本的问题
• fingers: 主动扫描保留原始路径并正确解析重定向
• cyberhub: 优先使用 POC 原始 YAML，提升模板加载准确性

Refactor

• neutron: 变量预求值重构为 globalVars 机制，替代 preprocessor/FrozenVariables，简化跨请求块变量共享（PR #27）
• neutron: req-condition 多请求改用 nuclei 标准形，去掉中间 gate
• neutron: 清理 favicon 剪枝、路径展开残留的死代码及非标准 internal-matchers 字段
• fingers: 移除 SDK 层路径拼接和重定向包装，下沉至 neutron 层处理

Dependencies

• neutron ea95825 → c816917（27 commits: converter registry + xray 转换器重构 + 变量系统重构 + 运行期补齐）
• fingers 9b9b6fe → 385e7d5（xray template load + active-match 修复）
• parsers da1ebd0 → 3d2c51b
• spray 546e8ab → 66dafe7（proton import 路径适配）
• zombie 21a4ec2 → 705f548
• proton e7e7b12 → 03df34b（protocols/file → proton/file 重构）
• proxyclient 74a84a4 → 2a80e08

v0.2.3 — 全栈代理统一 + 多引擎指纹主动探测(并发安全)

v0.2.3 — 全栈代理统一 + 多引擎指纹主动探测(并发安全）

本版本无破坏性变更。除新特性外,重点修复了多引擎并发主动探测下的数据竞争。

New Features

代理 / HTTP(全栈统一、per-instance、并发安全)

• 三级代理控制,优先级 Context > Config > Client:
  • client.WithProxy(proxies ...string) — 全局默认代理
  • Config.WithProxy(proxies ...string) — 引擎级(fingers / neutron / gogo / spray)
  • Context.SetProxy(proxies ...string) — 单任务细粒度(gogo / spray / zombie)
• 新增 pkg/types.NewProxyDialer([]string) / ResolveProxy(...) — proxyclient 桥接
• 新增 pkg/httpx:per-instance 的 HTTP client / transport 构造,无全局单例,多引擎并发互不干扰(含并发隔离测试)
• 经 proxyclient 支持 socks5 / http / https 等多协议代理链

多引擎指纹

• 同时加载并匹配 fingers + fingerprinthub + xray 三引擎
• 新增 xray 引擎支持,引擎类型在 provider 层解析(单一 xray tag)
• 统一主动探测(active probing):三引擎共享同一个 HTTP Transport(连接池复用),不再强依赖 FingersEngine 存在

gogo

• 智能扫描模式(smart scan)+ CIDR 排除

Concurrency & Robustness（本次重点）

• 并发主动探测数据竞争修复(-race 验证):xray / fingerprinthub 的 HTTPActiveMatch 此前把 per-call 的 http.Client 暂存到共享编译模板上(req.SetHTTPClient),并发扫描下产生数据竞争。现改为通过 ScanContext.Client / Template.ExecuteWithClient 执行时传入,共享模板运行时只读。
  • 配套上游修复:neutron 新增 ScanContext.Client;common.Logger() 去除懒初始化时对全局 logger 的写(与并发 Debug/Dump 竞争)。
• Panic 硬化:为模板执行路径上未判 ok 的类型断言(dsl/ast、dsl/codegen、convert/matcher、convert/top_expr、gogo worker 的 []string 断言 + 越界)加保护,避免 malformed 模板触发 panic。
• 主动匹配的 recover 边界从静默 Debug 提升为 Warn + 引擎名:不再吞掉、可观测,一个坏模板不会中断整轮多目标扫描。

Bug Fixes

• 模板变量丢失 — 引擎构建改用 RawContent 原始 YAML,保住 404Path = rand_text_alphanumeric 等变量(此前 Template.Variables 带 yaml:"-",经 Template→YAML→map 序列化被吃掉)
• 空 Protocol — 引擎初始化时空 Protocol 默认按 "http" 处理

Dependencies

• chainreactors/{fingers, neutron, gogo, utils, zombie} 推进至 2026-05-30(含上述并发安全修复)
• panjf2000/ants/v2 2.12.0 → 2.12.1
• CI:dependabot 改为分组更新 chainreactors/*(不再 ignore)

Full Changelog: v0.2.2...v0.2.3

v0.2.2

v0.2.2 — Provider 统一数据源架构

Breaking Changes

• WithLocalFile 已移除 — fingers.Config 和 neutron.Config 不再支持 WithLocalFile()，改用 WithProvider(provider.NewFileProvider(fingersPath, pocsPath))
• Provider 字段改为 Providers 切片 — 所有 Config 的 Provider 单字段改为 Providers []types.Provider，通过 WithProvider() 追加
• WithProvider 签名变更 — 改为可变参数 WithProvider(providers ...types.Provider)，支持多次调用自动合并

New Features

• types.Provider 接口 — 统一的数据源抽象，Fingers() + POCs() 两个方法
• provider.NewEmbedProvider() — 显式加载 fingers/gogo 库内置数据（8700+ 指纹 + 83 POC）
• provider.NewFileProvider(fingersPath, pocsPath) — 从本地 YAML 文件或目录加载，支持递归目录扫描
• provider.NewURLProvider(fingersURL, pocsURL) — 从远程 URL 下载 YAML 数据
• 多 Provider 合并 — WithProvider(embed, cyberhub, file) 自动合并多个数据源的指纹和 POC
• Spray 支持 Provider — spray.Config 新增 WithProvider()，自动从 Provider 创建 fingers 引擎

Bug Fixes

• 修复隐式 embed 数据混入 — alias.NewAliases() 和 engine.Compile() 不再被调用，杜绝 embed aliases 覆盖 CyberHub 数据
• 修复指纹名称大小写不一致 — 为所有 finger 生成基础 alias 映射，确保输出名称统一小写
• 修复指纹被 embed alias Block 规则静默丢弃 — 不再加载 embed aliases，CyberHub 指纹不会被意外屏蔽

Removed

• 移除 fingers.Config.Filename / neutron.Config.LocalPath 字段
• 移除 defaultPaths 本地文件扫描
• 移除 gogo / spray 的隐式 fallback（pkg.LoadFinger、pkg.LoadNeutron、pkg.LoadFingers）

Migration Guide

// Before (v0.2.1)
fingers.NewConfig().WithLocalFile("fingers.yaml")
neutron.NewConfig().WithLocalFile("./pocs")
client.New(client.WithProvider(cyberhub.NewProvider(url, key)))

// After (v0.2.2)
import "github.com/chainreactors/sdk/pkg/provider"

fingers.NewConfig().WithProvider(provider.NewFileProvider("fingers.yaml", ""))
neutron.NewConfig().WithProvider(provider.NewFileProvider("", "./pocs"))
client.New(client.WithProvider(
    provider.NewEmbedProvider(),
    cyberhub.NewProvider(url, key),
))

v0.2.1

What's Changed

Draft 模式重构

将 Draft 控制从 Provider 统一到 ExportFilter，实现端到端 draft 指纹/POC 加载。

Breaking Change

• 移除 Provider.WithDraft()，改用 ExportFilter.WithDraft(bool)

New

• ExportFilter.WithDraft(bool) — 控制是否加载草稿内容
• FingerprintExport — 导出完整指纹记录，包含 RawContent、RawContentDraft、Engine、Source、SourceNames
• Provider.ExportFingers() — 返回 []FingerprintExport 完整记录

Improved

• Provider.Fingers() 在 Draft=true 时自动从 RawContentDraft 解析指纹，下游 gogo/spray/fingers engine 无需改动即可使用 draft 数据
• client.exportFingers / exportPOCs 签名简化，移除独立的 draft bool 参数
• 合并 fingerprintResponse 到 FingerprintExport，消除重复类型

用法

// Draft 模式 — 一行 filter 即可端到端
hub := cyberhub.NewProvider(url, key).
    WithFilter(types.NewExportFilter().WithDraft(true))
engine := gogo.NewEngine(gogo.NewConfig().WithProvider(hub))

Closed PRs: #15, #17

Full Changelog: v0.2.0...v0.2.1

v0.2.0

Chainreactors SDK v0.2.0

自 v0.1.0 以来的全面重构，100 个文件变更，+14066 / -4625 行。

---

Highlights

• Client 统一入口 — 全新的 client.Client，共享 Provider + 依赖自动注入 + 可选关联索引
• Zombie 引擎 — 从零到完整，底层库重构，三种攻击模式 API
• 统一类型体系 — pkg/types 整合所有引擎的接口、类型别名和选项包装
• 用户文档 — 新增 docs/ 目录，8 篇系统性文档
• Association 独立化 — 关联索引从 GoGo 中剥离，成为 Client 层的可选机制

---

Breaking Changes

• client.New() 签名变更为 client.New(opts ...Option)（无参仍兼容）
• gogo.GogoEngine.Index() 和 gogo.Config.WithIndex() 已移除
• pkg/interface.go 重构为 pkg/types/ 目录
• pkg/cyberhub/config.go 重构为 pkg/cyberhub/provider.go（Provider 模式）

---

新增：Client 统一客户端 (client/)

v0.1.0 没有 Client 包。v0.2.0 新增：

c := client.New(
    client.WithProvider(provider),   // 共享数据源
    client.WithIndex(nil),           // 可选关联索引
)
defer c.Close()

gogoEng, _ := c.Gogo()     // 自动注入 Fingers + Neutron
sprayEng, _ := c.Spray()   // 自动注入 Fingers
related, _ := c.LookupResult(result)  // 关联查询

• WithProvider / WithResourceProvider — 共享配置
• With{Fingers,Neutron,Gogo,Spray,Zombie}Config — 单引擎覆盖
• 依赖自动注入：GoGo ← Fingers + Neutron，Spray ← Fingers
• Index() / Lookup() / LookupResult() / LookupByFinger() / LookupByCVE() / BuildIndex()

新增：Zombie 弱口令引擎 (zombie/)

v0.1.0 没有 Zombie。v0.2.0 新增完整引擎：

engine := zombie.NewEngine(nil)
results, _ := engine.Brute(ctx, targets, users, passwords)       // ClusterBomb
results, _ := engine.Pitchfork(ctx, targets, auths)              // Pitchfork
results, _ := engine.Sniper(ctx, targets)                        // Sniper

• 底层 zombie 库重构：提取 core.RunnerOption + core.NewRunner()
• SDK 委托 Runner，不再重新实现执行逻辑
• types.ZombieOption / types.ZombieTarget / types.ZombieMode* 统一类型
• SSH 支持 base64 编码 PEM 私钥（pk: 前缀）
• 26+ 种服务协议支持

新增：统一类型体系 (pkg/types/)

v0.1.0 只有 pkg/interface.go。v0.2.0 重构为完整的类型层：

• types.go — Engine / Context / Task / Result 核心接口 + 所有外部类型别名
• result.go — TypedResult[T] 泛型结果包装
• capacity.go — Capacity 加权信号量（跨引擎并发控制）
• stats.go — Stats 执行统计
• export_filter.go — ExportFilter 远程筛选条件
• gogo.go — GogoOption 包装 + Clone
• spray.go — SprayOption 包装 + 默认值 + Builder
• zombie.go — ZombieOption 包装 + Clone

新增：Association 关联查询 (pkg/association/)

v0.1.0 只有 index.go。v0.2.0 新增：

• query.go — Query / Lookup() / QueryFromResult() 统一查询
• 从 GoGo 引擎中完全剥离，作为 Client 层可选机制
• 支持 Finger / Alias / Template / CVE / Tag / Service / CPE / Attribute 多维查询
• c.LookupResult(r) 将任意引擎结果直接关联查询

新增：Cyberhub Provider (pkg/cyberhub/)

v0.1.0 是 Config 嵌入模式。v0.2.0 重构为 Provider 模式：

• NewProvider(url, key) — 统一数据源
• WithFilter(f) / WithTimeout(d) — 链式配置
• Fingers(ctx) / POCs(ctx) — 导出指纹和 POC
• ExportFilter 支持按 name / tag / source / severity / status / time 筛选

新增：用户文档 (docs/)

• quickstart.md — 快速开始
• concepts.md — 核心概念（Engine / Context / Task / Result）
• fingers.md / neutron.md / gogo.md / spray.md / zombie.md — 各引擎文档
• cyberhub.md — 数据源文档
• association.md — 关联查询文档

改进：Fingers 引擎

• WithMatchDetail() — 开启匹配细节（规则索引、匹配值）
• FullFingers.Filter() — 本地过滤
• AddFingers() / AddFingersFile() — 动态扩展
• 修复 alias pocs 在 compile 后丢失的问题

改进：Neutron 引擎

• NeutronResult 包含 Events（多步骤请求/响应）
• ExecuteWithEvents() — 获取 POC 执行每一步的数据
• Capacity 并发控制集成
• 优雅降级（加载失败不阻断）

改进：GoGo 引擎

• Capacity + ResourceProvider 集成
• 域名输入支持
• Association Index 从引擎中移除（归 Client 管理）
• 默认 fingers 引擎自动创建

改进：Spray 引擎

• 插件配置 API（Crawl / Active / Recon / Bak / Common / Fuzzuli）
• 字典/规则 setter
• SprayOption 统一包装 + SDK 友好默认值
• check/brute 统一执行路径

新增：Cyberhub WithDraft 草稿模式

• Provider.WithDraft() — 启用草稿模式，单次 API 调用同时加载已审核和待审核指纹/POC
• 已审核的数据直接使用，未审核的使用待审核版本
• Fingers 和 POCs export API 均支持 with_draft=true 参数

基础设施

• GitHub Actions CI 自动化
• Dependabot 依赖更新
• CRLF → LF 规范化
• 全量测试覆盖（zombie 24 例，client 12 例，含真实 SSH 连接测试）

Full Changelog

v0.1.0...v0.2.0

v0.1.0

What's Changed

• Feat/export filter by @wuchulonly in #2

New Contributors

• @wuchulonly made their first contribution in #2

Full Changelog: https://github.com/chainreactors/sdk/commits/v0.1.0