Build a plugin

Plugins are declarative

If you have used other monitoring tools you may expect imperative code hooks like on_device_discovered() or on_scan_complete(). InSpectre's equivalent is the declarative event-hooks map: you bind an InSpectre event to a named action the engine runs. This keeps community plugins safe to share — a manifest can only make the network calls it declares, against credentials the user explicitly enters.

Quick start

• Copy examples/plugins/TEMPLATE.yaml (or the JSON hello-world.json).
• Set a unique lowercase id, then edit config_schema, endpoints and actions to match your target API.
• In InSpectre: Settings → Plugins → Upload Plugin, choose your file.
• Open the plugin, fill in config, click Test Connection.
• Toggle Enabled. Polling starts on the next cycle; blocking plugins become selectable under Settings → Security Responses → Blocking Method.

A minimal discovery plugin is just an endpoint, one action, and a polling block:

{
  "id": "my-router",
  "name": "My Router",
  "version": "1.0.0",
  "capabilities": ["discovery"],
  "config_schema": [
    { "key": "host", "label": "Base URL", "type": "url", "default": "http://192.168.0.1", "required": true },
    { "key": "api_key", "label": "API Key", "type": "password", "default": "", "required": true }
  ],
  "endpoints": { "base_url": "{host}", "auth": "api-key-header", "api_key_header": "X-API-Key" },
  "actions": {
    "get_leases": {
      "method": "GET",
      "path": "/api/dhcp/leases",
      "response_mapping": { "root_path": "leases",
        "fields": { "mac": "mac_address", "ip": "ip_address", "name": "hostname" } }
    }
  },
  "polling": { "action": "get_leases", "interval_seconds": 120 }
}

Manifest reference

Capabilities

Declare what your plugin genuinely does — the engine uses these to decide which flows it joins. Only discovery/presence plugins have poll results written to the inventory; only blocking plugins appear as block methods.

Config schema

Each entry renders a field in the plugin's config form. Values become {key} placeholders usable in endpoints and actions.

Field types: string, password, integer, boolean, select, multiline, url, filepath.

• password values are encrypted at rest (Fernet, derived from the server SECRET_KEY) and shown as **redacted** when reading config back via the API.
• multiline renders a textarea (e.g. a newline-separated keyword list).
• filepath is a container-internal path — mount the file into the backend container via volumes:.

Event hooks

Bind an InSpectre event to an action. When the event fires, the engine runs the action asynchronously (fire-and-forget) for every enabled plugin that declares a matching hook.

"event_hooks": {
  "device.new":     "notify_action",
  "vuln.critical":  "notify_action",
  "device.offline": "notify_action"
}

Polling

Run action(s) on a schedule. Results are upserted into the inventory when the plugin has discovery or presence capability.

The blocking contract

A blocking plugin must declare block_client and unblock_client actions. Once enabled, it becomes selectable under Settings → Security Responses → Blocking Method, and the blocking coordinator calls those actions directly when you block or unblock a device. Blocking actions emit device.blocked / device.unblocked events on success, and may use read-modify-write list directives for APIs that take an allow/deny list.

Built-in plugins

The shipped manifests in backend/plugins/builtin/ are the best real-world examples — read them alongside this guide.

Install & test

A note on safety

Because a plugin is just a manifest, it can only perform the network operations it declares, against the endpoints and credentials you enter. There is no arbitrary code execution inside the backend. That said, community plugins are not audited by the InSpectre project — review a manifest before uploading it, the same way you would any config that holds your credentials.