Merge branch '366-update-documentation' into 'main'

Resolve "SysReptor Documentation"

Closes #366

See merge request reportcreator/reportcreator!807

.gitlab-ci.yml

@@ -306,7 +306,7 @@ release-prod:
 
     # Send notification for new release
     - >
-      curl https://cloud.sysreptor.com/api/v1/notifications/new/ \
+      curl https://portal.sysreptor.com/api/v1/notifications/new/ \
         -X POST \
         -H "Authorization: Bearer ${SAASPANEL_API_TOKEN}" \
         -H "Content-Type: application/json" \

README.md

@@ -27,13 +27,13 @@
 </p>
 
 <p align="center">
-  <a href="https://cloud.sysreptor.com/demo">Playground</a> •
+  <a href="https://portal.sysreptor.com/demo">Playground</a> •
   <a href="https://github.com/Syslifters/sysreptor/discussions/categories/ideas">Ideas</a> •
   <a href="https://github.com/Syslifters/sysreptor/discussions/categories/q-a">Questions</a> •
   <a href="https://docs.sysreptor.com/">Documentation</a> •
   <a href="https://docs.sysreptor.com/features-and-pricing/">Features and Pricing</a> •
   <a href="https://docs.sysreptor.com/setup/installation/">Installation</a> •
-  <a href="https://cloud.sysreptor.com/order/">Buy SysReptor</a>
+  <a href="https://portal.sysreptor.com/order/">Buy SysReptor</a>
 </p>
 
 ---
@@ -51,13 +51,13 @@ SysReptor is a fully customizable pentest reporting platform designed for penetr
 
 
 ## SysReptor Cloud
-You just want to start pentest reporting and save yourself all the effort of setting up, configuring and maintaining a dedicated server? Then SysReptor Cloud is the right choice for you! Get to know SysReptor on our [Playground](https://cloud.sysreptor.com/demo) and if you like it, you can get your personal Cloud instance [here](https://cloud.sysreptor.com/order/).
+You just want to start pentest reporting and save yourself all the effort of setting up, configuring and maintaining a dedicated server? Then SysReptor Cloud is the right choice for you! Get to know SysReptor on our [Playground](https://portal.sysreptor.com/demo) and if you like it, you can get your personal Cloud instance [here](https://portal.sysreptor.com/order/).
 
 <h3 align="center">
-    <a href="https://cloud.sysreptor.com/demo"><img src="/docs/docs/assets/dino/sign_demo.svg" width="15%" alt="Demo"></a>
+    <a href="https://portal.sysreptor.com/demo"><img src="/docs/docs/assets/dino/sign_demo.svg" width="15%" alt="Demo"></a>
 </h3>
-<h3 align="center">🦖 Try demo <a class="md-button" href="https://cloud.sysreptor.com/demo/">here</a></h3>
-<h3 align="center">🚀 Sign up for SysReptor Cloud <a class="md-button" href="https://cloud.sysreptor.com/order/">here</a></h3>
+<h3 align="center">🦖 Try demo <a class="md-button" href="https://portal.sysreptor.com/demo/">here</a></h3>
+<h3 align="center">🚀 Sign up for SysReptor Cloud <a class="md-button" href="https://portal.sysreptor.com/order/">here</a></h3>
 
 <br>
 

api/src/reportcreator_api/conf/settings.py

@@ -629,7 +629,7 @@ def __bool__(self):
 # Notifications
 VERSION = config('VERSION', default='dev')
 INSTANCE_TAGS = config('INSTANCE_TAGS', cast=Csv(delimiter=';', post_process=remove_empty_items), default='on-premise')
-NOTIFICATION_IMPORT_URL = config('NOTIFICATION_IMPORT_URL', default='https://cloud.sysreptor.com/api/v1/notifications/')
+NOTIFICATION_IMPORT_URL = config('NOTIFICATION_IMPORT_URL', default='https://portal.sysreptor.com/api/v1/notifications/')
 
 # License
 LICENSE = config('LICENSE', default=None)

docs/.gitignore

@@ -1,4 +1,5 @@
 *.pyc
 site
 __pycache__
-.cache
+.cache
+venv

docs/docs/features-and-pricing.md

@@ -21,7 +21,7 @@
 | [__Easy Backups__](setup/backups.md){ target=_blank }                                          | <span style="color:red;font-weight:bold;">X</span>                                                            | <span style="color:green;font-weight:bold;">✓</span>                                                                                                                  |
 | [__SSO (oAuth/OIDC)__](users/oidc-setup.md){ target=_blank }                                   | <span style="color:red;font-weight:bold;">X</span>                                                            | <span style="color:green;font-weight:bold;">✓</span>                                                                                                                  |
 | [__Project Archiving (encrypted)__](insights/archiving.md){ target=_blank }                    | <span style="color:red;font-weight:bold;">X</span>                                                            | <span style="color:green;font-weight:bold;">✓</span>                                                                                                                  |
-|                                                                                               | [:fire: Get Started](setup/installation.md){ .md-button target="_blank" }                                      | [:rocket: Buy](https://cloud.sysreptor.com/order/){ .md-button target="_blank"}                                                                                       |
+|                                                                                               | [:fire: Get Started](setup/installation.md){ .md-button target="_blank" }                                      | [:rocket: Buy](https://portal.sysreptor.com/order/){ .md-button target="_blank"}                                                                                       |
 |                                                                                               | [:material-phone: Contact Us](contact-us.md){ .md-button style="align:center;" }                               | [:sauropod: Book a Demo](https://outlook.office365.com/book/[email protected]/s/gUjy2xF2GEeSc_6mDLvvkA2){ .md-button style="align:center;" target=_blank } |
 
 <br><br>

docs/docs/insights/vulnerabilities.md

@@ -14,7 +14,7 @@ Find more information in our [advisory](https://github.com/Syslifters/sysreptor/
 
 **CVSSv3.1:** High (7.8; CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H)  
 **Fixed in 2024.29** (on 17 April 2024)  
-**Workaround:** Use a reverse proxy (like [Caddy](../setup/webserver.md#caddy) or [nginx](../setup/webserver.md#nginx)).
+**Workaround:** Use a reverse proxy (like [Caddy](../setup/webserver.md#caddy) or [nginx](../setup/webserver-nginx.md)).
 
 If you don't use a reverse proxy (like Caddy or nginx) for SysReptor and expose the SysReptor port (TCP 8000 by default) directly, you are probably vulnerable to HTTP Request Smuggling attacks.
 

docs/docs/install.sh

@@ -31,7 +31,7 @@ fi
 if
     test 0 -eq "$docker"
 then
-    echo "Follow the installation instructions at https://docs.docker.com/engine/install/ubuntu/"
+    echo 'Install Docker, e.g., using "curl -fsSL https://get.docker.com | sudo bash"'
     exit -1
 fi
 if

docs/docs/setup/backups.md

@@ -22,20 +22,21 @@ docker compose run --rm app python3 manage.py backup --key "<aes-key-as-hex>" >
 ## Create a backup during update
 When [updating](updates.md) SysReptor, you can use the `--backup` switch, which will create a backup before applying the update.
 
+## Create backups via web interface
+:octicons-cloud-24: Cloud · :octicons-server-24: Self-Hosted
+
+Users with [`superuser` permissions](../users/user-permissions.md#superuser) and access to the [`BACKUP_KEY`](configuration.md#backup-key) can create backups using the web interface.
+
+If no [`BACKUP_KEY`](configuration.md#backup-key) is configured, you cannot create backups via the web interface.
 
 ## Create backups via API
 :octicons-cloud-24: Cloud · :octicons-server-24: Self-Hosted
 
-### Prerequisites
-Creating backups is a high-privilege operation. Therefore, access to the backup API endpoint is restricted.
-Only [`superusers`](../users/user-permissions.md#superuser) [`system`-users](../users/user-permissions.md#system) can access this endpoint in combination with a `BACKUP_KEY`.
-Regular users do not have access to the backup API endpoint.
+Users with [`superuser` permissions](../users/user-permissions.md#superuser) and [`system` users](../users/user-permissions.md#system) can [create backups via the API](https://demo.sysre.pt/api/public/utils/swagger-ui/#/v1/v1_utils_backup_create){ target=_blank } in combination with the configured [`BACKUP_KEY`](configuration.md#backup-key).
 
-Additionally, you need to configure a `BACKUP_KEY` as environment variable.
-This backup key has to be at least 20 characters long.
 If no `BACKUP_KEY` is configured, the backup API endpoint is disabled.
 
-Optionally, the backup can be encrypted via a 256-bit AES key provided in the HTTP request body.
+The backup can optionally be encrypted via a 256-bit AES key provided in the HTTP request body or pushed to an S3 bucket (see [API parameters](https://demo.sysre.pt/api/public/utils/swagger-ui/#/v1/v1_utils_backup_create){ target=_blank }).
 
 ### API Requests
 ```

docs/docs/setup/configuration.md

@@ -197,7 +197,7 @@ GUEST_USERS_CAN_SEE_ALL_USERS=False
 ```
 
 ### S3 Storage
-Uploaded files and images can be stored in an S3 bucket. Files are stored on the filesystem in a docker volume by default. If data at rest encryption is configured files are encrypted (~~except images~~, images are also encrypted).
+Uploaded files and images can be stored in an S3 bucket. Files are stored on the filesystem in a docker volume by default. If data at rest encryption is configured, all uploaded files (incl. images) are encrypted.
 
 `DEFAULT_S3_*` settings to apply to all file storages. It is possible to configure different settings per storage.
 
@@ -257,7 +257,7 @@ ARCHIVED_FILE_LOCATION="archivedfiles"
 ### Backup Key
 <span style="color:red;">:octicons-heart-fill-24: Pro only</span>
 
-API key used for creating backups via REST API. The key should be random and must have 20 or more characters. Find more information at https://docs.sysreptor.com/backups/.  
+The backup key is used for creating backups via the [web interface](backups.md#create-backups-via-web-interface) or the [REST API](backups.md#create-backups-via-api). The key should be random and must have 20 or more characters.  
 Make sure this key remains secret.
 
 ``` title="Generate random backup key:"

docs/docs/setup/installation.md

@@ -2,9 +2,10 @@
 ### Server
 :octicons-server-24: Self-Hosted
 
-* Ubuntu
-* 4GB RAM
-* Latest [Docker](https://docs.docker.com/engine/install/ubuntu/){ target=_blank } (with docker-compose-plugin)
+* Ubuntu[^1]
+* 8GB RAM
+
+[^1]: It may also run on [Kali](https://emvee-nl.github.io/posts/SysReptor/){ target=_blank }, [MacOS](https://alive-club-f8d.notion.site/Sysreptor-Install-M2-Studio-12e1fd44f31080a28acae6de346c6a30){ target=_blank }, RHEL, and more as long as you take care of all dependencies. Our install and update procedures, however, focus on Ubuntu.
 
 ### Client
 :octicons-cloud-24: Cloud · :octicons-server-24: Self-Hosted
@@ -22,14 +23,19 @@
 
 === "Easy Script Installation"
 
-    Installation via script is the easiest option. You need (official) [Docker](https://docs.docker.com/engine/install/ubuntu/){ target=_blank }  installed.
+    Installation via script is the easiest option.
 
-    Install additional requirements:
+    Install additonal requirements:
     ```shell
     sudo apt update
     sudo apt install -y sed curl openssl uuid-runtime coreutils
     ```
 
+    Install Docker:
+    ```shell
+    curl -fsSL https://get.docker.com | sudo bash
+    ```
+
     The user running the installation script must have the permission to use docker.  
     Download and run:
 
@@ -42,7 +48,10 @@
 
 === "Manual Installation"
 
-    You need (official) [Docker](https://docs.docker.com/engine/install/ubuntu/){ target=_blank }  installed.
+    Install Docker:
+    ```shell
+    curl -fsSL https://get.docker.com | sudo bash
+    ```
 
     Download and extract the latest SysReptor setup files:
     ```shell

docs/docs/setup/plugins.md

@@ -4,12 +4,12 @@
 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.
+All plugins are disabled by default. To enable a plugin, add the [`ENABLED_PLUGINS`](./configuration.md#plugins) variable to your app.env (e.g., `ENABLED_PLUGINS=cyberchef,checkthehash`) and restart your container (`docker compose up -d` from the `deploy` directory).
 
 
 ## Official Plugins
 
-Official plugins are maintained by the SysReptor team and are included in official docker images.
+Official plugins are maintained by us and are shipped with our official docker images.
 
 | Plugin | Description |     |
 | ------ | ----------- | --- |

docs/docs/setup/upgrade-to-professional.md

@@ -11,5 +11,5 @@
      - sysreptor/docker-compose.yml
      - languagetool/docker-compose.yml
    ```
-3. `cd` to `deploy/` and run `docker compose up -d`
+3. `cd` to `deploy` and run `docker compose up -d`
 4. Enjoy

docs/docs/setup/webserver-nginx.md

@@ -0,0 +1,31 @@
+# Use nginx as a web server
+
+Install nginx on your host system:
+
+```shell
+sudo apt-get update
+sudo apt-get install -y nginx
+```
+
+Copy our nginx boilerplate configuration from the `deploy/nginx` directory to your nginx directory:
+
+```shell
+sudo cp deploy/nginx/sysreptor.nginx /etc/nginx/sites-available/
+sudo ln -s /etc/nginx/sites-available/sysreptor.nginx /etc/nginx/sites-enabled/
+sudo rm /etc/nginx/sites-enabled/default
+```
+
+You can optionally generate self-signed certificates:
+```shell
+sudo apt-get update
+sudo apt-get install -y ssl-cert
+sudo make-ssl-cert generate-default-snakeoil
+```
+
+Modify `sysreptor.nginx` and update the certificate paths in case you have trusted certificates (recommended).
+
+(Re)Start nginx:
+```shell
+sudo systemctl restart nginx
+# sudo /etc/init.d/nginx restart
+```

docs/docs/setup/webserver.md

@@ -3,7 +3,7 @@
 :octicons-server-24: Self-Hosted
 
 The Django webserver is not recommended due to missing transport encryption, missing performance and security tests.  
-We recommend a webserver like Caddy, nginx or Apache and to enable https.
+We recommend a webserver like Caddy, [nginx](webserver-nginx.md) or Apache and to enable https.
 
 ## Easy setup with Caddy (recommended) {#caddy}
 
@@ -19,34 +19,3 @@ If you want Caddy to take care of your LetsEncrypt certificate, you must set up:
  1. a valid domain name resolving to your public IP address
  2. port 80 of your must be publicly reachable
 
-## nginx
-
-Install nginx on your host system:
-
-```shell
-sudo apt-get update
-sudo apt-get install -y nginx
-```
-
-Copy our nginx boilerplate configuration from the `deploy/nginx` directory to your nginx directory:
-
-```shell
-sudo cp deploy/nginx/sysreptor.nginx /etc/nginx/sites-available/
-sudo ln -s /etc/nginx/sites-available/sysreptor.nginx /etc/nginx/sites-enabled/
-sudo rm /etc/nginx/sites-enabled/default
-```
-
-You can optionally generate self-signed certificates:
-```shell
-sudo apt-get update
-sudo apt-get install -y ssl-cert
-sudo make-ssl-cert generate-default-snakeoil
-```
-
-Modify `sysreptor.nginx` and update the certificate paths in case you have trusted certificates (recommended).
-
-(Re)Start nginx:
-```shell
-sudo systemctl restart nginx
-# sudo /etc/init.d/nginx restart
-```

docs/docs/show-and-tell/index.md

@@ -0,0 +1,3 @@
+---
+title: Show and Tell
+---

docs/mkdocs.yml

@@ -10,7 +10,6 @@ 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
@@ -45,6 +44,7 @@ nav:
           - Google: users/oidc-google.md
           - Generic: users/oidc-generic.md
       - Forgot Password: users/forgot-password.md
+  - Plugins: setup/plugins.md
   - Automize Reporting via CLI:
       - Getting Started: cli/getting-started.md
       - Setup: cli/setup.md

docs/overrides/partials/header.html

@@ -102,7 +102,7 @@
       </label>
       {% include "partials/search.html" %}
     {% endif %}
-    <a class="demo-button" href="https://cloud.sysreptor.com/demo" target="_blank">Playground</a>
+    <a class="demo-button" href="https://portal.sysreptor.com/demo" target="_blank">Playground</a>
     {% if config.repo_url %}
       <div class="md-header__source">
         {% include "partials/source.html" %}

docs/overrides/partials/post.html

@@ -48,7 +48,10 @@
         </li>
         {% if not post.meta.pro %}
           <li class="md-meta__item">
-                  Community
+            <span class="twemoji" style="color:green;">
+              {% include ".icons/octicons/heart-fill-24.svg" %}
+            </span>
+            Community
             {#- Collapse whitespace -#}
           </li>
         {% endif %}

packages/frontend/src/pages/users/self/apitokens.vue

@@ -23,6 +23,7 @@
     <s-card class="mt-4">
       <v-card-title>API Tokens</v-card-title>
       <v-card-text>
+        <p>Use the <a href="https://docs.sysreptor.com/cli/getting-started/" target=_blank>reptor</a>, or the <a href="/api/public/utils/swagger-ui/" target="_blank">SysReptor REST API</a> (unstable).</p>
         <v-list>
           <v-list-item
             v-for="apiToken in apiTokens" :key="apiToken.id"

plugins/checkthehash/README.md

@@ -1,2 +1,10 @@
-# Hash Identifier Plugin
-Identify hash possible hash types
+# Check the Hash
+Identify possible hash types of a string.
+
+Add `checkthehash` to the `ENABLED_PLUGINS` variable in your `app.env` and restart your containers using `docker compose up -d` from the `deploy` directory.
+
+```
+ENABLED_PLUGINS="checkthehash"
+```
+
+![Identify the hash type](docs/img/check_the_hash.png)

plugins/cyberchef/README.md

@@ -1,6 +1,10 @@
 # CyberChef Plugin
-Integrate CyberChef into SysReptor.
+Add CyberChef to SysReptor.
+
+Add cyberchef to the `ENABLED_PLUGINS` variable in your `app.env` and restart your containers using `docker compose up -d` from the `deploy` directory.
 
 ```
 ENABLED_PLUGINS="cyberchef"
 ```
+
+![CyberChef in SysReptor](docs/img/cyberchef.png)

plugins/graphqlvoyager/README.md

@@ -1,6 +1,10 @@
 # GraphQL Voyager Plugin
-Integrate GraphQL Voyager into SysReptor.
+Add GraphQL Voyager to SysReptor.
+
+Add `graphqlvoyager` to the `ENABLED_PLUGINS` variable in your `app.env` and restart your containers using `docker compose up -d` from the `deploy` directory.
 
 ```
 ENABLED_PLUGINS="graphqlvoyager"
 ```
+
+![GraphQL Voyager in SysReptor](docs/img/gql_voyager.png)