Workflows & Blueprints

Workflows let a MISP instance react automatically to things that happen inside it. When an event is saved, published, or about to be deleted — and at many other hook points — MISP can run a small graph of nodes that inspects the data and takes action: enrich it, tag it, publish it, push it to an external system, or even block the operation from completing. Workflows turn MISP from a passive store into an event-driven automation platform.

Warning

Workflows are an experimental feature and are site-admin only. They are powerful — a blocking workflow can prevent events from being saved or published — so treat them with the same care as any automation that sits in a critical path, and test thoroughly before enabling one on a production instance.

Concepts

A workflow is a directed graph made of three kinds of node:

  • Trigger — the single entry point. Each workflow is bound to exactly one trigger, which is a hook point in MISP core (for example event before-save, event publish, attribute after-save).
  • Logic — branching and filtering nodes. IF nodes fork the flow into a then and an else path based on a condition; filter nodes narrow the set of data flowing downstream.
  • Action — nodes that do something: enrich, tag, publish, add analyst data, push to ZMQ, call a webhook, send a Teams/Telegram message, stop execution, and many more.

Data enters at the trigger, flows through the logic and action nodes along the graph, and each node operates on a shared “roaming” copy of the data. The graph must be acyclic and have exactly one trigger.

Blocking vs non-blocking

This is the most important distinction to understand.

  • A non-blocking trigger fires after the core operation and runs asynchronously as a background job. The workflow’s outcome does not affect the operation that triggered it — it has already happened.
  • A blocking trigger fires before (or as part of) the core operation and runs synchronously. Its result is returned to the core code, which can then decide whether to proceed. A blocking workflow that reaches a Stop execution node causes the core operation to be aborted.

Only a handful of triggers are blocking. In MISP 2.5 these are:

  • event before-save — can prevent an event from being saved,
  • event before-delete — can prevent an event from being deleted,
  • event publish — can prevent an event from being published,
  • shadow-attribute before-save — can prevent a proposal from being saved,
  • user before-save — can prevent a user from being saved,
  • enrichment before-query — can prevent an enrichment query.

Every other trigger (attribute after-save, event after-save, sighting after-save, tag attached, object after-save, and so on) is non-blocking and runs in the background.

Note

The editor warns you if you place a blocking node (such as Stop execution) on a path fed by a non-blocking trigger — in that context it cannot actually block anything, it will just stop that branch of the workflow.

Enabling workflows

The feature has three prerequisites, all enforced when you open the Workflows UI:

  1. Background jobs must be enabled (MISP.background_jobs) — non-blocking workflows run as background jobs.
  2. The workflow plugin must be enabled (Plugin.Workflow_enable), under Administration → Server Settings & Maintenance → Plugin settings.
  3. Redis must be reachable — it stores the trigger routing and the set of enabled modules.

In addition, each trigger is disabled by default and has its own setting (Plugin.Workflow_triggers_<trigger-id>). A trigger only actually runs a workflow when it is both enabled and listened to by a saved workflow. This double gate means simply creating a workflow does not put it live — you also enable its trigger.

The workflow editor

Workflows are built in a drag-and-drop visual editor. You start from a trigger and connect logic and action nodes onto the canvas; each node has a small configuration form for its parameters (conditions, hash paths to the field being tested, tags to apply, webhook URLs, and so on). Some parameters support Jinja templating for dynamic values.

The editor validates the graph as you build it — checking that it is acyclic, that outputs are connected sensibly, and surfacing warnings such as blocking-node-on-non-blocking-path. You can also test a single module in isolation against sample input from the editor, which is the quickest way to confirm a node behaves as you expect before wiring it into a live workflow.

Supporting pages let you browse and manage the building blocks:

  • Triggers — the list of available triggers, filterable by scope, whether they are enabled, and whether they are blocking.
  • Modules — the catalogue of logic and action modules, where you enable or disable each module.
  • Workflows — your saved workflows.

Modules must be enabled

Not every module is available out of the box. Only a small default set is enabled — the common IF conditions (generic, distribution, published, organisation, tag), the concurrent-task node, Stop execution, Webhook and Push to ZMQ. Any other logic or action module (for example Enrich event, Attach warninglist, Tag operation, Attach decay score, Add analyst data, the messaging integrations) must be enabled in the module index before it can be used in a workflow.

Some action modules — such as sending mail, Jinja rendering, and service-provided actions — depend on a working misp-modules service and degrade gracefully if it is unavailable.

Ad-hoc workflows

Besides trigger-bound workflows, MISP supports ad-hoc workflows that you run manually rather than from a core hook. An ad-hoc workflow collects its input on demand — passed event IDs, a REST search, or roaming data supplied to it — and is useful for one-off curation runs or for testing a graph against real data. An action module also lets one workflow run another ad-hoc workflow.

Workflow Blueprints

A Workflow Blueprint is a reusable, saved fragment of a node graph. Blueprints are building blocks for the editor, not live automations: you drop a blueprint onto the canvas to reuse a proven pattern rather than rebuilding it node by node.

MISP ships a set of default blueprints covering common curation recipes — for example normalising TLP/PAP tags, assigning a country galaxy from enrichment, or removing the IDS flag on a warninglist hit. You can:

  • Import a blueprint from pasted JSON or an uploaded file,
  • Export a blueprint to JSON to share it, and
  • Update the default blueprints from the upstream misp-workflow-blueprints collection (matched by UUID, upgrading those with a newer upstream version).

Each blueprint shows a flowchart preview so you can see its shape before using it. Blueprints you create or edit are always saved as non-default.

Debugging and logs

Every workflow run is counted, and errors are always logged to the audit log and to app/tmp/logs/workflow-execution.log. For deeper inspection, each workflow has a debug toggle. With debugging on, MISP writes verbose, per-node execution messages and can POST execution snapshots (init, per-module exec, end) to an external debug receiver configured via Plugin.Workflow_debug_url. You can also execute a whole workflow manually with a supplied payload to observe its behaviour end-to-end.

Permissions and execution context

All workflow and blueprint actions are restricted to site administrators — there is no finer-grained role permission for workflows. Note also that a workflow executes as a system (host-organisation / admin) user, not as the user whose action triggered it; the initiating user is recorded separately for logging and for UI toast notifications. Keep this in mind when a workflow reads or modifies data — it is not limited by the triggering user’s distribution visibility.

API and CLI

Both workflows and blueprints are fully accessible over the REST API under the /workflows/ and /workflowBlueprints/ controllers (index, add, edit, delete, view, import/export, and the editor support actions). The view action can additionally emit the graph as Graphviz dot or Mermaid with ?format=dot / ?format=mermaid.

On the command line, the cake Workflow shell provides the entry points the background workers use — executeWorkflowForTrigger (run a trigger’s workflow), executeAdHocWorkflow (run an ad-hoc workflow), and walkGraph (execute a concurrent sub-branch as its own job). In normal operation these are invoked by MISP’s background job system rather than by hand.