Capability SDK

حزمة تطوير برمجيات Go مشتركة لبناء قدرات أمنية لمنصة Guard.

الحزم

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 (مخزّن مؤقتًا، مع خيار الطباعة الجميلة)
• NDJSON (بثّ مباشر، مفصول بأسطر جديدة)
• 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 ويولّد ويُدمج ويتحقق من مخرجات التوثيق المبنية منها، بحيث لا يمكن للتوثيق المُودَع أن ينحرف بصمت عن الملف التنفيذي. أنشئ Docs عبر clisurface.New، ثم استخدم Docs.Write لإعادة التوليد وDocs.CheckArtifacts مع Docs.LintRepo لإفشال CI عندما تتوقف الملفات المُودَعة أو النصوص أو تعليقات Go عن مطابقة CLI. راجع 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             │
└─────────────────────────┘    └───────────────────────────────-──────┘

توسيع الأنواع

إضافة نوع هدف جديد

1. افتح تذكرة: "Need git_repo target type for X"
2. يراجع مطوّر الواجهة الخلفية تعيين Tabularium
3. أضِف إلى pkg/capability/target.go:

   TargetGitRepo TargetType = "git_repo"
   

4. حدّث طريقة Valid()
5. أضِف اختبارات
6. حدّث محوّل Chariot

إضافة نوع نتيجة جديد

1. افتح تذكرة: "Need relationship finding type for X"
2. عرّف مخطط Data
3. أضِف إلى pkg/capability/finding.go
4. حدّث المحوّل في pkg/formatter/capability_converter.go
5. أضِف اختبارات

الوحدات التي تستخدم هذه الحزمة

• diocletian - ماسح أمني سحابي

الترخيص

Apache License 2.0. راجع LICENSE.

يُذكر الترخيص مرة واحدة، في جذر المستودع. لا تُضِف حقوق نشر أو ترويسات ترخيص لكل ملف — بما في ذلك عند نقل الكود من مشروع شقيق يحملها. ملف LICENSE في الجذر هو البيان المرجعي؛ تكراره في كل ملف ليس مطلوبًا.