क्षमता SDK

Guard प्लेटफ़ॉर्म के लिए सुरक्षा क्षमताओं के निर्माण हेतु साझा Go SDK।

पैकेज

pkg/capability - क्षमता इंटरफ़ेस

वह मानकीकृत इंटरफ़ेस परिभाषित करता है जिसे सुरक्षा स्कैनर लागू करते हैं।

प्रकार:

// 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 (स्ट्रीमिंग, newline-delimited)
• 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})

क्षमता निष्कर्षों को परिवर्तित करना:

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 कमांड ट्री को वॉक करता है और उससे निर्मित दस्तावेज़ीकरण आर्टिफ़ैक्ट्स को जनरेट, स्प्लाइस और जाँचता है, ताकि कमिट किए गए दस्तावेज़ बाइनरी से चुपचाप ड्रिफ्ट न हो सकें। clisurface.New से एक Docs बनाएँ, फिर पुनर्जनन के लिए Docs.Write और जब कमिट की गई फ़ाइलें, गद्य या Go टिप्पणियाँ CLI से मेल न खाएँ तो CI को विफल करने के लिए Docs.CheckArtifacts के साथ-साथ Docs.LintRepo का उपयोग करें। पूर्ण 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. इश्यू खोलें: "X के लिए git_repo target प्रकार चाहिए"
2. बैकएंड डेव Tabularium मैपिंग की समीक्षा करता है
3. pkg/capability/target.go में जोड़ें:

   TargetGitRepo TargetType = "git_repo"
   

4. Valid() विधि अपडेट करें
5. टेस्ट जोड़ें
6. Chariot अडैप्टर अपडेट करें

नया Finding प्रकार जोड़ना

1. इश्यू खोलें: "X के लिए relationship finding प्रकार चाहिए"
2. Data स्कीमा परिभाषित करें
3. pkg/capability/finding.go में जोड़ें
4. pkg/formatter/capability_converter.go में कन्वर्टर अपडेट करें
5. टेस्ट जोड़ें

इस SDK का उपयोग करने वाले मॉड्यूल

• diocletian - क्लाउड सुरक्षा स्कैनर

लाइसेंस

Apache License 2.0. देखें LICENSE।

लाइसेंस एक बार, रेपो रूट पर बताया गया है। प्रति-फ़ाइल कॉपीराइट या लाइसेंस हेडर न जोड़ें — जब किसी सहोदर से कोड पोर्ट करें जिसमें वे हेडर हों, तब भी नहीं। रूट LICENSE आधिकारिक कथन है; इसे हर फ़ाइल पर दोहराना आवश्यक नहीं है।