SDK Go condiviso che definisce un'interfaccia standard per le capacità degli scanner di sicurezza, con output dei risultati in formati multipli (terminale, JSON, NDJSON, Markdown, SARIF) e controlli di deriva della documentazione CLI.
SDK Go condiviso per la creazione di capability di sicurezza per la piattaforma Guard.
pkg/capability - Interfaccia CapabilityDefinisce l'interfaccia standardizzata che gli scanner di sicurezza implementano.
Tipi:
// Target - cosa scansiona una capability
type Target struct {
Type TargetType // domain, ip, port, url, cloud_resource
Value string // Il valore del target
Meta map[string]string // Contesto aggiuntivo
}
// Finding - cosa scopre una capability
type Finding struct {
Type FindingType // asset, risk, attribute
Severity Severity // info, low, medium, high, critical
Data map[string]any // Payload flessibile
}
// Capability - l'interfaccia da implementare
type Capability interface {
Name() string
Run(ctx context.Context, target Target) ([]Finding, error)
}
Esempio di Implementazione:
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 - Formattazione dell'OutputSistema di output multi-formato per il rendering dei risultati di scansione.
Formati Supportati:
Utilizzo Base:
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})
Conversione dei Finding delle Capability:
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-Output (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
Invio 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 - Gate di Drift della Documentazione CLIPercorre un albero di comandi cobra e genera, integra e verifica gli artefatti
di documentazione costruiti da esso, così che la documentazione committata non
possa silenziosamente divergere dal binario. Costruisci un Docs con
clisurface.New, poi usa Docs.Write per rigenerare e Docs.CheckArtifacts
più Docs.LintRepo per far fallire la CI quando i file committati, la prosa o
i commenti Go non corrispondono più alla CLI. Vedi
go doc ./pkg/clisurface per l'API completa.
┌─────────────────────────────────────────────────────────────────────┐
│ 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 │
└─────────────────────────┘ └───────────────────────────────-──────┘
git_repo per X"pkg/capability/target.go:
TargetGitRepo TargetType = "git_repo"
Valid()relationship per X"pkg/capability/finding.gopkg/formatter/capability_converter.godiocletian - Scanner di sicurezza cloudApache License 2.0. Vedi LICENSE.
La licenza è dichiarata una sola volta, alla radice del repository. Non aggiungere intestazioni di copyright o licenza per singolo file — nemmeno quando si porta codice da un progetto affine che le contiene. Un LICENSE alla radice è la dichiarazione autorevole; ripeterlo su ogni file non è necessario.