# Plugin Framework

> Universal extensibility framework providing plugin lifecycle management, sandboxing, registry, and SDK for building Stella Ops plugins.

## Purpose

The Plugin Framework is a foundational library that provides a consistent plugin lifecycle, trust-based sandboxing, and a registry for managing plugins across all Stella Ops modules. It enables any module to be extended with third-party or custom logic while maintaining security boundaries and operational visibility.

## Quick Links

- [Architecture](./architecture.md) - Technical design and implementation details

## Status

| Attribute | Value |
|-----------|-------|
| **Maturity** | Production |
| **Source** | `src/Plugin/` |

## Key Features

- **IPlugin interface and lifecycle:** Standard contract for all plugins with well-defined states (Discovery, Loading, Initialization, Active, Shutdown)
- **Trust levels:** Three-tier trust model -- BuiltIn (in-process), Trusted (isolated with monitoring), Untrusted (sandboxed in separate process)
- **Process sandboxing:** Untrusted plugins run in isolated processes with gRPC IPC for communication
- **Plugin registry:** Persistent catalog of installed plugins with version tracking (InMemory for tests, PostgreSQL for production)
- **SDK and test utilities:** `Plugin.Sdk` for plugin authors, `Plugin.Testing` for deterministic test harnesses
- **Capability declarations:** Plugins declare their capabilities; the host enforces capability restrictions at runtime

## Dependencies

### Upstream (this module depends on)
- None (foundational library with no upstream module dependencies)

### Downstream (modules that depend on this)
- **Integrations** - Uses plugin framework for connector plugins (GitHub, GitLab, Harbor)
- **Scanner** - Scanner analysis plugins
- **Policy** - Policy evaluation plugins
- **Orchestrator** - Worker plugins and task runner extensions

## Related Documentation

- [Integrations](../integrations/) - Primary consumer of plugin framework
- [Scanner](../scanner/) - Uses plugins for analysis extensibility