Plugin Framework

Verified against commit 942a18727c (2026-09-26). Re-verify with: ls src/Plugin src/Plugin/StellaOps.Plugin.Registry.Persistence/Migrations && rg -n "FromTrust" src/Plugin/StellaOps.Plugin.Sandbox/SandboxMode.cs src/Plugin/StellaOps.Plugin.Host/PluginHost.cs

Universal extensibility framework providing deterministic plugin discovery, admission checks, registry models, and SDK support for building Stella Ops plugins.

Audience: plugin authors building connectors, analyzers, or gate/step providers, and module owners who load plugins into their service hosts.

Purpose

The Plugin Framework is a foundational library that provides a consistent plugin lifecycle, deterministic discovery, signature/version admission checks, process/in-process sandboxing, and a persistent registry for Stella Ops modules. It is consumed as a library by other modules and exposes no HTTP endpoints.

The src/Plugin/ host derives a runtime SandboxMode from each plugin’s verified trust level via SandboxModeMatrix.FromTrust (StellaOps.Plugin.Sandbox/SandboxMode.cs). Today BuiltIn plugins load in-process with policy-interposed filesystem and process-spawn calls; Trusted plugins run out of process through ProcessSandbox behind a SandboxedPluginProxy; Untrusted plugins (valid signature, signer not allowlisted) still load in-process in an isolated, collectible AssemblyLoadContext, because the confined process runner is not yet wired into the host. See architecture.md.

Two distinct hosts exist. This dossier (src/Plugin/) documents the sandbox-capable host used by Release Orchestrator. A separate, older library at src/__Libraries/StellaOps.Plugin/ (PluginHost/PluginManifestLoader/NullPluginVerifier) is a lightweight shared host with admission checks and no process sandboxing; Integrations, Scanner and the JobEngine Scheduler use it. Integrations adds its own stellaops.pluginhost.process.v1 child-runner path for production admission, allowlisted integration:test-connection / integration:health-check / integration:discovery execution, deterministic dead-runner evidence and brokered single-authref secret materialization.

Quick Links

• Architecture - Technical design and implementation details
• Sandbox confinement events - Stable plugin.sandbox.* event-name contract (StellaOps.Plugin.Sandbox/Diagnostics/PluginSandboxEventName.cs)

Status

Key Features

• IPlugin interface and lifecycle: IPlugin (extends IAsyncDisposable) is the contract for all plugins. The PluginLifecycleState enum (StellaOps.Plugin.Abstractions/Lifecycle/PluginLifecycleState.cs) defines nine states: Discovered (0), Loading (1), Initializing (2), Active (3), Degraded (4), Stopping (5), Stopped (6), Failed (7), Unloading (8). There is no StartAsync/StopAsync on the plugin itself — the host drives start/stop; the plugin exposes InitializeAsync, a periodic HealthCheckAsync, and disposal-based shutdown.
• Trust levels and sandbox modes: PluginTrustLevel (BuiltIn = 0, Trusted = 1, Untrusted = 2) is the cryptographic pre-load verdict (“who is the plugin?”); SandboxModeMatrix.FromTrust maps it to the intended SandboxMode (“what may it do at runtime?”) per PSB-01: BuiltIn → InProcessHardened, Trusted → OutOfProcessOverlay, Untrusted → OutOfProcessConfined. The first two are wired into the host; Untrusted currently loads in-process in an isolated load context, not in a confined process.
• Process sandboxing: StellaOps.Plugin.Sandbox ships ProcessSandbox (ISandbox/ISandboxFactory, registered by AddPluginHost) for out-of-process plugins: IPluginProcessManager process management, OverlayFilesystemPolicy write redirection, NetworkPolicyEnforcer, Linux/Windows IResourceLimiter (the Windows limiter uses a Job Object), LinuxAppArmorAttacher / ApparmorAuditLogScraper (SELinux has event names only, no attacher), and an IGrpcPluginBridge over a plugin_bridge.proto client. The host wires this via SandboxedPluginProxy, which preserves the IPlugin lifecycle without loading the plugin assembly into the host process. AssemblyPluginLoader rejects Trusted plugins (they must launch through ProcessSandbox).
• Sandbox confinement diagnostics: Stable plugin.sandbox.* event names (PluginSandboxEventName) form a binding contract for workspace, OS-confinement, resource-limiter, and lifecycle-denial events — e.g. plugin.sandbox.confinement.profile_attached, plugin.sandbox.confinement.fail_closed, plugin.sandbox.resource_limiter.exceeded, plugin.sandbox.lifecycle.start_denied. See sandbox-confinement-events.md.
• Signature & trust admission: PluginTrustDecisionMaker plus X509PinnedSignatureValidator and PemDirectoryPluginTrustRoot verify a plugin.signature.json against a PEM trust bundle. Trust is promoted only by leaf-certificate thumbprint allowlists (BuiltInSignerThumbprints / TrustedSignerThumbprints on PluginHostOptions); a valid signature from any other signer yields Untrusted, and an invalid one is rejected. AllowUnsignedPluginsInDevelopment (honoured only in Development) and AllowMissingTrustRootBundle (boot escape hatch, default false) gate the fail-closed posture.
• License (SPDX) admission: DefaultLicenseValidator / SpdxExpression / LicensePolicyOptions enforce the manifest info.license field against allow/deny lists during discovery.
• Plugin registry: Persistent catalog with version tracking — InMemoryPluginRegistry for tests and PostgresPluginRegistry for production (IPluginRegistry). Tables plugins, plugin_capabilities and plugin_instances (multi-tenant) live in the registering host’s database under PluginRegistryOptions.SchemaName (default platform), created by the embedded migrations in src/Plugin/StellaOps.Plugin.Registry.Persistence/Migrations/ and applied by PluginRegistryMigrationRunner. Migration 003_retire_plugin_health_history.sql (RFC-19) removes the unused plugin_health_history table; health is kept only as the current status on the plugin row.
• Capability declarations: The PluginCapabilities [Flags] enum (long-backed) declares what a plugin provides — core (Crypto, Auth, Llm, Secrets), connector (Scm, Registry, Ci, Vault, Notification, IssueTracker), analysis (Analysis, Feed, Sbom), infrastructure (Network, FilesystemRead, FilesystemWrite, Process, Transport), and orchestrator (StepProvider, GateProvider, TargetProvider, EvidenceProvider, Execution) bits, with AllConnectors/AllOrchestrator/AllInfrastructure composites. Plugin manifests additionally carry typed CapabilityDeclaration entries and (Pattern Z, ADR-011) a requires list of PluginRequirement service contracts.
• SDK and test utilities: StellaOps.Plugin.Sdk (PluginBase, PluginInfoBuilder, options/config helpers) for plugin authors; StellaOps.Plugin.Testing (PluginTestHost, fake services/logger, deterministic TimeProvider/GUID) for deterministic harnesses; StellaOps.Plugin.Host.Tool provides a CLI host; Samples/StellaOps.Plugin.Samples.HelloWorld demonstrates the SDK.

Testing

Tests live under src/Plugin/__Tests/ (Abstractions, Host, Registry, Sandbox, Sdk). The sandbox suites also run in the platform-specific CI lanes .gitea/workflows/plugin-linux-os-confinement.yml, plugin-linux-overlay-sandbox.yml, plugin-windows-filesystem-sandbox.yml and plugin-windows-os-confinement.yml. StellaOps.Plugin.Sandbox.Tests references Microsoft.Extensions.Logging directly (it previously received logging only through a removed transitive test reference). Lane status is tracked in the active sprint, not here.

Dependencies

Upstream (this module depends on)

• Cryptography (StellaOps.Cryptography) - StellaOps.Plugin.Host routes asymmetric signature verification through the canonical crypto assembly (PSV-01…03). Otherwise foundational with no module-level upstream dependencies.

Downstream (modules that depend on this)

Consumers of the src/Plugin/host/abstractions/registry/sandbox/SDK projects documented here:

• Release Orchestrator - Primary consumer of the host: agent hosts (Agent.Host, Agent.DeployNative/Compose, Agent.Build*), WebApi (which also registers PostgresPluginRegistry), and the orchestrator plugin SDK/IntegrationHub
• Platform - Platform.WebService and Platform.Database
• Router / Gateway - Router.Common, Gateway.WebService, and *.Plugin.Unified packs
• Cryptography - StellaOps.Cryptography.Plugin / .Plugin.Hsm
• AdvisoryAI / Authority / Notify / Doctor / Signer / CLI / OfflineKit (export adapters) - reference src/Plugin/ projects (re-verify with rg -l "StellaOps.Plugin.(Abstractions|Host|Sandbox|Sdk)" src --glob "*.csproj")

Note: Integrations, Scanner and JobEngine (Scheduler job plugins) load plugins through the older src/__Libraries/StellaOps.Plugin/ shared host (sandbox-free) and reference only StellaOps.Plugin.Abstractions from src/Plugin/.

Related Documentation

• Architecture - Full component and contract reference, including the two-host distinction
• Sandbox confinement events - Binding plugin.sandbox.* event-name contract
• Release Orchestrator - Primary consumer of the src/Plugin/ host (agents, gates, deploy)
• Integrations - Consumer of the older __Libraries/StellaOps.Plugin shared host (connector plugins)
• Scanner - Consumer of the older __Libraries/StellaOps.Plugin shared host (analysis extensibility)
• Plugin system architecture - Authoritative dossier covering signature verification (SPRINT_20260501_001) and SPDX license enforcement (SPRINT_20260501_002). Plugin authors: see the “License declaration (SPDX)” section for the required info.license field and the default allow / deny lists.