Skip to main content
Version: v0.9.0a2
Operator

Plugin Management

5 min readNode operatorPlugins · v0.9.0aN

What this guide covers

Operator workflow for installing, trusting, inspecting, auditing, and troubleshooting Stigmem plugins. Plugins are opt-in Python packages loaded at node startup through the stigmem.plugins entry point group. The default install runs without plugins.

Production deployments should keep plugin signing required, pin plugin package versions, and review every declared capability before rollout.

For author-facing package structure and examples, see the Plugin Author Guide. For security review inputs, see the Plugin Capability Reference.

Production workflow​

  1. Review the package. Confirm the plugin name, version, declared hooks, declared capabilities, dependencies, and signing identity.
  2. Install the package into the node environment. Use the same Python environment that runs stigmem so entry point discovery can find the plugin.
  3. Configure signing trust. Add accepted signing identities to STIGMEM_PLUGIN_TRUSTED_PUBLISHERS. Use the override list only for explicit, documented exceptions.
  4. Restart the node. Plugin discovery and registration are startup-only. There is no hot reload or runtime unload path in v0.9.0aN.
  5. Inspect registration and health. Use stigmem plugins list and stigmem plugins describe.
  6. Review audit events. Confirm registration, trust decision, and any handler denial or error events.

Install a plugin package​

For a source checkout:

python -m pip install /path/to/example-stigmem-plugin

For a pinned package:

python -m pip install 'example-stigmem-plugin==1.0.0'

For Docker deployments, build a derived image or otherwise install the plugin package into the container image used by the node. Avoid installing plugins manually inside a running container; that is not repeatable and will be lost on redeploy.

The package must expose an entry point in the stigmem.plugins group. Stigmem discovers those entry points, calls the manifest factory, resolves plugin dependencies, verifies signing/trust policy, and registers handlers during startup.

Configure signing and trust​

Production defaults are fail closed:

Setting
Production value
Purpose
STIGMEM_PLUGIN_SIGNING_REQUIRED
true
Reject unsigned or unverified plugins during startup registration.
STIGMEM_PLUGIN_TRUSTED_PUBLISHERS
comma list
Allow plugins signed by known publishers.
STIGMEM_PLUGIN_TRUST_OVERRIDE_PUBLISHERS
empty by default
Explicit audited exception list for signing identities not in the allowlist.

Example:

STIGMEM_PLUGIN_SIGNING_REQUIRED=true
STIGMEM_PLUGIN_TRUSTED_PUBLISHERS=builder@example.com,release-bot@example.com
STIGMEM_PLUGIN_TRUST_OVERRIDE_PUBLISHERS=

Use STIGMEM_PLUGIN_TRUST_OVERRIDE_PUBLISHERS only when you have a documented operational reason to accept a specific signing identity outside the normal allowlist. Override registration remains audit-visible with trust_decision=operator_override.

Development-only unsigned loading​

STIGMEM_PLUGIN_SIGNING_REQUIRED=false

Do not use this in production.

When disabled, unsigned plugin loading is warning-visible in logs and audit-visible with trust_decision=development_unsigned_override.

Inspect installed plugins​

stigmem plugins list

Example output:

example-stigmem-plugin 1.0.0 hooks=2 health=healthy signed_by=builder@example.com

For machine-readable output:

stigmem plugins list --json

Search the published plugin catalog:

stigmem plugins search tenant

Print install and enable commands for a known plugin:

stigmem plugins enable multi-tenant

Diagnose installed/enabled mismatches:

stigmem plugins doctor
stigmem doctor

Describe one plugin:

stigmem plugins describe example-stigmem-plugin

The describe command reports plugin name and version, signing identity, declared capabilities, registered hooks, dependencies, discovery source, and latest health status, message, and error summary when available.

Health checks​

health_check is a lifecycle callable on PluginManifest, not a hook. The operator CLI polls plugin health when listing or describing plugins. Health is informational in v0.9.0aN: unhealthy plugins remain registered and their handlers stay active until a future policy layer changes that behavior.

Status
Meaning
Notes
healthy
normal
Plugin reports normal operation.
degraded
partial
Plugin reports partial functionality or a recoverable problem.
unhealthy
serious
Plugin reports a serious problem.
unknown
no signal
No health check is available or health has not been reported.

Audit events to watch​

Plugin registration and handler outcomes are written as audit events. Query audit data through your normal audit pipeline. For the admin audit API, see Audit & Quotas.

Event type
Trigger
Meaning
plugin.registered
success
A plugin registered successfully. Metadata includes plugin name, hooks, capabilities, discovery source, signing identity, and trust decision when available.
plugin.registration_failed
failure
Registration failed: duplicate names, manifest validation, config validation, dependency, signing, or trust policy problems.
plugin.handler_denied
veto
A voting hook returned Deny. Metadata includes hook, handler name, plugin name, and reason.
plugin.handler_error
exception
A handler raised an exception. Metadata includes hook, handler name, plugin name, error type, and error summary.

For production alerts, watch for:

Any registration_failed

During deploy.

Any development_unsigned_override

Trust decision.

operator_override w/o change record

Without an approved change record.

Repeated handler_error

Unexpected capability additions

After a plugin upgrade.

Troubleshooting​

Symptom
Likely cause
Response
No plugins registered
discovery miss
Confirm the package is installed in the same environment as stigmem; verify the package declares [project.entry-points."stigmem.plugins"]; restart the node.
Startup fails: unsigned plugin
signing required
Use a signed package from a trusted publisher. Disable signing only in local development.
Startup fails: signed by untrusted identity
not in allowlist
Add the identity to the trusted-publisher list after review, or use the override list for a documented exception.
Startup fails: duplicate plugin name
collision
Remove one package or upgrade to packages with unique names.
Startup fails: missing dependency
depends_on
Install the dependency plugin or remove the dependent plugin.
Handler fails: CapabilityError
capability mismatch
Treat as a plugin bug. Upgrade, disable, or request a corrected manifest.
Health degraded / unhealthy
plugin reported
Run stigmem plugins describe <name> --json; review health_message and health_error; check plugin logs and audit events.

Upgrade and rollback checklist​

Before upgrading a plugin:

  1. Read the release notes and compare the new manifest to the old one.
  2. Review added hooks and capabilities.
  3. Confirm the signing identity is expected.
  4. Deploy first in a non-production environment with production-like signing settings.
  5. Capture stigmem plugins describe <name> --json before and after the upgrade.

To roll back, reinstall the previous pinned plugin version and restart the node.

Because registration is startup-only, a restart is required for the old handlers to replace the new ones.