Merge pull request #2 from chainreactors/feat/export-filter

Feat/export filter

Author: M09Ic

README.md

@@ -35,45 +35,44 @@ SDK 采用简单的四组件架构：
 所有引擎支持双重加载模式：
 
 - **本地模式**: 从嵌入数据或文件系统加载
-- **远程模式**: 从 Cyberhub API 加载，支持 source 过滤
+- **远程模式**: 从 Cyberhub API 加载，支持 sources 过滤
 
 ## 快速开始
 
 ### Fingers - 指纹识别
 
 ```go
 import (
-    "context"
     "github.com/chainreactors/sdk/fingers"
 )
 
 // 创建并加载引擎
-config := fingers.NewConfig().
-    SetCyberhubURL("http://127.0.0.1:8080").
-    SetAPIKey("your_key")
+config := fingers.NewConfig()
+config.WithCyberhub("http://127.0.0.1:8080", "your_key")
 
 engine, _ := fingers.NewEngine(config)
-libEngine, _ := engine.Load(context.Background())
 
-// 检测指纹
-frameworks, _ := libEngine.DetectContent(httpResponse)
+// 方式一：使用 Match API 直接检测
+frameworks, _ := engine.Match(httpResponseBytes)
+
+// 方式二：使用底层 Engine
+libEngine := engine.Get()
+frameworks, _ = libEngine.DetectContent(httpResponseBytes)
 ```
 
 ### Neutron - POC 扫描
 
 ```go
 import (
-    "context"
     "github.com/chainreactors/sdk/neutron"
 )
 
 // 创建并加载引擎
-config := neutron.NewConfig().
-    SetCyberhubURL("http://127.0.0.1:8080").
-    SetAPIKey("your_key")
+config := neutron.NewConfig()
+config.WithCyberhub("http://127.0.0.1:8080", "your_key")
 
 engine, _ := neutron.NewEngine(config)
-templates, _ := engine.Load(context.Background())  // 自动编译
+templates := engine.Get()  // 自动编译
 
 // 执行 POC
 for _, t := range templates {
@@ -88,26 +87,30 @@ for _, t := range templates {
 
 ```go
 import (
-    "context"
     "github.com/chainreactors/sdk/gogo"
     "github.com/chainreactors/sdk/fingers"
     "github.com/chainreactors/sdk/neutron"
 )
 
 // 加载指纹库
 fingersEngine, _ := fingers.NewEngine(fingersConfig)
-libEngine, _ := fingersEngine.Load(ctx)
-fEngine := libEngine.GetEngine("fingers")
 
 // 加载 POC
 neutronEngine, _ := neutron.NewEngine(neutronConfig)
-templates, _ := neutronEngine.Load(ctx)
 
 // 创建集成扫描器
-gogoEngine := gogo.NewGogoEngineWithFingersAndNeutron(nil, fEngine, templates)
+gogoConfig := gogo.NewConfig().
+    WithFingersEngine(fingersEngine).
+    WithNeutronEngine(neutronEngine)
+gogoEngine := gogo.NewEngine(gogoConfig)
 gogoEngine.Init()
 
 // 执行扫描
+gogoCtx := gogo.NewContext().
+    SetThreads(1000).
+    SetVersionLevel(2).
+    SetExploit("all").
+    SetDelay(5)
 task := gogo.NewScanTask("192.168.1.0/24", "80,443,8080")
 resultCh, _ := gogoEngine.Execute(gogoCtx, task)
 
@@ -120,14 +123,16 @@ for result := range resultCh {
 
 ```go
 import (
-    "context"
     "github.com/chainreactors/sdk/spray"
 )
 
 engine := spray.NewEngine(nil)
 engine.Init()
 
 urls := []string{"http://example.com", "http://target.com"}
+sprayCtx := spray.NewContext().
+    SetThreads(100).
+    SetTimeout(10)
 task := spray.NewCheckTask(urls)
 resultCh, _ := engine.Execute(sprayCtx, task)
 
@@ -142,39 +147,45 @@ for result := range resultCh {
 ### Fingers 配置
 
 ```go
-config := fingers.NewConfig().
-    SetCyberhubURL("http://127.0.0.1:8080").
-    SetAPIKey("your_key").
-    SetSource("github").        // 可选：按来源过滤
-    SetTimeout(10 * time.Second).
-    SetMaxRetries(3)
+config := fingers.NewConfig()
+config.WithCyberhub("http://127.0.0.1:8080", "your_key")
+config.SetSources("github")       // 可选：按来源过滤
+config.WithLocalFile("fingers.yaml") // 可选：从导出的 YAML 加载
+config.SetTimeout(10 * time.Second)
 ```
 
 ### Neutron 配置
 
 ```go
-config := neutron.NewConfig().
-    SetCyberhubURL("http://127.0.0.1:8080").
-    SetAPIKey("your_key").
-    SetSource("github").        // 可选：按来源过滤
-    SetLocalPath("./pocs").     // 可选：本地 POC 目录
-    SetTimeout(10 * time.Second)
+config := neutron.NewConfig()
+config.WithCyberhub("http://127.0.0.1:8080", "your_key")
+config.SetSources("github")       // 可选：按来源过滤
+config.WithLocalFile("./pocs") // 可选：本地 POC 目录
+config.SetTimeout(10 * time.Second)
 ```
 
 ### GoGo 配置
 
 ```go
 config := gogo.NewConfig().
+    WithFingersEngine(fingersEngine).
+    WithNeutronEngine(neutronEngine)
+```
+
+### GoGo 运行时上下文
+
+```go
+ctx := gogo.NewContext().
     SetThreads(1000).
     SetVersionLevel(2).         // 0-3，数值越高检测越深
     SetExploit("all").          // none/all/known
     SetDelay(5)                 // 请求超时时间
 ```
 
-### Spray 配置
+### Spray 运行时上下文
 
 ```go
-config := spray.NewConfig().
+ctx := spray.NewContext().
     SetThreads(100).
     SetTimeout(10)
 ```
@@ -201,31 +212,41 @@ sdk/
 ├── fingers/              # 指纹识别引擎
 │   ├── engine.go        # 核心引擎实现
 │   ├── config.go        # 配置
-│   └── api.go          # 公共 API
+│   ├── types.go         # 类型定义
+│   ├── additions.go     # 扩展方法 (AddFingers, AddFingersFile)
+│   ├── init.go          # 注册入口
+│   └── README.md        # 引擎文档
 │
 ├── neutron/             # POC 扫描引擎
-│   ├── engine.go       # 核心引擎（自动编译）
-│   ├── config.go       # 配置
-│   └── api.go         # 公共 API
+│   ├── engine.go        # 核心引擎（自动编译）
+│   ├── config.go        # 配置
+│   ├── types.go         # 类型定义
+│   ├── templates.go     # Templates 辅助类型 (Filter, Merge)
+│   ├── additions.go     # 扩展方法 (AddPocs, AddPocsFile)
+│   └── README.md        # 引擎文档
 │
-├── gogo/               # 端口扫描（集成）
-│   ├── gogo.go        # 支持 Fingers/Neutron 的引擎
-│   ├── config.go      # 配置
-│   └── api.go        # 公共 API
+├── gogo/                # 端口扫描（集成）
+│   ├── gogo.go          # 支持 Fingers/Neutron 的引擎
+│   ├── types.go         # 类型定义和配置
+│   ├── init.go          # 注册入口
+│   └── README.md        # 引擎文档
 │
-├── spray/              # HTTP 检测引擎
-│   ├── spray.go       # 核心引擎实现
-│   ├── config.go      # 配置
-│   └── api.go        # 公共 API
+├── spray/               # HTTP 检测引擎
+│   ├── spray.go         # 核心引擎实现
+│   ├── types.go         # 类型定义和配置
+│   ├── init.go          # 注册入口
+│   └── README.md        # 引擎文档
 │
 ├── pkg/
-│   ├── cyberhub/      # 统一 API 客户端
-│   │   ├── client.go  # HTTP 客户端（支持 gzip）
-│   │   └── types.go   # API 类型
-│   ├── interface.go   # 核心 SDK 接口
-│   └── helper.go      # 工具函数
+│   ├── cyberhub/        # 统一 API 客户端
+│   │   ├── client.go    # HTTP 客户端（支持 gzip）
+│   │   ├── config.go    # 客户端配置
+│   │   └── types.go     # API 类型
+│   ├── association/     # 关联索引
+│   │   └── index.go     # 指纹-POC 关联索引
+│   └── interface.go     # 核心 SDK 接口
 │
-└── examples/           # CLI 工具实现
+└── examples/            # CLI 工具实现
     ├── fingers/
     ├── neutron/
     ├── gogo/
@@ -239,8 +260,7 @@ sdk/
 
 所有引擎都支持从 Cyberhub 加载数据：
 - Gzip 压缩处理
-- 自动重试（指数退避）
-- 基于 source 的过滤
+- 基于 sources 的过滤
 - API Key 认证
 
 ### POC 自动编译
@@ -255,7 +275,84 @@ Neutron 引擎在加载时自动编译 POC：
 GoGo 可以同时集成 Fingers 和 Neutron：
 - 模板按指纹、ID、标签建立索引
 - 9,444 个 POC 生成 61,267 条索引（多重索引）
-- 根据检测到的指纹自动匹配模板
+
+### 基于指纹筛选 POC 示例
+
+下面示例演示：Fingers 命中指纹后，使用 `neutron.Templates.Filter` 从模板集中筛选相关 POC 并执行。
+
+```go
+package main
+
+import (
+	"strings"
+
+	"github.com/chainreactors/sdk/fingers"
+	"github.com/chainreactors/sdk/neutron"
+	neutronTemplates "github.com/chainreactors/neutron/templates"
+)
+
+func main() {
+	// 1) 指纹识别
+	fConfig := fingers.NewConfig().WithCyberhub("http://127.0.0.1:8080", "your_key")
+	fEngine, _ := fingers.NewEngine(fConfig)
+
+	// 使用 Match API 直接匹配
+	frameworks, _ := fEngine.Match([]byte("raw http response"))
+
+	// 收集指纹名称
+	fingerNames := make(map[string]struct{})
+	for _, frame := range frameworks {
+		fingerNames[strings.ToLower(frame.Name)] = struct{}{}
+	}
+
+	// 2) 加载 POC 并使用 Filter 筛选
+	nConfig := neutron.NewConfig().WithCyberhub("http://127.0.0.1:8080", "your_key")
+	nEngine, _ := neutron.NewEngine(nConfig)
+
+	// 使用 Templates.Filter 按指纹/标签筛选
+	filtered := (neutron.Templates{}).Merge(nEngine.Get()).Filter(func(t *neutronTemplates.Template) bool {
+		// 按 Fingers 字段匹配
+		for _, finger := range t.Fingers {
+			if _, ok := fingerNames[strings.ToLower(finger)]; ok {
+				return true
+			}
+		}
+		// 按 Tags 匹配
+		for _, tag := range t.GetTags() {
+			if _, ok := fingerNames[strings.ToLower(tag)]; ok {
+				return true
+			}
+		}
+		return false
+	})
+
+	// 3) 执行筛选后的 POC
+	task := &neutron.ExecuteTask{
+		Target:    "http://target.example",
+		Templates: filtered.Templates(),
+	}
+	resultCh, _ := nEngine.Execute(neutron.NewContext(), task)
+	for range resultCh {
+		// consume results
+	}
+}
+```
+
+也可以使用 `pkg/association` 包中的 `FingerPOCIndex` 进行更高效的关联查询。
+
+### 动态扩展
+
+引擎支持在运行时动态添加指纹和 POC：
+
+```go
+// Fingers: 动态添加指纹
+engine.AddFingers(newFingers)           // 添加指纹切片
+engine.AddFingersFile("./custom.yaml")  // 从文件/目录加载
+
+// Neutron: 动态添加 POC
+engine.AddPocs(newTemplates)            // 添加模板切片
+engine.AddPocsFile("./custom-pocs/")    // 从文件/目录加载
+```
 
 ## 开发
 
@@ -275,7 +372,7 @@ go test ./spray -v
 ### 添加新引擎
 
 1. 实现 `pkg/interface.go` 中的核心接口
-2. 创建引擎包，包含 `engine.go`、`config.go`、`api.go`
+2. 创建引擎包，包含 `engine.go`、`config.go`、`init.go`
 3. 在 `engine.go` 的 init 函数中注册
 4. 在 `examples/` 中添加 CLI 工具