Capability SDK

Общий Go SDK для создания security-возможностей для платформы Guard.

Пакеты

pkg/capability — интерфейс Capability

Определяет стандартизированный интерфейс, который реализуют security-сканеры.

Типы:

// 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 Findings:

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 и генерирует, вставляет и проверяет артефакты документации, построенные на его основе, чтобы закоммиченная документация не могла незаметно разойтись с бинарником. Создайте Docs через clisurface.New, затем используйте Docs.Write для регенерации и Docs.CheckArtifacts вместе с Docs.LintRepo, чтобы валить CI, когда закоммиченные файлы, текст или Go-комментарии больше не соответствуют CLI. Полный 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. Откройте issue: "Need git_repo target type for X"
2. Backend-разработчик проверяет маппинг Tabularium
3. Добавьте в pkg/capability/target.go:

   TargetGitRepo TargetType = "git_repo"
   

4. Обновите метод Valid()
5. Добавьте тесты
6. Обновите адаптер Chariot

Добавление нового типа Finding

1. Откройте issue: "Need relationship finding type for X"
2. Определите схему Data
3. Добавьте в pkg/capability/finding.go
4. Обновите конвертер в pkg/formatter/capability_converter.go
5. Добавьте тесты

Модули, использующие этот SDK

• diocletian — сканер облачной безопасности

Лицензия

Apache License 2.0. См. LICENSE.

Лицензия указана один раз, в корне репозитория. Не добавляйте copyright или заголовки лицензии в отдельные файлы — в том числе при переносе кода из родственного проекта, где они присутствуют. Корневой LICENSE является авторитетным заявлением; повторять его в каждом файле не требуется.