Capability SDK

Guard 플랫폼을 위한 보안 기능을 구축하기 위한 공유 Go SDK입니다.

패키지

pkg/capability - Capability 인터페이스

보안 스캐너가 구현하는 표준화된 인터페이스를 정의합니다.

타입:

// Target - what a capability scans
type Target struct {
    Type  TargetType        // domain, ip, port, url, cloud_resource
    Value string            // The target value
    Meta  map[string]string // Additional context
}

// Finding - what a capability discovers
type Finding struct {
    Type     FindingType    // asset, risk, attribute
    Severity Severity       // info, low, medium, high, critical
    Data     map[string]any // Flexible payload
}

// Capability - the interface to implement
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)
    }

    // Scan logic here...

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

pkg/formatter - 출력 포맷팅

스캔 결과를 렌더링하기 위한 다중 포맷 출력 시스템입니다.

지원 포맷:

• Terminal (스트리밍, lipgloss를 통한 컬러링)
• JSON (버퍼링, pretty-print 옵션)
• NDJSON (스트리밍, 개행 구분)
• Markdown (버퍼링, 템플릿 기반 리포트)
• SARIF 2.1.0 (버퍼링, GitHub/Azure 통합)

기본 사용법:

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

// Create a formatter
f, err := formatter.New(formatter.Config{
    Format: formatter.FormatJSON,
    Writer: os.Stdout,
    Pretty: true,
})
if err != nil {
    return err
}
defer f.Close()

// Format findings
f.Format(ctx, formatter.Finding{
    ID:       "vuln-001",
    Title:    "Security Issue",
    Severity: formatter.SeverityHigh,
})

// Complete with summary
f.Complete(ctx, formatter.Summary{TotalFindings: 1, HighCount: 1})

Capability Finding 변환:

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

// Run capability
findings, err := scanner.Run(ctx, target)

// Convert and format for CLI output
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) // Writes to both

동시 제출 (Aggregator):

agg := formatter.NewAggregator(f, 100) // buffer size 100

// From multiple goroutines
go func() { agg.Submit(ctx, finding1) }()
go func() { agg.Submit(ctx, finding2) }()

agg.Close() // Wait for all writes

pkg/clisurface - CLI 문서 드리프트 게이트

cobra 명령 트리를 순회하며 그로부터 생성된 문서 아티팩트를 생성, 병합, 검사하여 커밋된 문서가 바이너리와 조용히 어긋나지 않도록 합니다. clisurface.New로 Docs를 생성한 다음, Docs.Write로 재생성하고 Docs.CheckArtifacts와 Docs.LintRepo를 사용하여 커밋된 파일, 산문 또는 Go 주석이 더 이상 CLI와 일치하지 않을 때 CI를 실패시키세요. 전체 API는 go doc ./pkg/clisurface를 참조하세요.

아키텍처

┌─────────────────────────────────────────────────────────────────────┐
│                     STANDALONE TOOL                                 │
│  Implements: capability.Capability                                  │
│  Produces:   []capability.Finding                                   │
└────────────────────────────┬────────────────────────────────────────┘
                             │
              ┌──────────────┴──────────────┐
              ▼                              ▼
┌─────────────────────────┐    ┌─────────────────────────────-────────┐
│   CLI OUTPUT PATH       │    │       CHARIOT INTEGRATION PATH       │
│                         │    │                                      │
│  capability.Finding     │    │  capability.Finding                  │
│         │               │    │         │                            │
│         ▼               │    │         ▼                            │
│  formatter.Finding      │    │  Chariot Adapter (in chariot repo)   │
│  (FromCapabilityFinding)│    │         │                            │
│         │               │    │         ▼                            │
│         ▼               │    │  Tabularium Model (Asset/Risk/Attr)  │
│  Terminal/JSON/SARIF    │    │         │                            │
│                         │    │         ▼                            │
│     stdout/file         │    │     job.Send() → Storage             │
└─────────────────────────┘    └───────────────────────────────-──────┘

타입 확장

새로운 Target 타입 추가

1. 이슈 생성: "X를 위한 git_repo target 타입 필요"
2. 백엔드 개발자가 Tabularium 매핑 검토
3. pkg/capability/target.go에 추가:

   TargetGitRepo TargetType = "git_repo"
   

4. Valid() 메서드 업데이트
5. 테스트 추가
6. Chariot 어댑터 업데이트

새로운 Finding 타입 추가

1. 이슈 생성: "X를 위한 relationship finding 타입 필요"
2. Data 스키마 정의
3. pkg/capability/finding.go에 추가
4. pkg/formatter/capability_converter.go의 컨버터 업데이트
5. 테스트 추가

이 SDK를 사용하는 모듈

• diocletian - 클라우드 보안 스캐너

라이선스

Apache License 2.0. LICENSE를 참조하세요.

라이선스는 저장소 루트에 한 번 명시됩니다. 파일별 저작권 또는 라이선스 헤더를 추가하지 마세요 — 해당 헤더를 포함하는 형제 저장소에서 코드를 이식할 때도 마찬가지입니다. 루트 LICENSE가 권위 있는 명시이며, 모든 파일에 이를 반복할 필요는 없습니다.