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):
Docker (version 19.03 or higher)
Docker Compose (version 1.26 or higher)
SSH keys (for GitLab CI installation option)
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
Option 1: GitLab CI installation (automated docker-compose installation)
Option 2: Install using Helm (install in Kubernetes environment)
Option 3: Docker-compose installation (manual docker-compose 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
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:
release:
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 toTrue
if HTTPS is used.DB_NAME
,DB_USER
,DB_HOST
,DB_PORT
andDB_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, includingRABBITMQ_DEFAULT_USER
andRABBITMQ_DEFAULT_PASS
need to be specifiedThe
JWT_PRIVATE_KEY
andJWT_PUBLIC_KEY
variables are RSA key pair used to sign JWT keysSECRET_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
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
DOMAIN
the required variable must be specified. Specify the domain where the AppSec Portal will be accessibleDB_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, includingRABBITMQ_DEFAULT_USER
andRABBITMQ_DEFAULT_PASS
need to be specifiedThe
COOKIES_SECURE
variable determines the cookie security flag. It should be set toTrue
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.
Congratulations, you have successfully installed the AppSec Portal! Now apply the licence to your installed application.
If you have any issues during the installation process or while using the app, contact our support team sales@whitespots.io for assistance❤️.
Last updated