SDK Go partagé définissant une interface de capacité standard pour les scanners de sécurité, avec une sortie de résultats multi-format (terminal, JSON, NDJSON, Markdown, SARIF) et des vérifications de dérive de la documentation CLI.
SDK Go partagé pour la création de capacités de sécurité pour la plateforme Guard.
pkg/capability - Interface de capacitéDéfinit l'interface standardisée que les scanners de sécurité implémentent.
Types :
// Target - ce qu'une capacité scanne
type Target struct {
Type TargetType // domain, ip, port, url, cloud_resource
Value string // La valeur de la cible
Meta map[string]string // Contexte supplémentaire
}
// Finding - ce qu'une capacité découvre
type Finding struct {
Type FindingType // asset, risk, attribute
Severity Severity // info, low, medium, high, critical
Data map[string]any // Charge utile flexible
}
// Capability - l'interface à implémenter
type Capability interface {
Name() string
Run(ctx context.Context, target Target) ([]Finding, error)
}
Exemple d'implémentation :
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 - Formatage de sortieSystème de sortie multi-format pour le rendu des résultats de scan.
Formats pris en charge :
Utilisation de 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})
Conversion des résultats de capacité :
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)
}
Sortie multiple (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
Soumission 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 - Barrière de dérive de la documentation CLIParcourt un arbre de commandes cobra et génère, assemble et vérifie les
artefacts de documentation construits à partir de celui-ci, afin que la
documentation commitée ne puisse pas dériver silencieusement du binaire.
Construisez un Docs avec clisurface.New, puis utilisez Docs.Write pour
régénérer et Docs.CheckArtifacts ainsi que Docs.LintRepo pour faire échouer
la CI lorsque les fichiers commités, la prose ou les commentaires Go ne
correspondent plus à la CLI. Voir go doc ./pkg/clisurface pour l'API complète.
┌─────────────────────────────────────────────────────────────────────┐
│ 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 pour X »pkg/capability/target.go :
TargetGitRepo TargetType = "git_repo"
Valid()relationship pour X »pkg/capability/finding.gopkg/formatter/capability_converter.godiocletian - Scanner de sécurité cloudApache License 2.0. Voir LICENSE.
La licence est énoncée une seule fois, à la racine du dépôt. N'ajoutez pas d'en-têtes de copyright ou de licence par fichier — y compris lors du portage de code depuis un projet voisin qui en contient. Un fichier LICENSE à la racine constitue la déclaration faisant autorité ; le répéter sur chaque fichier n'est pas nécessaire.