reconmesh/worker-sdk

# worker-sdk 每个 parabellum worker 都会链接的共享 Go 库。它承载了控制平面与 worker 之间的通信契约，以及每个 worker 否则都需要重新实现的运行时基础管道：River 订阅、Postgres 连接池、OpenTelemetry 链路追踪、Prometheus 指标、发现去重和优雅停机。 SDK 的接口设计非常精简：三个接口、少量类型以及一个 `Serve` 入口点。新工具只需实现 `Tool.Run` 并调用 `worker.Serve(t)` 即可。仅此而已。其他一切均被隐藏。 ## 版本控制 `worker-sdk` 即为通信契约。破坏性更改会导致每个 worker 大约需要一个 PR 来处理，因此我们对此非常谨慎： - MINOR / PATCH 版本升级保持完全的向后兼容性。 - MAJOR 版本升级会经历至少一个 MINOR 版本的弃用周期，然后才会移除旧 API。 - SDK 自带 `Version` 常量；控制平面会读取每个 worker 的 `manifest.sdk_version` 以确保兼容性。 有关全组织范围的策略，请参阅 `../platform/docs/VERSIONING.md`。 ## 目录结构 ``` worker-sdk/ ├── worker/ # the public package; what `import` consumers use │ ├── tool.go # Tool interface, Job, Result, Finding, Asset │ ├── manifest.go # YAML manifest schema + load/validate (incl. Description) │ ├── jobargs.go # CascadeArgs wire contract (matches controlplane/jobtype) │ ├── serve.go # Serve() entry point: River + signal handling │ ├── runtime.go # PG pool, metrics, OTel, config reload │ ├── river_adapter.go # River JobArgs binding + worker registration │ ├── asset_writer.go # UpsertAsset + sync.Pool fingerprint │ ├── dedup.go # finding hash canonicalization │ └── once.go # --once / --asset synthetic-job mode (no DB, no River) ├── sdk/ # opt-in helpers; workers import only what they need │ ├── mtls/ # cleanhttp-style http.Client with mTLS roots │ ├── httpcache/ # cluster body cache + SourceCache │ ├── dns/ # dns-service HTTP client wrapper + local fallback │ ├── secretbox/ # AES-256-GCM decrypt (read-only by design) │ ├── metrics/ # shared prometheus collectors for the worker side │ └── tracing/ # OTLP exporter helpers ├── docs/ # ASSETS / FINDINGS / IDEMPOTENCE / CONCURRENCY / MANIFEST ├── grafana/ # ready-to-import dashboards for worker-side metrics └── CHANGELOG.md ``` `consumes.filter` DSL 在控制平面（cascade 引擎）内部进行解析，而不是在 SDK 中。worker 接收到的都是已经匹配过滤条件 的 job。SDK 仅提供用于声明它的 *manifest* 类型。 ## 快速示例 ``` package main import ( "context" "git.vozec.fr/Parabellum/worker-sdk/worker" ) type MyTool struct{} func (t *MyTool) Name() string { return "tm-mytool" } func (t *MyTool) Run(ctx context.Context, j worker.Job) (worker.Result, error) { return worker.Result{ Findings: []worker.Finding{{ Kind: "demo", Severity: worker.SeverityInfo, Title: "Hello from " + j.Asset.Value, }}, }, nil } func main() { worker.Serve(&MyTool{}) } ``` 包含上述主体代码的 worker 将会： - 读取二进制文件旁的 `manifest.yaml` - 连接到 Postgres（`PG_DSN` 环境变量） - 通过 River 订阅其声明的阶段队列 - 在 `:9090` 端口（可配置）暴露 `/metrics` 和 `/healthz` 端点 - 如果设置了 `OTEL_EXPORTER_OTLP_ENDPOINT`，则发出 OTLP 追踪 ## 文档 - [`docs/IDEMPOTENCE.md`](./docs/IDEMPOTENCE.md) - 为什么你的 `Run` 必须能够安全地重试，SDK 保证了什么以及你需要负责什么 - [`docs/MANIFEST.md`](./docs/MANIFEST.md) - 详细的 YAML schema - [`docs/ASSETS.md`](./docs/ASSETS.md) - 类型、各类型的 attrs 约定以及 JSONB 往返 (round-trip) 注意事项 - [`docs/FINDINGS.md`](./docs/FINDINGS.md) - finding 结构、去重哈希 (dedup hash) 算法、类型 + 严重性级别 - [`docs/CONCURRENCY.md`](./docs/CONCURRENCY.md) - 单主机限制、AIMD、熔断器、DNS 侧并发 - [`docs/OBSERVABILITY.md`](./docs/OBSERVABILITY.md) - SDK 暴露的免费指标、自定义指标 + 结构化日志约定 ## 更新日志 有关各版本的发布说明，请参阅 [CHANGELOG.md](./CHANGELOG.md)。 ## 许可证 MIT。

标签：API集成, DNS解析, GET参数, Go语言, mTLS, OpenTelemetry, PostgreSQL, River, Worker, YAML, 优雅关机, 作业调度, 分布式任务队列, 可观测性, 后端开发, 安全可观测性, 安全库, 开源项目, 接口契约, 控制平面, 插件系统, 数据去重, 无线安全, 日志审计, 测试用例, 渗透测试框架, 版本控制, 用户代理, 程序破解, 网络安全, 网络安全审计, 自定义请求头, 资产同步, 防御, 隐私保护