SDK de Capacidades

SDK Go compartilhado para construir capacidades de segurança para a plataforma Guard.

Pacotes

pkg/capability - Interface de Capacidade

Define a interface padronizada que os scanners de segurança implementam.

Tipos:

// Target - o que uma capacidade escaneia
type Target struct {
    Type  TargetType        // domain, ip, port, url, cloud_resource
    Value string            // O valor do alvo
    Meta  map[string]string // Contexto adicional
}

// Finding - o que uma capacidade descobre
type Finding struct {
    Type     FindingType    // asset, risk, attribute
    Severity Severity       // info, low, medium, high, critical
    Data     map[string]any // Payload flexível
}

// Capability - a interface a ser implementada
type Capability interface {
    Name() string
    Run(ctx context.Context, target Target) ([]Finding, error)
}

Exemplo de Implementação:

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 - Formatação de Saída

Sistema de saída multi-formato para renderizar resultados de escaneamento.

Formatos Suportados:

• Terminal (streaming, colorido via lipgloss)
• JSON (buffered, opção de pretty-print)
• NDJSON (streaming, delimitado por nova linha)
• Markdown (buffered, relatórios baseados em template)
• SARIF 2.1.0 (buffered, integração GitHub/Azure)

Uso Básico:

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})

Convertendo Findings de Capacidade:

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)
}

Multi-Saída (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

Envio Concorrente (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 - Portão de Detecção de Desvio de Documentação da CLI

Percorre uma árvore de comandos cobra e gera, insere e verifica os artefatos de documentação construídos a partir dela, para que a documentação commitada não possa silenciosamente divergir do binário. Construa um Docs com clisurface.New, depois use Docs.Write para regenerar e Docs.CheckArtifacts mais Docs.LintRepo para falhar o CI quando os arquivos commitados, a prosa ou os comentários Go não corresponderem mais à CLI. Veja go doc ./pkg/clisurface para a API completa.

Arquitetura

┌─────────────────────────────────────────────────────────────────────┐
│                     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             │
└─────────────────────────┘    └───────────────────────────────-──────┘

Estendendo Tipos

Adicionando um Novo Tipo de Target

1. Abra uma issue: "Preciso do tipo de target git_repo para X"
2. O dev de backend revisa o mapeamento do Tabularium
3. Adicione em pkg/capability/target.go:

   TargetGitRepo TargetType = "git_repo"
   

4. Atualize o método Valid()
5. Adicione testes
6. Atualize o adaptador do Chariot

Adicionando um Novo Tipo de Finding

1. Abra uma issue: "Preciso do tipo de finding relationship para X"
2. Defina o schema de Data
3. Adicione em pkg/capability/finding.go
4. Atualize o conversor em pkg/formatter/capability_converter.go
5. Adicione testes

Módulos que Usam Este SDK

• diocletian - Scanner de segurança em nuvem

Licença

Apache License 2.0. Veja LICENSE.

A licença é declarada uma vez, na raiz do repositório. Não adicione cabeçalhos de copyright ou licença por arquivo — inclusive ao portar código de um projeto irmão que os contenha. Um LICENSE na raiz é a declaração autoritativa; repeti-lo em cada arquivo não é necessário.