Installation

AppSec Portal deployment step-by-step guide

System Requirements for Portal usage:

  • Minimum system resources: 4 GB of RAM and 2 CPU cores.

  • Free disk space for installation and data storage of the portal.

  • Network access for external users (users must be able to connect to the portal over the network).

Prerequisites

Before installing the AppSec Portal, make sure you have the following software installed on your machine (for Docker-compose installation type):

SSH keys generation

To securely connect to the Linux server, you will need to set up SSH keys.

If you don't have SSH keys already, you can generate them using the following command in your server terminal:

ssh-keygen -t rsa -b 4096

Set SSH key to your Server

After generating the SSH keys, you need to copy the public SSH key to the Linux server. Use this command to copy the public key:

ssh-copy-id <username>@<server-ip-address>

Replace <username> with your Linux server account username, and <server-ip-address> with the IP address of the Linux server. You will be prompted to enter your password for authentication.

Open the file on your local machine where the private SSH key is stored. The private key is typically saved with a .pem or .ssh file extension.

Select and copy the contents of the private key file. Ensure you copy the key with the correct permissions and line breaks intact.

Please note that the AppSec Portal is currently incompatible with Amazon Aurora database.

Installation

GitLab CI installation

Step 1: Fork the AppSec Portal repository. This will create a copy of the repository under your account, which you can then modify and configure as needed

Step 2: Set the public SSH key on the host where the portal will be deployed. Add an SSH key to your GitLab account This key will be used to establish a secure connection between the host and the repository

Step 3: Configure Environment Variables for a forked project in GitLab CI/CD settings

  • mandatory environment variables that must be specified (In the CI/CD settings, you need to set the following environment variables for these keys):

SEC_PORTAL_HOST: Specify the host where the portal will be deployed SSH_KEY_PRIVATE: Set the private SSH key within the forked repository. This key will be used for authentication during the installation process

  • optional environment variables. You can choose to accept the default values provided for demonstration purposes or specified it if necessary:

IMAGE_VERSION=latest
DB_NAME=db_name
DB_USER=db_user
DB_PASS=db_pass
DB_HOST=db_host
DB_PORT=5432
GUNICORN_WORKERS=4
GUNICORN_THREADS=4
IMPORTER_GUNICORN_WORKERS=1
IMPORTER_GUNICORN_THREADS=1
RABBITMQ_DEFAULT_USER=admin
RABBITMQ_DEFAULT_PASS=mypass
AMQP_HOST_STRING=amqp://admin:mypass@rabbitmq:5672/
DOMAIN=http://localhost
COOKIES_SECURE=False (True if you use https)

The IMAGE_VERSION The script will autonomously determine the most recent version

For optimal performance (tested on 1 million findings), it is recommended to specify the following environment values: GUNICORN_WORKERS = 4 and GUNICORN_THREADS= 4 To configure the import worker and import threads, the following is necessary: IMPORTER_GUNICORN_WORKERS determines the number of workers for processing import tasks. It is recommended to set a value that takes into account the volume and intensity of import tasks. IMPORTER_GUNICORN_THREADS defines the number of threads within each import worker. This affects the parallel processing of tasks within the worker.

DB_NAME, DB_USER, DB_PASS, DB_HOST, DB_PORT variables are required for database configuration

If the message broker is hosted on a third-party server, only the AMQP_HOST_STRING must be specified. However, if the container is raised locally, all three variables, including RABBITMQ_DEFAULT_USER and RABBITMQ_DEFAULT_PASS need to be specified

The COOKIES_SECURE variable determines the cookie security flag. It should be set to True if HTTPS is used.

Step 4: Run pipeline

Step 5: Click on install section

The GitLab CI script provided in the forked repository will handle the installation process

This script will raise the portal and generate a user with administrator privileges using the default login and password credentials "admin/admin"

Please note that after the initial installation, it is necessary to reset the password for the administrator user via the Django admin panel: follow the <your-domain>.com/admin URL and sign in using the superuser credentials, then select "Users" in the left panel. You can add users from there

Next step: Start your AppSec Portal and apply the licence

Install using Helm

Before using Helm, make sure that Helm is installed on your computer and that your Kubernetes cluster is configured to work with Helm

Step 1: Clone the repository

Clone the Appsec portal repository to your server:

git clone https://gitlab.com/whitespots-public/appsec-portal.git appsec-portal

Step 2: Navigate to the root directory

Navigate to the directory where the Appsec-portal files were cloned, the helm directory:

cd appsec-portal/AppsecPortal-HelmChart  

Step 3: Set environment variables

in the values.yaml file, change the default environment variables in some sections to meet your requirements :

  • In the deploymentSpec section:

  • In the ingresses section:

- name: ingress-webhook
  path: /api/v1/jira-helper/jira-event/<your-webhook>/

Replace your-webhook in path variable '/api/v1/jira-helper/jira-event/your-webhook/' with the unique identifier (token) associated with the specific webhook event, for example, e2b7e8be-1c77-4969-9105-58e91bd311cc.

  • In the configMap section:

COOKIES_SECURE: "True"  
DB_HOST: "postgres"     
DB_PORT: "5432"         
DB_NAME: "postgres"       
DB_USER: "postgres"      
DEBUG: "True"           
DOMAIN: http://localhost  
RABBITMQ_DEFAULT_USER: admin 
  • COOKIES_SECURE: variable determines the cookie security flag. It should be set to True if HTTPS is used.

  • DB_NAME, DB_USER, DB_HOST, DB_PORT and DB_PASS specify the variables needed to configure the database, or use the defaults.

  • The DOMAIN specify the domain where the Appsec-portal will be accessible.

  • if the container is raised locally RABBITMQ_DEFAULT_USER need to be specified

  • In the secrets section:

AMQP_HOST_STRING: "amqp://admin:mypass@rabbitmq:5672/"
DB_PASS: "postgres"
JWT_PRIVATE_KEY: <your key>
JWT_PUBLIC_KEY: <your key>
SECRET_KEY: <your key>
RABBITMQ_DEFAULT_PASS: "mypass"
  • If the message broker is hosted on a third-party server, only the AMQP_HOST_STRING must be specified. However, if the container is raised locally, all three variables, including RABBITMQ_DEFAULT_USER and RABBITMQ_DEFAULT_PASS need to be specified

  • The JWT_PRIVATE_KEY and JWT_PUBLIC_KEY variables are RSA key pair used to sign JWT keys

  • SECRET_KEY: variable is used to generate hashes in Django

  • In the db section:

It is recommended to use an external database. For this purpose it is enough only to specify the value true for the variable external_db, other variables in this section do not need to be specified

But if you use a database inside the cluster, configure variables for it

external_db: false 
name: postgres
storageClassName: local-storage
node: minikube
path: /mnt/local-storage
mountPath: /mnt
claimName: postgres-pv-claim

external_db: false name: database name storageClassName: storage class name for the database node: the node in the cluster that will host the database path:path to the database storage on the node mountPath: the place inside the container where the database storage will be mounted claimName: the name of the PersistentVolumeClaim that is used to request storage allocation

Step 4: To configure the ingress

To configure the ingress in your Helm chart, add the required annotations. We recommend including the following:

For ingress-webhook:

ingress.kubernetes.io/scheme: internet-facing
ingress.kubernetes.io/target-type: ip

For ingress-hosts:

ingress.kubernetes.io/scheme: internal
ingress.kubernetes.io/target-type: ip

For ingress-import:

ingress.kubernetes.io/scheme: internal
ingress.kubernetes.io/target-type: ip

Step 5: Install the application using Helm

Run the application by executing the following command:

helm install appsecportal <path-to-helm-directory>

replace <path-to-helm-directory> with the path to the directory that contains the Helm Chart for your application.

After the first run you will receive an Access Token.

Copy the value of the access token and add it in the values.yaml file in the secret section and restart scanner-worker pod

Next step: Start your AppSec Portal and apply the licence

Docker-compose installation

Step 1: Clone the repository

Clone the AppSec Portal repository to your server:

git clone https://gitlab.com/whitespots-public/appsec-portal.git appsec-portal

Step 2: Navigate to the root directory

Navigate to the root directory of the AppSec Portal project by executing the following command:

cd appsec-portal

Step 3: Set environment variables

In the root directory of the AppSec Portal project, execute the following command:

./set_vars.sh

The script prompts you for values for the following environment variables, including optional ones. You can also accept the default values for optional variables by pressing Enter:

DB_NAME{default=postgres}
DB_USER{default=postgres}
DB_PASS{default=postgres}
DB_HOST{default=postgres}
DB_PORT{default=5432}
RABBITMQ_DEFAULT_USER{default=admin}
RABBITMQ_DEFAULT_PASS{default=mypass}
AMQP_HOST_STRING{default=amqp://admin:mypass@rabbitmq:5672/}
COOKIES_SECURE{default=True}
DOMAIN=http://localhost
IMAGE_VERSION=latest
  • The IMAGE_VERSION the required variable must be specified. Specify a specific version, e.g. release_v24.02.3, or specify latest and the script will install the latest version.

  • The DOMAINthe required variable must be specified. Specify the domain where the AppSec Portal will be accessible

  • DB_NAME, DB_USER, DB_PASS, DB_HOST, DB_PORT optional variable. Specify the variables needed to configure the database, or use the defaults.

  • If the message broker is hosted on a third-party server, only the AMQP_HOST_STRING must be specified. However, if the container is raised locally, all three variables, including RABBITMQ_DEFAULT_USER and RABBITMQ_DEFAULT_PASS need to be specified

  • The COOKIES_SECURE variable determines the cookie security flag. It should be set to True if HTTPS is used

The set_vars.sh script creates the .env file with the configured environment variables and generates a pair of JWT keys, which are used to sign JWT keys and SECRET_KEY is used to generate hashes in Django.

Step 4: Start the AppSec Portal

To start the AppSec Portal, run the following command:

sh run.sh

Step 5: Create a superuser account

To create an administrator account, execute the following command:

docker-compose exec back python3 manage.py createsuperuser --username admin

This username and password will allow you to log in to the installed Appsec Portal

or

Create users using Django admin panel

In order to access admin settings, follow the <your-domain>.com/admin URL and sign in using the superuser credentials, then select Users in the left panel. You can add users from there. Don't forget to assign the necessary permissions to the users.

Next step: Start your AppSec Portal and apply the licence

Congratulations, you have successfully installed the AppSec Portal! Now apply the licence to your installed application.

Last updated