Documentation
Add scanners

Add a scanner

This guide will show you how to add a scanner to connect to your console. Scanner is the component that runs the scans and reports the results back to the console.

If you followed the deployment guide, you should already have a scanner running in the same host as the UI and the backend (i.e. the console). This guide is for adding additional scanners.

Prerequisites

  • A console up and running (see deployment guide).
  • Host that you can run the scanner on. This guide will assume one of the following:
    • docker
    • docker-compose
  • Connectivity from the scanner to the console. If you are running the scanner on a different network, you will need to open the console port to the scanner network. Default port for the console is 8000 if using the deployment guide.

Steps

In the console

Run command to create the scanner

These commands assume you have deployed the console using the docker-compose.yml (opens in a new tab).

   docker compose run backend create_scanner_token

This returns

   SCANNER_TOKEN=ey....

In the scanner host

Create a .env file with the scanner token

.env
SCANNER_TOKEN=ey....
ENDPOINT=http://console-address:8000

Where http://console-address:8000 is the address of the console. If you are running the console on a different port or network, you will need to change the ENDPOINT variable.

Download the seccomp (opens in a new tab) profile for the scanner

curl -o chrome.json https://raw.githubusercontent.com/webhood-io/webhood/main/files/chrome.json

Create a docker-compose.yml file with the scanner configuration

docker-compose.yml
services:
  scanner:
    container_name: webhood-scanner
    image: ghcr.io/webhood-io/webhood/scanner:latest
    restart: always
    environment:
      ENDPOINT: ${ENDPOINT}
      SCANNER_TOKEN: ${SCANNER_TOKEN}
      #  Scanner is not able to receive realtime updates from the console if it is using a self-signed certificate. 
      #  We therefore recommend using valid certificate or plain HTTP for the scanner.
      #  But, comment out next line if you are using a self-signed certificate and HTTPS anyway. 
      # NODE_TLS_REJECT_UNAUTHORIZED: 0
    security_opt:
      # Use seccomp to restrict the syscalls that the container can make for Chrome
      # This allows us to run chrome with sandboxing enabled without having to run the whole container as root
      - seccomp=./chrome.json

Run the scanner and check for any errors

   docker compose up

It is a good idea to now initiate some scans in the console to see if the scanner is working correctly.

If no errors, you can start the scanner as a daemon

   docker compose up -d

Additional configuration

Additional scanners

The create_scanner_token command with no arguments will create a new scanner token for the default scanner present in all installations.

To create a token for an additional scanner, you can run

docker compose run backend create_scanner --u "scanner-name"
# Then create an auth token for that scanner
docker compose run backend create_scanner_token --u "scanner-name"