Merge branch 'plugin-docs' into 'main'

Plugin documentation See merge request reportcreator/reportcreator!775
Syslifters · Nov 25, 2024 · 58bb98f · 58bb98f
2 parents 4a0ba64 + fb2a445
commit 58bb98f
Show file tree

Hide file tree

Showing 9 changed files with 128 additions and 0 deletions.
diff --git a/docs/docs/features-and-pricing.md b/docs/docs/features-and-pricing.md
@@ -12,6 +12,7 @@
 | [__Data Encryption at rest__](setup/configuration.md#data-encryption-at-rest){ target=_blank } | <span style="color:green;font-weight:bold;">✓</span>                                                          | <span style="color:green;font-weight:bold;">✓</span>                                                                                                                  |
 | [__MFA (FIDO/WebAuthn, TOTP)__](show-and-tell/posts/2fa.md){ target=_blank }      | <span style="color:green;font-weight:bold;">✓</span>                                                          | <span style="color:green;font-weight:bold;">✓</span>                                                                                                                  |
 | [__Note Taking__](show-and-tell/posts/note-taking.md){ target=_blank }           | <span style="color:green;font-weight:bold;">✓</span>                                                          | <span style="color:green;font-weight:bold;">✓</span>                                                                                                                  |
+| [__Plugins__](setup/plugins.md){ target=_blank }             | <span style="color:green;font-weight:bold;">✓</span>                                                          | <span style="color:green;font-weight:bold;">✓</span>                                                                                                                  |
 | [__Comments__](show-and-tell/posts/comments.md){ target=_blank }                                        | <span style="color:red;font-weight:bold;">X</span>                                                            | <span style="color:green;font-weight:bold;">✓</span>                                                                                                                  |
 | [__Version History__](reporting/version-history.md){ target=_blank }                                        | <span style="color:red;font-weight:bold;">X</span>                                                            | <span style="color:green;font-weight:bold;">✓</span>                                                                                                                  |
 | [__Concurrent Editing__](show-and-tell/posts/concurrent-editing.md){ target=_blank }                                        | <span style="color:red;font-weight:bold;">X</span>                                                            | <span style="color:green;font-weight:bold;">✓</span>                                                                                                                  |

diff --git a/docs/docs/setup/configuration.md b/docs/docs/setup/configuration.md
@@ -319,3 +319,14 @@ This setting sould only be activated if WebSockets are blocked by a firewall or
 ``` title="Example:"
 DISABLE_WEBSOCKETS=true
 ```
+
+### Plugins
+Extend the functionality of SysReptor by enabling plugins. Plugins are disabled by default and need to be explicitly enabled.
+`ENABLED_PLUGINS` is a comma separated list of plugin names or plugin IDs.
+
+``` title="Example:"
+ENABLED_PLUGINS="cyberchef,graphqlvoyager,checkthehash"
+```
+
+Some plugins require additional configuration. These plugin settings are configured as separate entries in `app.env`.
+Please refer to the plugin documentation for more information on available plugin setting.
diff --git a/docs/docs/setup/plugins.md b/docs/docs/setup/plugins.md
@@ -0,0 +1,30 @@
+# Plugins
+<span style="color:orange;">:octicons-alert-fill-24: Experimental. Expect breaking changes.</span>
+
+The functionality of SysReptor can be extended by plugins. 
+Plugins can hook into the SysReptor core and provide additional features both in the API and the web UI.
+
+All plugins are disabled by default. To enable a plugin, add it to the [`ENABLED_PLUGINS`](./configuration.md#plugins) setting.
+
+
+## Official Plugins
+
+Official plugins are maintained by the SysReptor team and are included in official docker images.
+
+| Plugin | Description | 
+| ------ | ----------- |
+| [cyberchef](https://github.com/Syslifters/sysreptor/tree/main/plugins/cyberchef) | CyberChef integration |
+| [graphqlvoyager](https://github.com/Syslifters/sysreptor/tree/main/plugins/graphqlvoyager) | GraphQL Voyager integration |
+| [checkthehash](https://github.com/Syslifters/sysreptor/tree/main/plugins/checkthehash) | Hash identifier |
+| [customizetheme](https://github.com/Syslifters/sysreptor/tree/main/plugins/customizetheme) | Customize UI themes per instance |
+| [demoplugin](https://github.com/Syslifters/sysreptor/tree/main/plugins/demoplugin) | A demo plugin that demonstrates the plugin system |
+| [projectnumber](https://github.com/Syslifters/sysreptor/tree/main/plugins/projectnumber) | Automatically adds an incremental project number to new projects |
+| [webhooks](https://github.com/Syslifters/sysreptor/tree/main/plugins/webhooks) | Send webhooks on certain events |
+
+
+<!--
+## Custom Plugins
+It is possible to develop and load custom plugins.
+
+The plugin system is currently experimental. Expect breaking changes anytime. Use at own risk.
+-->
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -10,6 +10,7 @@ nav:
       - Setup Webserver: setup/webserver.md
       - Updates: setup/updates.md
       - Backups: setup/backups.md
+      - Plugins: setup/plugins.md
       - Upgrade to PRO: setup/upgrade-to-professional.md
   - Writing Reports:
       - Markdown Syntax: reporting/markdown-features.md

diff --git a/plugins/checkthehash/README.md b/plugins/checkthehash/README.md
@@ -0,0 +1,2 @@
+# Hash Identifier Plugin
+Identify hash possible hash types
diff --git a/plugins/customizetheme/README.md b/plugins/customizetheme/README.md
@@ -0,0 +1,61 @@
+# Customize Theme
+
+This plugin allows to customize the theme of the SysReptor frontend.
+It allows to change settings of light and dark globally per instance.
+
+
+
+## Configuration
+`PLUGIN_CUSTOMIZETHEME_CONFIG` accepts a JSON object with theme configs. 
+The provided configurations override the [default theme configs](../../packages/nuxt-base-layer/src/vuetify.config.ts).
+All theme configurations provided by Vuetify are supported. See the [Vuetify documentation](https://vuetifyjs.com/en/features/theme/) for more information.
+Options in `all` apply to both light and dark mode. Options in `light` and `dark` apply to the respective mode only.
+
+```
+ENABLED_PLUGINS="customizetheme"
+PLUGIN_CUSTOMIZETHEME_CONFIG='{"light": {...}, "dark": {...}, "all": {...}}'
+```
+
+
+## Examples
+### Custom Risk Colors
+You want to use the same colors for risk levels in the web UI as in the report PDFs?
+
+```json
+{
+  "all": {
+    "colors": {
+       "risk-critical": "#8c00fc",
+       "risk-high": "#ed0003",
+       "risk-medium": "#f0d400",
+       "risk-low": "#009dff",
+       "risk-info": "#00bc00"
+    }
+  }
+}
+```
+
+### Headers in Corporate Colors
+```json
+{
+  "all": {
+    "colors": {
+      "header": "#ff00ff"
+    }
+  }
+}
+```
+
+### Matrix Dark Theme
+```json
+{
+  "dark": {
+    "colors": {
+      "on-background": "#74ee15",
+      "on-surface": "#74ee15",
+      "on-drawer": "#74ee15",
+      "on-header": "#74ee15"
+    }
+  }
+}
+```
diff --git a/plugins/cyberchef/README.md b/plugins/cyberchef/README.md
@@ -0,0 +1,6 @@
+# CyberChef Plugin
+Integrate CyberChef into SysReptor.
+
+```
+ENABLED_PLUGINS="cyberchef"
+```
diff --git a/plugins/demoplugin/README.md b/plugins/demoplugin/README.md
@@ -0,0 +1,10 @@
+# Demoplugin
+
+This is a demo plugin that demonstrates the plugin system.
+Use this plugin as a reference to develop your own plugins.
+
+Plugins are loaded as [Django apps](https://docs.djangoproject.com/en/5.1/ref/applications/). Plugins can add API endpoints, views, models, admin pages, signal handlers, and more.
+Data can be stored in the database via Django models. Migrations are supported.
+
+Plugins can extend the frontend by adding pages and menu entries. Each frontend plugin provides an entrypoint script named [`plugin.js`](./frontend/public/plugin.js) as static file. This script is called when the web application is loaded in the browser and performs the necessary plugin setup (e.g. register new routes, add menu entries, etc.).
+Plugin pages are loaded as iframes. This allows you to develop frontend plugins with any frontend framework you like, add custom dependencies, or include existing third-party applications.
diff --git a/plugins/graphqlvoyager/README.md b/plugins/graphqlvoyager/README.md
@@ -0,0 +1,6 @@
+# GraphQL Voyager Plugin
+Integrate GraphQL Voyager into SysReptor.
+
+```
+ENABLED_PLUGINS="graphqlvoyager"
+```
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		# Hash Identifier Plugin
		Identify hash possible hash types