diff --git a/docs/docs/features-and-pricing.md b/docs/docs/features-and-pricing.md index 4dcfec1e4..dd2add019 100755 --- 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 } | ✓ | ✓ | | [__MFA (FIDO/WebAuthn, TOTP)__](show-and-tell/posts/2fa.md){ target=_blank } | ✓ | ✓ | | [__Note Taking__](show-and-tell/posts/note-taking.md){ target=_blank } | ✓ | ✓ | +| [__Plugins__](setup/plugins.md){ target=_blank } | ✓ | ✓ | | [__Comments__](show-and-tell/posts/comments.md){ target=_blank } | X | ✓ | | [__Version History__](reporting/version-history.md){ target=_blank } | X | ✓ | | [__Concurrent Editing__](show-and-tell/posts/concurrent-editing.md){ target=_blank } | X | ✓ | diff --git a/docs/docs/setup/configuration.md b/docs/docs/setup/configuration.md index 0ab395ab1..9efd1c925 100644 --- 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 new file mode 100644 index 000000000..0a9773232 --- /dev/null +++ b/docs/docs/setup/plugins.md @@ -0,0 +1,30 @@ +# Plugins +:octicons-alert-fill-24: Experimental. Expect breaking changes. + +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 | + + + diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index c4c6d5d7e..861b36333 100755 --- 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 new file mode 100644 index 000000000..4322fb633 --- /dev/null +++ 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 new file mode 100644 index 000000000..e33a4058c --- /dev/null +++ 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 new file mode 100644 index 000000000..73cb734db --- /dev/null +++ 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 new file mode 100644 index 000000000..edec8046d --- /dev/null +++ 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 new file mode 100644 index 000000000..59b1cfad7 --- /dev/null +++ b/plugins/graphqlvoyager/README.md @@ -0,0 +1,6 @@ +# GraphQL Voyager Plugin +Integrate GraphQL Voyager into SysReptor. + +``` +ENABLED_PLUGINS="graphqlvoyager" +```