Plugin Framework

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/ projects ship a trust-driven sandbox: StellaOps.Plugin.Host derives a runtime SandboxMode from each plugin’s verified trust level via SandboxModeMatrix.FromTrust (StellaOps.Plugin.Sandbox/SandboxMode.cs) — BuiltIn → InProcessHardened, Trusted → OutOfProcessOverlay, Untrusted → OutOfProcessConfined. OutOfProcess* modes run the plugin in a separate OS process (ProcessSandbox) with an overlay filesystem, network-policy enforcement, resource limits, and a gRPC bridge; OutOfProcessConfined additionally attaches an OS-level confinement profile (AppArmor/SELinux on Linux, Job Object on Windows) and fails closed if it cannot be attached.

Two distinct hosts exist. This dossier (Source: src/Plugin/) documents the sandbox-capable host. A separate, older library at src/__Libraries/StellaOps.Plugin/ (PluginHost/PluginManifestLoader/NullPluginVerifier) is a simpler shared host that does not ship process sandboxing; consumers of that host must provide their own isolation. Integrations runs a narrow 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. See architecture.md for the full distinction.

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 a SandboxMode (“what may it do at runtime?”) per PSB-01: BuiltIn → InProcessHardened (loads in the host’s default AssemblyLoadContext but filesystem/process-spawn calls are interposed through IFilesystemPolicy/IProcessSpawnPolicy); Trusted → OutOfProcessOverlay (process sandbox + overlay filesystem, no OS confinement profile); Untrusted → OutOfProcessConfined (process sandbox + overlay filesystem + AppArmor/SELinux/Job Object, fail-closed on attach failure).
• Process sandboxing: StellaOps.Plugin.Sandbox ships ProcessSandbox (ISandbox/ISandboxFactory) for out-of-process plugins: IPluginProcessManager process management, OverlayFilesystemPolicy write redirection, NetworkPolicyEnforcer, Linux/Windows IResourceLimiter (CPU/memory/process/file-handle limits), LinuxAppArmorAttacher / ApparmorAuditLogScraper, 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 by leaf-certificate thumbprint allowlists (BuiltInSignerThumbprints / TrustedSignerThumbprints on PluginHostOptions); the pre-PSV-04 plain-text id/vendor allowlists are retained as [Obsolete] properties. AllowUnsignedPluginsInDevelopment (Development-only) and AllowMissingTrustRootBundle (boot escape hatch) 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). The PostgreSQL schema is platform with tables plugins, plugin_capabilities, plugin_instances (multi-tenant), and plugin_health_history (migration 001_CreatePluginTables.sql, applied by PluginRegistryMigrationRunner).
• 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.

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: agent hosts (Agent.Host, Agent.DeployNative/Compose, Agent.Build*), WebApi, 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
• Concelier / AdvisoryAI / Authority - *.Plugin.Unified plugin packs

Note: Integrations and Scanner consume the older src/__Libraries/StellaOps.Plugin/ shared host (sandbox-free), not the src/Plugin/ projects above. Treat their connector/analyzer plugins as consumers of that separate library.

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.