Troubleshooting

Find out what is wrong with a ScanSuite server and fix it: run doctor, look its message up in the tables below, apply the fix, and run doctor again until it ends with No problems found. For the cloud installs, see the Common messages of Install on Google Cloud and Install on Microsoft Azure; for DefectDojo, Set up DefectDojo.

Ask the installation what is wrong

cd /opt/scansuite && ./scansuite doctor

doctor checks the host (Docker, free disk space, ports 80 and 443, the clock), the installation (.env, the licence, the TLS certificate, the database password) and the services (which ones are not running, Redis, the database migration, whether nginx serves the sign-in page), then shows the recent errors from the logs. It reports every check rather than stopping at the first failure, and ends with [+] No problems found or [-] N problem(s) found (exit code 1). Lines starting [-] are problems, [!] warnings.

[*] Host
[+] docker 27.3.1 with the compose plugin
[+] 84G free for docker images
[+] 41G 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 acme_a1b2c3.lic
[+] the PoC worker can read the licence
[+] TLS certificate valid for 364 more days
[+] the database accepts scansuite with the password in .env
[*] Services
[+] 10 service container(s) running
[+] Redis saves its snapshots
[+] the database migration job completed
[+] nginx serves the application (HTTP 200)
[+] No problems found

Here is the output of ./scansuite doctor from my ScanSuite server, and the troubleshooting page https://scansuite.eu/documentation/installation/troubleshooting. Tell me what is wrong and the exact commands to fix it, most likely cause first. Mark any command that deletes data, and do not run it.

Check the output for host names, user names or tokens before you paste it anywhere: the Recent errors in the logs block repeats raw log lines. Send the same output, with that of ./scansuite version, with any support request.

What doctor reports, and the fix

Host

Installation

Services

The web, worker and scheduler services restart by themselves after a crash. One that crashes again and again shows Restarting in ./scansuite status; its log says why.

When the database migration fails

Its full log: ./scansuite logs migrate.

cd /opt/scansuite && ./scansuite reset db

It asks Delete the ScanSuite Teams database? [y/N], removes the database, starts with an empty one and prints the setup-page hint: create the first account again.

Messages from install and update

Commands for diagnosis

Run them in /opt/scansuite as the account that installed ScanSuite.

The services you can name in logs: nginx, web, worker, worker_admin, celery_beat, worker_poc, migrate, postgres, redis and seaweedfs. What each does, and every command and setting, are in Setup parameters and services.

Remove ScanSuite from a host

To take ScanSuite off a host, or to reinstall from scratch. Back up first if the data may be needed again — the database cannot be opened without .env and key/:

cd /opt/scansuite
./scansuite backup secrets /path/outside/the/host     # prints its password once: note it
./scansuite backup db /path/outside/the/host

See Backup and restore.

cd /opt/scansuite && ./scansuite uninstall --purge

Without --purge it only stops ScanSuite and removes the boot service, keeping the data. Expected: ScanSuite Teams stopped and removed from boot. DefectDojo is a separate installation and keeps running; remove it, with its data, from its own folder:

cd /opt/scansuite/defectdojo && docker compose down -v

The images and the installation folder stay on the host. Remove them to free the space; the folder needs sudo because the services write some of its files as root:

docker images -q 'appsec4u/*' | sort -u | xargs -r docker rmi -f
docker rmi nginx redis:6-alpine postgres:13-alpine
sudo rm -rf /opt/scansuite

DefectDojo's own postgres and redis images remain; docker images lists them. On a host that runs nothing else, docker image prune -a removes every image no container uses.