Plugin System

Overview

The NetStacks Plugin System provides an extensible architecture for adding capabilities to the platform without modifying the core codebase. Plugins can add new ingestion sources, integrate with external platforms, extend the UI, and hook into system events like device discovery, alert creation, and configuration changes.

Plugin Capabilities

• Event hooks -- subscribe to system events (device added, config changed, alert fired) and execute custom logic
• Data ingestion -- create new ingestion endpoints for external data sources (webhooks, syslog, SNMP traps)
• External integrations -- connect NetStacks to third-party platforms (ITSM, monitoring, ticketing)
• UI extensions -- add custom panels, dashboard widgets, and menu items to the NetStacks interface
• API extensions -- register new API endpoints under the plugin namespace

How It Works

Plugin Architecture

Each plugin is a self-contained module with a manifest that declares its metadata, capabilities, dependencies, and configuration schema. The plugin runtime manages discovery, registration, lifecycle transitions, and inter-plugin communication.

Plugin Lifecycle

Capability Model

Plugins declare their capabilities in the manifest. The runtime validates that required capabilities are available before activating the plugin. Capabilities include:

• event:subscribe -- listen to system events
• event:emit -- emit custom events
• api:register -- register API endpoints
• ui:panel -- add UI panels
• data:ingest -- create ingestion endpoints
• integration:external -- connect to external APIs

Configuration Schema

Each plugin defines a JSON Schema for its configuration. The admin UI renders a configuration form from this schema, ensuring type-safe settings without custom UI code.

Step-by-Step Guide

Workflow 1: View Installed Plugins

1. Navigate to Administration → Plugins
2. View the list of installed plugins with their current state (Active, Disabled, Error)
3. Click a plugin to view its details, configuration, and health status

Workflow 2: Enable and Configure a Plugin

1. In the Plugins list, find the plugin you want to enable
2. Click Enable to transition from Installed to Enabled
3. Fill in the configuration form (e.g., API keys, endpoint URLs, notification settings)
4. Click Save & Start to activate the plugin
5. Verify the plugin status shows Active with a green health indicator

Workflow 3: Monitor Plugin Health

1. Navigate to Administration → Plugins
2. Check the health column -- green indicates healthy, yellow indicates degraded, red indicates error
3. Click a plugin to view detailed health metrics: uptime, events processed, last error, memory usage

Workflow 4: Disable or Uninstall a Plugin

1. Click the plugin and select Disable to stop it while preserving configuration
2. To remove completely, click Uninstall -- this removes the plugin files and configuration

Code Examples

Plugin Manifest

{
  "id": "alert-pipeline",
  "name": "Alert Pipeline",
  "version": "1.0.0",
  "description": "Ingest alerts from webhooks, syslog, and SNMP traps with rule-based routing",
  "author": "NetStacks",
  "license": "Enterprise",
  "capabilities": [
    "event:subscribe",
    "event:emit",
    "api:register",
    "ui:panel",
    "data:ingest"
  ],
  "dependencies": [],
  "config_schema": {
    "type": "object",
    "properties": {
      "webhook_port": { "type": "number", "default": 8443 },
      "syslog_enabled": { "type": "boolean", "default": false },
      "syslog_port": { "type": "number", "default": 514 },
      "snmp_trap_enabled": { "type": "boolean", "default": false },
      "snmp_trap_port": { "type": "number", "default": 162 }
    }
  }
}

Plugin Configuration via API

# Get plugin status
GET /api/v1/plugins/alert-pipeline

# Update plugin configuration
PUT /api/v1/plugins/alert-pipeline/config
Content-Type: application/json
{
  "webhook_port": 8443,
  "syslog_enabled": true,
  "syslog_port": 1514,
  "snmp_trap_enabled": true,
  "snmp_trap_port": 1162
}

# Enable plugin
POST /api/v1/plugins/alert-pipeline/enable

# Disable plugin
POST /api/v1/plugins/alert-pipeline/disable

Plugin Health Check

# Check plugin health
GET /api/v1/plugins/alert-pipeline/health

# Response
{
  "plugin_id": "alert-pipeline",
  "status": "active",
  "health": "healthy",
  "uptime_seconds": 86400,
  "metrics": {
    "events_processed": 12847,
    "events_per_minute": 8.9,
    "last_event": "2025-12-15T14:30:00Z",
    "errors_last_24h": 0,
    "memory_mb": 128
  }
}

Plugin Event Subscription

// Example: Plugin subscribing to system events
{
  "subscriptions": [
    {
      "event": "device.status.changed",
      "filter": { "status": "down" },
      "action": "create_alert"
    },
    {
      "event": "config.snapshot.diff",
      "filter": { "has_changes": true },
      "action": "notify_team"
    },
    {
      "event": "discovery.device.found",
      "action": "auto_classify"
    }
  ]
}

Q&A

Q: What plugins come pre-installed with NetStacks?

A: NetStacks Enterprise includes two first-party plugins: Alert Pipeline (for ingesting alerts from webhooks, syslog, and SNMP traps) and Incidents & ITSM (for ServiceNow and Jira Service Management integration). Both are installed but disabled by default -- enable them in Administration → Plugins.

Q: How do I enable or disable a plugin?

A: Navigate to Administration → Plugins, find the plugin, and click Enable or Disable. Enabling a plugin requires completing its configuration form. Disabling preserves the configuration so you can re-enable later without reconfiguring.

Q: What capabilities can plugins add?

A: Plugins can subscribe to and emit system events, register API endpoints, add UI panels and dashboard widgets, create data ingestion endpoints (webhooks, syslog, SNMP), and integrate with external platforms via their APIs.

Q: Can I develop custom plugins?

A: The plugin architecture is designed for extensibility. Custom plugin development requires a plugin manifest, capability declarations, and implementation of the plugin lifecycle interface. Contact NetStacks support for access to the plugin SDK and development documentation.

Q: How are plugin settings configured?

A: Each plugin defines a JSON Schema for its configuration. The admin UI renders a form from this schema. Settings can also be managed via the API at /api/v1/plugins/{id}/config. Configuration changes take effect after saving and may require a plugin restart.

Q: What happens to data when a plugin is disabled?

A: Disabling a plugin stops it from processing new events, but all existing data (alerts, incidents, configurations) is preserved in the database. When you re-enable the plugin, it resumes with its previous configuration and can access historical data.

Troubleshooting

Plugin Not Loading

• Check the plugin manifest for syntax errors -- invalid JSON will prevent loading
• Verify all declared dependencies are installed and active
• Review the system logs at Administration → Audit Logs for plugin initialization errors

Plugin Health Check Failures

• Click the plugin to view detailed error messages and stack traces
• Common causes: external API unreachable, invalid credentials, port conflicts (another service using the configured port)
• Try disabling and re-enabling the plugin to reset its state

Configuration Errors

• The configuration form validates against the plugin's JSON Schema. Fix any highlighted validation errors before saving
• For API-based configuration, ensure the JSON payload matches the expected schema

Plugin Conflicts

• Two plugins cannot listen on the same port -- check for port conflicts in plugin configurations
• If plugins subscribe to the same events, they process independently -- no conflicts occur at the event level

Related Features

• System Settings -- configure global settings that affect plugin behavior
• Alert Pipeline -- first-party plugin for alert ingestion and routing
• Incidents & ITSM -- first-party plugin for ServiceNow and Jira integration
• Task Monitoring -- monitor automated tasks triggered by plugin events