How do I install the CyberPanel plugin?

The plugin is a user interface, not a second scanner. The broker and its workers keep running when the panel is down, being upgraded or broken.

Before you install

The Shelltrap broker must be running, /run/shelltrap/api.sock must exist, and CyberPanel must be installed:

test -S /run/shelltrap/api.sock
shelltrap health

Install

cd /usr/local/CyberCP
/usr/local/CyberCP/bin/python /usr/local/CyberCP/pluginInstaller/pluginInstaller.py \
  install --pluginName shelltrap

CyberPanel's own installer patches core files by inserting lines, and its hook calls ignore exit codes — a failed preflight cannot stop it from claiming success. The plugin therefore checks itself: pre_install writes a root-owned transaction marker at /var/lib/shelltrap/plugin-install-transaction.json with atomic snapshots of the three core files, and post_install evaluates that marker regardless of what the native installer printed. The result is written to /var/lib/shelltrap/plugin-status.json. An unreachable or degraded broker is never marked healthy.

cat /var/lib/shelltrap/plugin-status.json

What the plugin adds

Dashboard and health, findings with filters, paging, detail and signals, quarantine with restore (purge for administrators only), policies per domain with visible global → account → domain inheritance, ignore lists, feed generations, audit (administrators only), jobs, and a help and status page. Every signal display carries author, source and licence attribution where the rule provides them.

Roles

• Administrator — all sites, findings, jobs, policies, feeds, audit and quarantine; may change policies, ignores, feed actions, finding resolutions and quarantine purge.
• Reseller — own sites and their objects, restore within that scope, and the released policy keys of their own domains.
• Customer — own sites and their objects, restore within that scope, and the released policy keys of their own domains.

upload.on_error and heuristics.action stay locked for resellers and customers at all times, and the broker enforces that boundary independently of the user interface. Bulk editing across several domains is offered to administrators only.

After a CyberPanel upgrade

A panel upgrade can rewrite the same core files. The repair script is idempotent and can be run on its own:

/usr/local/CyberCP/shelltrap/repair.sh

It restores exactly one shelltrap entry in INSTALLED_APPS, exactly one URL entry and exactly one sidebar link, and it never deletes lines it did not write. Messages about symlinks, hard links or an unexpected structure need a human — do not patch lines on suspicion.

Removal

/usr/local/CyberCP/bin/python /usr/local/CyberCP/pluginInstaller/pluginInstaller.py \
  remove --pluginName shelltrap

Removing the plugin stops no broker service and deletes no findings, quarantine, configuration, logs or broker database. More detail: the plugin documentation.