Initial commit

2025-08-30 21:05:34 +00:00
commit b04557a923
40 changed files with 5469 additions and 0 deletions
--- a/docs/dev/30_PLUGIN_DEV_GUIDE.md
+++ b/docs/dev/30_PLUGIN_DEV_GUIDE.md
@@ -0,0 +1,146 @@
+# Writing Plug‑ins for Stella Ops SDK *Preview 3*
+
+> **SDK status:** *Preview 3* is compatible with the **v0.1 α** runtime.  
+> Interfaces freeze at **v0.2 β**; binary‑breaking changes are still possible
+> until then.
+
+| SDK NuGet | Runtime compat | Notes |
+|-----------|---------------|-------|
+| `StellaOps.SDK 0.2.0-preview3` | `stella-ops >= 0.1.0-alpha` | Current preview |
+| `StellaOps.SDK 0.2.x‑beta` | v0.2 β (Q1 2026) | Interface **freeze** |
+| `StellaOps.SDK 1.0.0` | v1.0 GA (Q4 2026) | Semantic Ver from here |
+
+---
+
+## 0 · Extension points
+
+| Area | Interface / format | Example |
+|------|--------------------|---------|
+| SBOM mutator | `ISbomMutator` | Inject SPDX licences |
+| Additional scanner | `IVulnerabilityProvider` | Rust Crates ecosystem |
+| Policy engine | **OPA Rego** file | Custom pass/fail rule |
+| Result exporter | `IResultSink` | Slack webhook notifier |
+
+*Hot‑plugging (live reload) is **post‑1.0**; modules are discovered once
+during service start‑up.*
+
+---
+
+## 1 · Five‑minute quick‑start (C# /.NET {{ dotnet }})
+
+```bash
+dotnet new classlib -n SlackExporter
+cd SlackExporter
+dotnet add package StellaOps.SDK --version 0.2.0-preview3
+````
+
+```csharp
+using System.Net.Http.Json;
+using StellaOps.Plugin;
+
+public sealed class SlackSink : IResultSink
+{
+    private readonly string _webhook =
+        Environment.GetEnvironmentVariable("SLACK_WEBHOOK")
+        ?? throw new InvalidOperationException("Missing SLACK_WEBHOOK");
+
+    public string Name => "Slack Notifier";
+
+    public async Task ExportAsync(ScanResult result, CancellationToken ct)
+    {
+        var payload = new
+        {
+            text = $":rotating_light: *{result.Image}* " +
+                   $"→ {result.Findings.Count} findings (max {result.MaxSeverity})"
+        };
+
+        using var client = new HttpClient();
+        await client.PostAsJsonAsync(_webhook, payload, ct);
+    }
+}
+```
+
+```bash
+dotnet publish -c Release -o out
+sudo mkdir -p /opt/stella/plugins/Slack
+sudo cp out/SlackExporter.dll /opt/stella/plugins/Slack/
+sudo systemctl restart stella-ops
+```
+
+Start‑up log:
+
+```
+[PluginLoader] Loaded 1 plug‑in:
+  • Slack Notifier
+```
+
+---
+
+## 2 · Packaging rules
+
+| Item   | Rule                                      |
+| ------ | ----------------------------------------- |
+| Folder | `/opt/stella/plugins/<NiceName>/`         |
+| DLLs   | Your plug‑in + non‑GAC deps               |
+| Config | Env‑vars or `settings.yaml`               |
+| SBOM   | Optional `addon.spdx.json` for provenance |
+
+---
+
+## 3 · Security sandbox
+
+* Runs as Linux user **`stella‑plugin` (UID 1001)**.
+* SELinux/AppArmor profile blocks inbound traffic; outbound :80/443 only.
+* cgroup default: **1 CPU / 256 MiB** (adjustable).
+* SHA‑256 of every DLL is embedded in the run report.
+
+---
+
+## 4 · Debugging
+
+| Technique         | Command                            |
+| ----------------- | ---------------------------------- |
+| Verbose core log  | `STELLA_LOG=debug`                 |
+| Per‑plug‑in log   | Inject `ILogger<YourClass>`        |
+| Dry‑run (no fail) | `--plugin-mode warn`               |
+| Hot reload        | *Not supported* (planned post‑1.0) |
+
+Logs: `/var/log/stella-ops/plugins/YYYY‑MM‑DD.log`.
+
+---
+
+## 5 · Interface reference (Preview 3)
+
+```csharp
+namespace StellaOps.Plugin
+{
+    public interface ISbomMutator
+    {
+        string Name { get; }
+        Task<SoftwareBillOfMaterials> MutateAsync(
+            SoftwareBillOfMaterials sbom,
+            CancellationToken ct = default);
+    }
+
+    public interface IVulnerabilityProvider
+    {
+        string Ecosystem { get; }
+        Task<IReadOnlyList<Vulnerability>> QueryAsync(
+            PackageReference p, CancellationToken ct = default);
+    }
+
+    public interface IResultSink
+    {
+        string Name { get; }
+        Task ExportAsync(
+            ScanResult result, CancellationToken ct = default);
+    }
+}
+```
+
+Full POCO docs: [https://git.stella-ops.org/stella-ops/sdk/-/tree/main/docs/api](https://git.stella-ops.org/stella-ops/sdk/-/tree/main/docs/api).
+
+---
+
+*Last updated {{ "now" | date: "%Y‑%m‑%d" }} – constants auto‑injected.*
+