# Plugin Architecture & Extensibility Patterns **Version:** 1.0 **Date:** 2025-11-28 **Status:** Canonical This advisory consolidates the extensibility patterns used across Stella Ops modules, providing a unified view for architects and developers implementing custom integrations. --- ## 1. Overview Stella Ops uses a **plugin-based architecture** enabling customers and partners to extend functionality without modifying core code. The platform supports three primary extension types: | Type | Module | Purpose | Examples | |------|--------|---------|----------| | **Connectors** | Concelier, Excititor | Ingest/export data from external sources | NVD, OSV, vendor VEX feeds | | **Plugins** | Authority, Scanner | Extend runtime behavior | LDAP auth, custom analyzers | | **Analyzers** | Scanner | Add detection capabilities | Language-specific, binary analysis | --- ## 2. Core Principles ### 2.1 Determinism All plugins must produce **deterministic outputs** for identical inputs: - No global state between invocations - Timestamps in UTC ISO-8601 - Stable ordering of collections - Reproducible hashing with documented algorithms ### 2.2 Offline-First Plugins must function in **air-gapped environments**: - No network access unless explicitly configured - Local configuration and secrets - Bundled dependencies (no runtime downloads) - Offline-capable credential stores ### 2.3 Restart-Safe Plugins load at **service startup only**: - No hot-reload (security/determinism trade-off) - Configuration changes require restart - State persists in external stores (MongoDB, filesystem) --- ## 3. Plugin Lifecycle ``` ┌─────────────────────────────────────────────────────────────────┐ │ Host Startup │ └─────────────────────────────────┬───────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 1. Configuration Load │ │ - Read YAML manifests from etc/.plugins/ │ │ - Validate capability tokens │ │ - Resolve relative paths │ └─────────────────────────────────┬───────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 2. Assembly Discovery │ │ - Scan plugin binaries directory │ │ - Match assemblies to manifest descriptors │ │ - Load assemblies into isolated context │ └─────────────────────────────────┬───────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 3. Registrar Execution │ │ - Find IPluginRegistrar implementations │ │ - Bind options from configuration │ │ - Register services in DI container │ │ - Queue bootstrap tasks (optional) │ └─────────────────────────────────┬───────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ 4. Runtime │ │ - Host resolves plugin services via DI │ │ - Capability metadata guides feature exposure │ │ - Health checks report plugin status │ └─────────────────────────────────────────────────────────────────┘ ``` --- ## 4. Concelier Connectors ### 4.1 Purpose Connectors ingest vulnerability advisories from external sources into the Concelier merge engine. ### 4.2 Interface ```csharp public interface IAdvisoryConnector { string ConnectorId { get; } Task> FetchAsync( ConnectorContext context, CancellationToken ct); Task CheckHealthAsync(CancellationToken ct); } ``` ### 4.3 Built-in Connectors | Connector | Source | Format | |-----------|--------|--------| | `nvd` | NVD API 2.0 | CVE JSON | | `osv` | OSV.dev | OSV JSON | | `ghsa` | GitHub Advisory Database | GHSA JSON | | `oval` | Vendor OVAL feeds | OVAL XML | | `csaf` | CSAF repositories | CSAF JSON | ### 4.4 Developer Guide See: `docs/dev/30_EXCITITOR_CONNECTOR_GUIDE.md` --- ## 5. Authority Plugins ### 5.1 Purpose Authority plugins extend authentication with custom identity providers, credential stores, and client management. ### 5.2 Interface ```csharp public interface IAuthorityPluginRegistrar { void ConfigureServices(IServiceCollection services, PluginContext context); void ConfigureOptions(IConfiguration config); } public interface IIdentityProviderPlugin { string ProviderId { get; } AuthorityIdentityProviderCapabilities Capabilities { get; } Task AuthenticateAsync(AuthenticationRequest request); } ``` ### 5.3 Capabilities Plugins declare capabilities via manifest: ```yaml plugins: descriptors: ldap: assemblyName: "StellaOps.Authority.Plugin.Ldap" capabilities: - password - mfa - clientProvisioning ``` | Capability | Description | |------------|-------------| | `password` | Username/password authentication | | `mfa` | Multi-factor authentication support | | `clientProvisioning` | Dynamic OAuth client registration | | `bootstrap` | Initial admin user creation | ### 5.4 Developer Guide See: `docs/dev/31_AUTHORITY_PLUGIN_DEVELOPER_GUIDE.md` --- ## 6. Scanner Analyzers ### 6.1 Purpose Analyzers extend the Scanner with language-specific or binary-level detection capabilities. ### 6.2 Interface ```csharp public interface IScanAnalyzer { string AnalyzerId { get; } IReadOnlyList SupportedEcosystems { get; } Task AnalyzeAsync( ScanContext context, IAsyncEnumerable artifacts, CancellationToken ct); } ``` ### 6.3 Built-in Analyzers | Analyzer | Ecosystem | Detection Method | |----------|-----------|------------------| | `syft` | Multi-ecosystem | SBOM generation | | `grype-db` | Multi-ecosystem | Vulnerability matching | | `elf-symbols` | Binary/ELF | Symbol table analysis | | `buildid` | Binary/ELF | Build-ID extraction | | `dotnet-deps` | .NET | deps.json parsing | ### 6.4 Surface Validation The Scanner supports **extensible surface validation** for detecting risky patterns: ```csharp public interface ISurfaceValidator { string ValidatorId { get; } Task ValidateAsync( SurfaceContext context, CancellationToken ct); } ``` See: `docs/modules/scanner/guides/surface-validation-extensibility.md` --- ## 7. Manifest Structure All plugins use a standard manifest format: ```json { "pluginId": "example-plugin", "version": "1.0.0", "assemblyName": "StellaOps.Module.Plugin.Example", "hostVersion": ">=2.0.0", "capabilities": ["capability1", "capability2"], "configuration": { "requiredSettings": ["setting1"], "optionalSettings": ["setting2"] }, "dependencies": { "packages": ["Dependency.Package@1.0.0"] } } ``` --- ## 8. Security Considerations ### 8.1 Assembly Isolation - Plugins load in dedicated assembly contexts - Host enforces capability-based access control - Network access requires explicit configuration ### 8.2 Configuration Validation - Unknown capability tokens rejected at startup - Path traversal in relative paths blocked - Secrets never logged or exposed in diagnostics ### 8.3 Audit Trail - Plugin loading events logged with assembly hash - Configuration changes recorded - Runtime errors captured with context --- ## 9. Offline Kit Integration Plugins must support offline distribution: ``` offline-kit/ ├── plugins/ │ ├── authority/ │ │ ├── StellaOps.Authority.Plugin.Ldap.dll │ │ └── manifest.json │ ├── scanner/ │ │ ├── StellaOps.Scanner.Analyzer.Custom.dll │ │ └── manifest.json │ └── checksums.sha256 ├── config/ │ └── plugins.yaml └── MANIFEST.json ``` ### 9.1 Checksum Verification All plugin assemblies verified against `checksums.sha256` before loading. ### 9.2 Version Compatibility Host rejects plugins with incompatible `hostVersion` requirements. --- ## 10. Testing Requirements ### 10.1 Unit Tests - Registrar binds options correctly - Services resolve from DI container - Capability metadata accurate ### 10.2 Integration Tests - Plugin loads in host process - Health checks pass - Functionality works end-to-end ### 10.3 Test Helpers ```csharp // Use StellaOps.Plugin.Tests helpers var host = new PluginTestHost() .WithPlugin() .WithConfiguration(config) .Build(); var plugin = host.GetRequiredService(); var result = await plugin.DoSomethingAsync(); ``` --- ## 11. Related Documentation | Resource | Location | |----------|----------| | General plugin guide | `docs/dev/plugins/README.md` | | Concelier connector guide | `docs/dev/30_EXCITITOR_CONNECTOR_GUIDE.md` | | Authority plugin guide | `docs/dev/31_AUTHORITY_PLUGIN_DEVELOPER_GUIDE.md` | | Scanner extensibility | `docs/modules/scanner/guides/surface-validation-extensibility.md` | | Platform architecture | `docs/modules/platform/architecture-overview.md` | --- ## 12. Sprint Mapping No dedicated sprint - plugin infrastructure is foundational. Related tasks appear in: - Module-specific sprints (Authority, Scanner, Concelier) - Platform infrastructure sprints --- ## 13. Success Metrics | Metric | Target | |--------|--------| | Plugin load time | < 500ms per plugin | | Configuration validation | 100% coverage of manifest schema | | Offline kit verification | All plugins checksum-verified | | Documentation coverage | All plugin types documented | --- *Last updated: 2025-11-28*