重构 SDK 至 pkg/sdk，补齐能力并修复引擎泄漏与竞态 - #224
Open
kkx600 wants to merge 5 commits into
Open
Conversation
把根目录的 afrog.go 迁移为独立的 pkg/sdk 包，改用函数式选项， 让 SDK 可以安全地嵌入长驻进程。 SDK - New(ctx, opts...) 函数式选项，context 贯穿生命周期 - 哨兵错误、Close() 幂等释放、channel 流式订阅 - 默认零控制台输出，构造函数不再创建目录或改写用户配置 - 结果视图可直接 JSON 序列化，携带完整请求/响应报文 - 新增 WithCheckpoint(断点续扫)、WithCyberspace(空间测绘取目标)、 WithTargetPreProbe、WithExecutionMonitor、WithTaskTimeout， 以及 OOB 轮询间隔与命中保留时长 PoC 输入 - PocFile/PocPaths/AppendPoc 合并解析，修复同时指定 -P 与 -ap 时 -ap 被静默丢弃的问题 - 支持 glob 通配，加载失败原因通过 PocDiagnostics 返回而非只打印 引擎 - OOB 轮询协程不再在扫描结束后存活，新增 Runner.Release 释放资源 - ticker 与 oobMgr 改为原子指针，消除 Stop 与调度之间的竞态 - 极高速率下 ticker 间隔为 0 导致 panic 的问题 - 新增 OnFailure 回调，PoC 执行失败不再被静默吞掉 - 响应体被 MaxRespBodySize 截断时标记 BodyTruncated - 端口扫描改用 net.JoinHostPort，修复 IPv6 地址拼接 - HexDecode 遇到非法输入不再 log.Fatal 终止宿主进程 Web - 任务状态改由互斥量保护，finalizeTask 保证只执行一次， 修复取消扫描时并发计数被多减、队列超额准入的问题 - 扫描结束后释放 scanner，避免长驻服务累积引擎与轮询协程 同步更新中英文 SDK 文档与全部示例，新增 55 个 SDK 测试、 3 个 web 并发测试，全量包通过 -race。
此前这几项修复通过了全量回归，但没有任何测试断言它们自身的正确性： 回归只能说明没有破坏既有功能，不能说明修复真的生效。 每个测试都通过临时回退对应修复验证过会失败，确认不是空测： - OOB 轮询协程回收：回退后 Stop 永远等不到协程退出，测试超时 - ticker/oobMgr 原子指针：并发 setTicker/waitTick/stopTicker/Stop 在 -race 下的专项测试 - ticker 零间隔：回退后 rate=2e9 触发 "non-positive interval for NewTicker" panic - OnFailure：回退后连接被拒的目标不产生任何失败上报 - BodyTruncated：补上真实截断为 true 的场景，此前只测了 false - IPv6 地址拼接：回退后报 "too many colons in address" - HexDecode：回退后 log.Fatal 直接终止测试进程 pkg/utils 此前没有任何测试文件，现已覆盖。
上一次提交把根目录的 afrog.go 删掉了，使用 afrog.NewSDKScanner 的 存量代码会直接编译不过。这次把旧接口原样恢复为根包的兼容门面， 内部委托给 pkg/sdk，因此只有一份实现，缺陷修复与新能力对两套 API 同时生效。 兼容性 - SDKOptions 的 51 个原始字段、默认值、语义保持不变 - NewSDKOptions / NewSDKScanner 与 19 个方法签名逐一对齐 - OnResult / OnPort / OnWebProbe 仍是构造后赋值的公开字段， 处理器在调用时读取而非构造时捕获 - 六个通道仍由 EnableStream 控制创建，并保留"满了就丢"的 非阻塞语义：改成阻塞会让不读通道的旧代码直接卡死 - SetProxy / SetRateLimit / SetConcurrency 在 Run 前生效， 底层扫描器按需重建 - 配置错误仍在 NewSDKScanner 阶段返回，而不是推迟到 Run 旧行为的唯一修正：同时指定 PocFile 与 AppendPoc 时， 旧版静默丢弃 AppendPoc，现在两者都会加载。 新能力以可选字段开放给旧写法：PocPaths/PocPathsOnly、ResumeFile、 TaskHardTimeoutSec/TaskSmartTimeout、Cyberspace/Query/QueryCount、 MonitorTargets、OOBPollInterval/OOBHitRetention、MaxStoredResults、 RedactedHeaders、OnFailure、Silent。留空即与以前完全一致。 另有 Scanner() 返回底层 *sdk.Scanner，便于逐步迁移。 验证 - 新增 15 个兼容测试，覆盖基础扫描、回调、流式、异步、setter、 统计、Close 幂等、构造期报错、通道不读不卡死 - 从 git 历史取出改动前的 7 个真实示例，未经修改全部编译通过 - 全量 15 个包在 -race 下通过 - 中英文文档补充两套 API 的对照与迁移说明
文档 - 中英文指南开头加入醒目的升级提示：说明本次改动较大、建议迁移到 pkg/sdk，同时明确旧接口入口与调用方式保持不变，优化与缺陷修复 都在内部完成 兼容性验证 - 用 go doc 对改动前后的根包 API 面做逐项机器比对：旧 API 零删除、 零签名变更，只新增了 16 个可选字段与 1 个 Scanner() 方法 测试 - 旧 API 补齐 Pause/Resume/IsPaused/IsStopping/SetProxy/GetOpenPorts/ IsOOBEnabled/GetOOBStatus 的覆盖，20 个方法现已全部有测试； 另加打印行为、二次 Run 被拒绝的用例 - 新 API 补一组表驱动测试，逐个断言 51 个选项确实生效，避免某个 单行选项函数写错却无人察觉；并断言关键选项透传到引擎、SDK 模式 下不会配置任何报告文件输出 - 补齐访问器、剩余四个事件流、错误类型的 Unwrap、端口记录与 进度加权路径 覆盖率：根包 81.4%，pkg/sdk 82.7%（此前 68.8%） 全量 15 个包在 -race 下通过；改动前的 7 个真实旧示例未经修改编译通过
审查兼容层每个字段的接线情况时发现：SDKOptions.BruteMaxRequests 和 DefaultAccept 从未被传递到引擎。旧代码设置这两个字段会被静默忽略， 是编译期发现不了的兼容性破坏。 根因是 pkg/sdk 有这两个 Options 字段却没有对应的选项函数，兼容层 无从设置。现补上 WithBruteMaxRequests 与 WithDefaultAccept，并在 兼容层接线。 同时补一组守护测试，逐字段断言 SDKOptions 的每一项都真正到达引擎， 覆盖基础配置、端口预扫描、OOB 与新增能力四个块。回退接线后测试会 报 "BruteMaxRequests did not reach the engine: got 5000, want 123"， 确认不是空测。 新增 sdk.Scanner.EngineOptions() 作为只读逃生舱，让兼容层可以验证 配置确实落到引擎，而不是靠肉眼比对。 覆盖率：根包 81.4% -> 85.4%，pkg/sdk 82.7%
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
把根目录的 afrog.go 迁移为独立的 pkg/sdk 包，改用函数式选项，
让 SDK 可以安全地嵌入长驻进程。
SDK
PoC 输入
引擎
Web
同步更新中英文 SDK 文档与全部示例，新增 55 个 SDK 测试、
3 个 web 并发测试，全量包通过 -race。