Setup parameters and services

A ScanSuite Teams server is run with one command, ./scansuite, in /opt/scansuite, and configured in one file, /opt/scansuite/.env. This page lists every subcommand, option and setting, how an update treats your own changes, and what ./scansuite doctor checks. Installing for the first time is described in Install ScanSuite Teams; backups in Backup and restore.

Before you start

Run every command on the server, in the installation directory, as the account that installed ScanSuite. Check that you are in the right place:

ls /opt/scansuite/docker-compose.yml && cd /opt/scansuite && ./scansuite version

Expected: the path of docker-compose.yml, then ScanSuite Teams with the release, images and licence lines. "No ScanSuite installation here" means you are in another directory, or ScanSuite is not installed yet.

The scansuite command

./scansuite without arguments, or with help, --help or -h, prints a summary.

Install and update options

The scanner and DefectDojo choices are saved in .env as SCANSUITE_SCANNERS and SCANSUITE_DOJO; later updates and starts keep to them until you give another option.

Environment variables of the command

Set them in the shell before the command, for example SCANSUITE_ASSUME_YES=1 ./scansuite reset dojo. They are not read from .env, except where the table says so.

Updating

1. 01
   Run the update

   It reads the licence code from key/. Give it as an argument only when the licence changed.

   ShellCopy

   cd /opt/scansuite && ./scansuite update

2. 02
   Read the end of the output

   Expected: [+] Updated <old tag> -> <new tag>, then the version block. Warnings ([!]) above it say which of your files were kept or replaced, see below.

3. 03
   Check the installation

   Expected last line: [+] No problems found.

   ShellCopy

   ./scansuite doctor

What the update does, in order:

• saves a copy of .env as .env.bak-<date>;
• fetches the release files. Files you changed in docker-compose.yml, compose.d/, services/nginx/ and defectdojo/ are carried into the new release: your changes and the release's are merged. Where both changed the same lines, or the merged services no longer load, the release's version is put in place and yours is kept in .replaced-<date>.<random>/ together with your change alone as <file>.patch;
• keeps your TLS certificate and key (services/nginx/certs/cert.pem and key.pem) as a pair, exactly as you had them;
• replaces any other release file that differs on the server, keeping a copy in .replaced-<date>.<random>/;
• stops without changing anything when the account running it cannot read one of your changed files, for example a key.pem copied in as root. The message gives the sudo chown command to run before updating again;
• continues with the new scansuite command when the update replaced the command itself;
• pulls the images your licence and your scanner choice need, refreshes the start-up service, brings the database up to date, and recreates only the services that changed.

The .replaced- directory is removed again when nothing was replaced.

A cron job for a weekly update (edit with sudo crontab -e). It works once the server has signed in to the registry, which the first installation does:

0 3 * * 4 cd /opt/scansuite && ./scansuite update --yes > /var/log/scansuite-update.log 2>&1

Choosing what is installed

By default only the platform is installed: the application and DefectDojo, without the external scanner containers. Add the scanners you need with the options above, on install or on a later update:

./scansuite update --all-scanners   # every scanner
./scansuite update --static-only    # only the static analysis scanners
./scansuite update --dynamic-only   # only the dynamic analysis and infrastructure scanners
./scansuite update --no-scanners    # no external scanners (the default)
./scansuite update --no-dojo        # stop DefectDojo; its data is kept
./scansuite update --with-dojo      # bring DefectDojo back

The static group holds classic code scanners such as Semgrep, KICS, gosec, SpotBugs, Bandit, Brakeman and Flawfinder; the dynamic group holds web and infrastructure scanners such as Wapiti, Nuclei, Dastardly and ZAP, and the OSINT and password-guessing tools. The full lists are scanners.d/static.list and scanners.d/dynamic.list. A first install with scanners needs about 40 GB free for images, a platform-only install about 15 GB.

Check: the update prints External scanners: <all|static|dynamic|none>; DefectDojo: <yes|no>, and grep SCANSUITE_ .env shows the saved choice.

The .env file

The settings of this server live in /opt/scansuite/.env. The installer creates it on the first install: it generates the passwords, takes the time zone from the server and records the release. Only its owner can read it (mode 600). Updates never overwrite it, and it belongs in your backups.

zoom_inEnlarge

Single sign-on adds its own settings, see Single sign-on. The Nessus scanner is configured in System Settings, not in .env.

Advanced settings

Not in the file and not needed on a standard server. Add one by hand only for the case in its last column:

Apply a change

1. 01
   Edit .env

   For example with sudo nano /opt/scansuite/.env. Keep the file mode 600.

2. 02
   Restart

   Only the services whose settings changed are recreated. Expected: [+] All services healthy.

   ShellCopy

   cd /opt/scansuite && ./scansuite restart

3. 03
   Check

   Expected last line: [+] No problems found.

   ShellCopy

   ./scansuite doctor

Database and Redis passwords

PostgreSQL and Redis run as containers of the installation, reachable only on its own Docker network (as postgres and redis) and not published on the server. Both passwords are generated on the first install. To change one, edit PS_DATABASE_PASSWORD or REDIS_PASSWORD and run ./scansuite restart: Redis starts with the new password, and the database account is brought in line with it before the other services start. ./scansuite doctor then reports the database accepts scansuite with the password in .env.

Installation files

Services

web, the workers, worker_admin, worker_poc and celery_beat restart on their own after a crash; a service you stopped stays stopped. A container that keeps restarting is crashing on start: read its log with ./scansuite logs <SERVICE>. At start-up the services also bring the database schema up to date when it is behind, instead of refusing to start. Each container's log is capped at three 20 MB files.

Checking the server

cd /opt/scansuite && ./scansuite doctor

Each line starts with [+] (fine), [!] (a warning) or [-] (a problem). The report ends with [+] No problems found (exit code 0) or [-] N problem(s) found (exit code 1). Every check runs, so one failure never hides another.

[*] Host
[+] docker 27.3.1 with the compose plugin
[+] 112G free for docker images
[+] 64G free in /var/tmp for scans and logs
[+] port 80 is served by this installation
[+] port 443 is served by this installation
[+] clock check skipped (no NTP server configured)
[*] Installation
[+] .env is complete
[+] licence demo_a1b2c3.lic
[+] the PoC worker can read the licence
[+] TLS certificate valid for 83 more days
[+] the database accepts scansuite with the password in .env
[*] Services
NAME   IMAGE   SERVICE   STATUS   ...
[+] 9 service container(s) running
[+] Redis saves its snapshots
[+] the database migration job completed
[+] nginx serves the application (HTTP 200)
[+] No problems found

What to do about each message is described in Troubleshooting.

Start-up

Install and update register a systemd service, so ScanSuite starts with the server:

systemctl status scansuite           # expected: enabled
sudo systemctl disable scansuite     # remove it from start-up

Resetting the databases

./scansuite reset db

Deletes the ScanSuite database: scan results, findings, teams, accounts and application settings. The licence, .env, the encryption keys, the certificates and the stored files stay. ScanSuite then restarts and prints Open https://<this host>/setup in a browser to create the first account: create the first team and its administrator again.

./scansuite reset dojo

Deletes and recreates the DefectDojo database, with a new administrator. Wait a few minutes and get the password with ./scansuite dojo password (at a terminal, answer N to Change the admin password now? to only read it).

Uninstalling

./scansuite uninstall asks Continue? [y/N], stops ScanSuite and removes it from start-up. With --purge it also deletes the ScanSuite data: the database, Redis and the file storage. DefectDojo's data and the /opt/scansuite directory stay. Removing the server entirely is described in Troubleshooting.

Moving images to a server without registry access

If the server cannot reach the image registry, prepare the images on one that can. Run the first command there, copy the directory to the target server, load it, and install or update with --offline:

./scansuite offline save /media/transfer/scansuite-images      # on a server with registry access
./scansuite offline load /media/transfer/scansuite-images      # on the target server
./scansuite install <LICENCE_CODE> --offline                  # or: ./scansuite update --offline

The same set of images as a normal installation is saved, as one file per image with a checksum list. offline load verifies the checksums (Bundle checksums verified, then Images loaded), and --offline stops with a list of whatever release image is missing.