能力 SDK

用于为 Guard 平台构建安全能力的共享 Go SDK。

包

pkg/capability - 能力接口

定义了安全扫描器实现的标准化接口。

类型：

// Target - 能力扫描的目标
type Target struct {
    Type  TargetType        // domain, ip, port, url, cloud_resource
    Value string            // 目标值
    Meta  map[string]string // 附加上下文
}

// Finding - 能力发现的结果
type Finding struct {
    Type     FindingType    // asset, risk, attribute
    Severity Severity       // info, low, medium, high, critical
    Data     map[string]any // 灵活载荷
}

// Capability - 需要实现的接口
type Capability interface {
    Name() string
    Run(ctx context.Context, target Target) ([]Finding, error)
}

实现示例：

type SubdomainScanner struct{}

func (s *SubdomainScanner) Name() string {
    return "subdomain-scanner"
}

func (s *SubdomainScanner) Run(ctx context.Context, target capability.Target) ([]capability.Finding, error) {
    if target.Type != capability.TargetDomain {
        return nil, fmt.Errorf("expected domain, got %s", target.Type)
    }

    // 扫描逻辑...

    return []capability.Finding{
        {
            Type: capability.FindingAsset,
            Data: map[string]any{
                "dns":   "found.example.com",
                "class": "domain",
            },
        },
    }, nil
}

pkg/formatter - 输出格式化

用于渲染扫描结果的多格式输出系统。

支持的格式：

• Terminal（流式，通过 lipgloss 着色）
• JSON（缓冲，可选美化打印）
• NDJSON（流式，换行分隔）
• Markdown（缓冲，基于模板的报告）
• SARIF 2.1.0（缓冲，GitHub/Azure 集成）

基本用法：

import "github.com/praetorian-inc/capability-sdk/pkg/formatter"

// 创建格式化器
f, err := formatter.New(formatter.Config{
    Format: formatter.FormatJSON,
    Writer: os.Stdout,
    Pretty: true,
})
if err != nil {
    return err
}
defer f.Close()

// 格式化发现结果
f.Format(ctx, formatter.Finding{
    ID:       "vuln-001",
    Title:    "Security Issue",
    Severity: formatter.SeverityHigh,
})

// 完成并附带摘要
f.Complete(ctx, formatter.Summary{TotalFindings: 1, HighCount: 1})

转换能力发现结果：

import (
    "github.com/praetorian-inc/capability-sdk/pkg/capability"
    "github.com/praetorian-inc/capability-sdk/pkg/formatter"
)

// 运行能力
findings, err := scanner.Run(ctx, target)

// 转换并格式化为 CLI 输出
for _, cf := range findings {
    ff := formatter.FromCapabilityFinding(cf)
    f.Format(ctx, ff)
}

多输出（TeeFormatter）：

terminal, _ := formatter.New(formatter.Config{Format: formatter.FormatTerminal, Writer: os.Stdout})
jsonFile, _ := formatter.New(formatter.Config{Format: formatter.FormatJSON, Writer: file})

tee, _ := formatter.NewTee(terminal, jsonFile)
tee.Format(ctx, finding) // 同时写入两者

并发提交（Aggregator）：

agg := formatter.NewAggregator(f, 100) // 缓冲区大小 100

// 从多个 goroutine 提交
go func() { agg.Submit(ctx, finding1) }()
go func() { agg.Submit(ctx, finding2) }()

agg.Close() // 等待所有写入完成

pkg/clisurface - CLI 文档漂移门禁

遍历 cobra 命令树，并生成、拼接和检查由其构建的文档 产物，从而使已提交的文档不会与二进制文件悄然漂移。使用 clisurface.New 构建 Docs，然后使用 Docs.Write 重新生成， 并使用 Docs.CheckArtifacts 加上 Docs.LintRepo 在已提交文件、 说明文字或 Go 注释不再与 CLI 匹配时使 CI 失败。完整 API 请参见 go doc ./pkg/clisurface。

架构

┌─────────────────────────────────────────────────────────────────────┐
│                     独立工具                                        │
│  实现：capability.Capability                                        │
│  产出：  []capability.Finding                                       │
└────────────────────────────┬────────────────────────────────────────┘
                             │
              ┌──────────────┴──────────────┐
              ▼                              ▼
┌─────────────────────────┐    ┌─────────────────────────────-────────┐
│   CLI 输出路径          │    │       CHARIOT 集成路径               │
│                         │    │                                      │
│  capability.Finding     │    │  capability.Finding                  │
│         │               │    │         │                            │
│         ▼               │    │         ▼                            │
│  formatter.Finding      │    │  Chariot 适配器（位于 chariot 仓库） │
│  (FromCapabilityFinding)│    │         │                            │
│         │               │    │         ▼                            │
│         ▼               │    │  Tabularium 模型（Asset/Risk/Attr）  │
│  Terminal/JSON/SARIF    │    │         │                            │
│                         │    │         ▼                            │
│     stdout/file         │    │     job.Send() → Storage             │
└─────────────────────────┘    └───────────────────────────────-──────┘

扩展类型

添加新的目标类型

1. 提交 issue：“需要为 X 添加 git_repo 目标类型”
2. 后端开发人员审查 Tabularium 映射
3. 添加到 pkg/capability/target.go：

   TargetGitRepo TargetType = "git_repo"
   

4. 更新 Valid() 方法
5. 添加测试
6. 更新 Chariot 适配器

添加新的发现类型

1. 提交 issue：“需要为 X 添加 relationship 发现类型”
2. 定义 Data schema
3. 添加到 pkg/capability/finding.go
4. 更新 pkg/formatter/capability_converter.go 中的转换器
5. 添加测试

使用此 SDK 的模块

• diocletian - 云安全扫描器

许可证

Apache License 2.0。参见 LICENSE。

许可证仅在仓库根目录声明一次。不要添加逐文件的版权或许可证头——包括从带有这些头的同级项目移植代码时。根目录的 LICENSE 是权威声明；无需在每个文件上重复它。