SDK de Capacidades

SDK compartido de Go para construir capacidades de seguridad para la plataforma Guard.

Paquetes

pkg/capability - Interfaz de Capacidad

Define la interfaz estandarizada que implementan los escáneres de seguridad.

Tipos:

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

Implementación de Ejemplo:

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 - Formateo de Salida

Sistema de salida multi-formato para renderizar resultados de escaneo.

Formatos Soportados:

• Terminal (streaming, coloreado mediante lipgloss)
• JSON (buffered, opción de pretty-print)
• NDJSON (streaming, delimitado por saltos de línea)
• Markdown (buffered, informes basados en plantillas)
• SARIF 2.1.0 (buffered, integración con 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})

Convirtiendo Hallazgos de Capacidades:

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-Salida (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

Envío Concurrente (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 - Puerta de Deriva de Documentación de CLI

Recorre un árbol de comandos cobra y genera, empalma y verifica los artefactos de documentación construidos a partir de él, de modo que la documentación confirmada no pueda desviarse silenciosamente del binario. Construya un Docs con clisurface.New, luego use Docs.Write para regenerar y Docs.CheckArtifacts más Docs.LintRepo para fallar en CI cuando los archivos confirmados, la prosa o los comentarios de Go ya no coincidan con la CLI. Consulte go doc ./pkg/clisurface para la API completa.

Arquitectura

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

Extendiendo Tipos

Agregando un Nuevo Tipo de Target

1. Abrir issue: "Se necesita el tipo de target git_repo para X"
2. El desarrollador de backend revisa el mapeo de Tabularium
3. Agregar a pkg/capability/target.go:

   TargetGitRepo TargetType = "git_repo"
   

4. Actualizar el método Valid()
5. Agregar pruebas
6. Actualizar el adaptador de Chariot

Agregando un Nuevo Tipo de Finding

1. Abrir issue: "Se necesita el tipo de finding relationship para X"
2. Definir el esquema de Data
3. Agregar a pkg/capability/finding.go
4. Actualizar el convertidor en pkg/formatter/capability_converter.go
5. Agregar pruebas

Módulos que Usan Este SDK

• diocletian - Escáner de seguridad en la nube

Licencia

Apache License 2.0. Consulte LICENSE.

La licencia se declara una vez, en la raíz del repositorio. No agregue encabezados de copyright o licencia por archivo — incluso al portar código desde un proyecto hermano que los incluya. Un LICENSE en la raíz es la declaración autoritativa; repetirlo en cada archivo no es necesario.