Plugin pipelines

Plugin pipelines run installed plugins in response to events such as a downloadable file being created. Downloads expose applicable checks, attempt history, and safe diagnostics in a public Pipelines tab.

Configure a pipeline

Open Admin → Plugins → Pipelines. The visual and YAML editors both save the same ordered configuration.

Installing and enabling a plugin makes it available to pipeline editors. It does not make the plugin run automatically. An event must have an explicit pipeline with at least one enabled, compatible plugin step.

Server pipelines currently support these events:

Event	When it runs
downloadableFile.created	A downloadable file is uploaded.
downloadableFile.updated	A downloadable file is replaced or modified.
downloadableFile.downloaded	A download request needs a fresh check.
comment.created	A comment is created.

For example:

pipelines:
  - event: downloadableFile.created
    applicability: NEW_FILES_ONLY
    stopOnFirstFailure: true
    steps:
      - plugin: security-attachment-scan
        condition: ALWAYS
        continueOnError: false

Each step can optionally pin a plugin version. Without a version, Multiforum uses the latest enabled version. Conditions can be ALWAYS, PREVIOUS_SUCCEEDED, or PREVIOUS_FAILED.

Server and channel scope

Server and channel pipelines are separate, explicit policies:

• server pipelines handle server-wide concerns such as file security checks;
• channel pipelines handle discussionChannel.created and comment.created for that channel;
• a channel owner can only select plugins installed and enabled by a server administrator;
• a channel cannot disable or bypass a server pipeline;
• if no server pipeline is configured for an event, channels are not silently opted into every enabled plugin.

For a discussion with an attachment, server file checks run before channel automation. If the same security scanner is present at both scopes, Multiforum reuses the applicable result instead of scanning the same attachment twice.

Visibility and permissions

People who can view content can also view its applicable pipeline, attempts, job statuses, and public diagnostics. Permissions control actions rather than hiding ordinary check history:

• the original uploader can start missing required checks and retry eligible failed, timed-out, or cancelled attempts;
• channel moderators with permission to edit discussions can start or retry checks for downloads in that channel;
• security reviewers with the server's permanent-removal permission can release a quarantined file after recording an audit reason;
• administrators with plugin-management permission can inspect internal operational logs.

Internal logs are separate from public diagnostics and may contain information that must not be published.

Adding a required check

When enabling a check for a forum that already contains downloads, choose a rollout policy explicitly.

Policy	Behavior
New files only	Recommended default. Existing file versions are not required; new and replacement files must pass.
All files, gradual	New files are enforced immediately and existing files enter a controlled backfill campaign.
All files, immediate	Every applicable existing file is held until it passes. This requires explicit confirmation.

“New” is based on the uploaded file-version timestamp relative to the policy's effective time, not the date of a later discussion edit. Replacing a binary always creates a new version.

The chosen policy and applicability decision are recorded with attempts, so later configuration changes do not rewrite history.

Existing-file campaigns

Before starting a gradual or immediate rollout, review the campaign preview:

• number of affected files;
• whether stored files are still accessible;
• estimated provider usage;
• enforcement behavior.

Configure concurrency and rate limits appropriate for the plugin provider. Campaigns can be paused and resumed. The campaign view reports completed, running, failed, and timed-out totals and links to affected attempts.

Each generated attempt retains its policy and campaign IDs for auditability.

Security scanning and quarantine

To require malware scanning across the server:

1. Install and enable security-attachment-scan.
2. Configure its provider secret and settings.
3. Add it to the server downloadableFile.created pipeline.
4. Choose the rollout policy deliberately.
5. Save the pipeline and review the campaign preview if existing files apply.

Because this is a server pipeline, individual channels cannot turn it off. To make scanning optional per channel, omit the server pipeline and configure the scanner only in the channels that require it.

A file is logically quarantined while its scan is PENDING, SUSPICIOUS, INFECTED, or FAILED. Direct download is disabled. A successful scan changes the status to CLEAN and makes the file available. Replacing a clean file puts the new version back into quarantine until its own check passes.

The Admin Dashboard includes the Download security review queue for SUSPICIOUS, INFECTED, and FAILED files. Reviewers should:

1. open the download and its public pipeline history;
2. read the scanner finding and any creator review request;
3. retry transient failures instead of overriding them;
4. ask the uploader to replace files that genuinely contain a threat;
5. release quarantine only when there is sufficient evidence, entering a specific audit reason.

Releasing quarantine records the reviewer and reason, marks the file clean, and notifies the uploader. It does not erase the scanner's pipeline attempt.

Recovery and monitoring

Pipeline attempts use execution leases and heartbeats. A scheduled watchdog marks expired jobs Timed out, computes the attempt's terminal status, and releases the active-attempt lock. An uploader or authorized moderator can then retry safely.

The server dashboard surfaces:

• queue age;
• timeout rates;
• repeated failures;
• retry storms.

Investigate persistent provider or configuration errors in the internal plugin logs. Do not copy internal logs into public diagnostics without reviewing and redacting them.

Retry safeguards

Only one attempt may be active for the same target, event, scope, and file version. Whole-pipeline retries use the current enabled configuration and preserve the original attempt. The default safeguards include a one-minute cooldown and no more than three retries for a target pipeline in a rolling hour.

Public diagnostic codes

These codes are currently published by first-party checks:

Code	Meaning	Typical next step
SCAN_COMPLETE	The provider completed its scan.	No action is needed.
SCAN_NOT_APPLICABLE	The event contained no attachments to scan.	No action is needed.
SCAN_SUSPICIOUS	The scan found content that needs review.	Inspect the diagnostic and adjust the archive if needed.
SCAN_MALWARE_DETECTED	The scan detected a threat.	Remove the affected file before retrying.
SCAN_PROVIDER_ERROR	The scan provider could not complete the request.	Retry later; investigate if it repeats.
SCAN_CONFIGURATION_REQUIRED	Required scan configuration is missing.	Configure the scan plugin.
ARCHIVE_CONTAINS_EXECUTABLE	An archive contains an executable file.	Remove it or explain why it is required.
PLUGIN_VERSION_REQUIRES_NEWER_SERVER	The plugin requires a newer server.	Update the server.
PLUGIN_API_VERSION_UNSUPPORTED	The plugin uses an unsupported API contract.	Install a compatible plugin version.

Codes keep the same meaning once published. Plugins may add fields to diagnostic details, but consumers should not depend on undocumented fields.

See Publishing public pipeline diagnostics for the plugin author contract.