This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Reference

Low level reference docs for the various components.

The app consists of several components. Each is documented below.

1 - Dash Parameters

Instructions for configuring dash.

The most common way to configure dash is to simply configure environment variables. Some parameters are only used during the initial installation.

For details about configuring environment variables for the dash app, see the advanced install guide.

Required Parameters

Variable Description Default
SECURITY_JWT_SECRET JWT Secret for signing JWT Tokens (REQUIRED) null
DEFAULT_SUPER_ADMIN_EMAIL Default super admin email to create during installation null
DEFAULT_SUPER_ADMIN_PASSWORD Default super admin password to create during installation null

Complete List of ENV Variables

Server Configuration

Variable Description Default
DEFAULT_SUPER_ADMIN_EMAIL Default super admin email to create during installation null
DEFAULT_SUPER_ADMIN_PASSWORD Default super admin password to create during installation null
SECURITY_JWT_SECRET JWT Secret for signing JWT Tokens (REQUIRED) null
SERVER_NAME Server name (can largely ignore) M9sweeper
SERVER_HOST What network adapter to listen on (defaults to all - 0.0.0.0) 0.0.0.0
SERVER_PORT What port to listen on 3000
SERVER_BASE_URL Server Base URL for things like links in emails http://localhost:3000/
SERVER_FRONTEND_URL Server Frontend URL for things like links in emails ${SERVER_BASE_URL}

Database Configuration

Variable Description Default
DATABASE_CLIENT Database client (do not change) postgresql
DATABASE_CONNECTION_HOST Database connection host localhost
DATABASE_CONNECTION_PORT Database connection port 5432
DATABASE_CONNECTION_DATABASE Database name postgres
DATABASE_CONNECTION_USERNAME Database connection username postgres
DATABASE_CONNECTION_PASSWORD Datbase connection password postgres
DATABASE_POOL_MIN Database connection pool minimum connections 1
DATABASE_POOL_MAX Database connection pool maximum connections 5
DATABASE_POOL_IDLETIMEOUT Time before connections are reaped when inactive (in milliseconds) 60000
DATABASE_ACQUIRE_CONNECTION_TIMEOUT How long to wait for database connections to be acquired before timing out (in milliseconds) 20000
DATABASE_MIGRATION_ENABLED Whether to run db migrations (0 to disable) true
DATABASE_MIGRATION_TABLE_NAME What table name to use to store which db migrations have been run migrations
DATABASE_MIGRATION_DIRECTORY Where to look for db migration scripts (don’t change) ./migrations
DATABASE_SEED_ENABLED Whether to seed data with the sample data (1 to enable) off
DATABASE_SEED_DIRECTORY Where to find db seed data ./seeds
DATABASE_DEFAULT_SCHEMA Database search path public

Email Configuration

Variable Description Default
EMAIL_CONFIG_USE What email protocol to use (smtp is all that is supported) SMTP
EMAIL_SMTP_HOST SMPT Host (leave blank to disable)
EMAIL_SMTP_PORT SMTP Port Number 465
EMAIL_DEBUG Whether or not to print out emails to console (set to 1 to enable) off
EMAIL_SMTP_SECURE_CONNECTION Whether SMTP is secured (set to 1 to enable) off
EMAIL_SMTP_AUTH_USER SMTP user
EMAIL_SMTP_AUTH_PASSWORD SMTP password
EMAIL_DEFAULT_SENDER_EMAIL Who emails should appear from
EMAIL_SYSTEM_ERROR_REPORT_ENABLE Email errors to a system email address (1 to enable) off
EMAIL_SYSTEM_ERROR_REPORT Where to email system errors
EMAIL_TEMPLATE_DIR Email template directory (mount/provide your own to customize emails) dist/email-templates

RabbitMQ Configuration

Variable Description Default
RABBITMQ_ENABLED Whether to enable rabbitmq (1 is enabled) 1 - enabled
RABBITMQ_HOST_NAME RabbitMQ Hostname rabbitmq
RABBITMQ_HOST_PORT RabbitMQ Port Number 5672
RABBITMQ_PROTOCOL RabbitMQ Protocol (don’t change) amqp
RABBITMQ_USER_NAME RabbitMQ Username guest
RABBITMQ_USER_PASSWORD RabbitMQ Password guest
MSG_QUEUE_NAME_IMAGE_SCANNER RabbitMQ Queue Name for queueing scans trawler_queue
RABBITMQ_VHOST RabbitMQ VHost /
RABBITMQ_FRAMEMAX RabbitMQ Framerate 0

File Storage Configuration

Variable Description Default
FILE_MANAGEMENT_MAX_FILE_FILE
FILE_MANAGEMENT_STORAGE File storage method. local or s3 (see multer docs) local
FILE_MANAGEMENT_LOCAL_DEST Where to store files /mnt/storage
FILE_MANAGEMENT_S3_REGION Amazon S3 Region
FILE_MANAGEMENT_S3_ACCESS_KEY_ID AWS Access Key ID
FILE_MANAGEMENT_S3_ACCESS_KEY_SECRET AWS Access Key Secret
FILE_MANAGEMENT_S3_BUCKET_NAME AWS S3 Bucket Name

Misc App Configuration

Variable Description Default
ADMISSION_CONTROLLER_DEFAULT_ACTION The default behavior when we fail to validate whether or not an image is compliant for some reason. deny
GATEKEEPER_TEMPLATE_DIR Where gatekeeper templates should be loaded from dist/gatekeeper-templates
KUBEBENCH_CONFIG_DIR Where to load the kubebench configuration templates kube-bench-templates
RELEASE_NAMESPACE Where it should install things when using install wizards default

2 - Trawler Parameters

Instructions for Configuring Trawler

Trawler is our app for running scans of your containers. Right now, it is a wrapper around Trivy, one of the best container scanners available, but it is architected such that other scanners could be supported in the future (contributions are welcome!).

Functions

Trawler is normally run in listening mode in the cluster and in scanning mode when scanning a single image from a CICD Pipeline.

You can see how to use one mode or the other by just viewing the built-in help docs.

trawler help

The output looks something like this:

Usage:
trawler [-Dh] [-A=<m9sweeperApiKey>] [-H=<rabbitmqHostname>]
[-p=<rabbitmqPassword>] [-P=<trawlerParallelScanners>]
[-q=<rabbitmqQueueName>] [-t=<rabbitmqPort>] [-u=<rabbitmqUsername>]
[-U=<m9sweeperUrl>] [COMMAND]

Description:
Run Trawler in its RabbitMQ mode where it will monitor a specified RabbitMQ
queue for scan jobs.

Options:
-P, --parallel-scans=<trawlerParallelScanners>
number of scanners that Trawler can run at once
-U, --url=<m9sweeperUrl>   URL of the m9sweeper instance
-A, --api-key=<m9sweeperApiKey>
API Key of the m9sweeper instance
-D, --debug                whether to enable debug logs
-u, --rabbitmq-user=<rabbitmqUsername>
username of the RabbitMQ server
-p, --rabbitmq-password=<rabbitmqPassword>
password of the RabbitMQ server
-H, --rabbitmq-host=<rabbitmqHostname>
hostname of the RabbitMQ server
-t, --rabbitmq-port=<rabbitmqPort>
port of the RabbitMQ server
-q, --rabbitmq-queue=<rabbitmqQueueName>
name of the RabbitMQ queue to listen on
-h, --help                 display this help and exit

Commands:
scan  Scan a single docker image in the standalone scan mode.

Many settings can be set through the CLI.

Running an image scan is as simple as:

trawler scan alpine:3.15

Environment Variables

In addition to CLI parameters, you can also configure Trawler using environment variables. This is the norm when deploying a trawler runner to run automatic scans of new, unrecognized images as well as nightly image scans.

General Configuration Options

Parameter Description Default
M9SWEEPER_URL URL of m9sweeper API (required)
M9SWEEPER_API_KEY M9sweeper API Key
TRAWLER_RUN_MODE Whether to run as a passive scan worker (rabbitmq) or scan a single image and exit (scan) rabbitmq

Configuration Options for Running a Scan Worker

Parameter Description Default
TRAWLER_PARALLEL_SCANNERS When passively listening for scans, how many parallel workers to run 1
RABBITMQ_USERNAME RabbitMQ Username guest
RABBITMQ_PASSWORD RabbitMQ Password guest
RABBITMQ_HOSTNAME RabbitMQ Hostname rabbitmq
RABBITMQ_PORT RabbitMQ Port Number 5672
RABBITMQ_QUEUE_NAME RabbitMQ Queue Name to listen for Scans trawler_queue

Configuration Options for Scanning a Single Image

Parameter Description Default
CLUSTER_NAME Name of cluster to scan images for
DOCKER_IMAGE_URL Docker image url to scan

3 - API Docs

API Documentation.

API documentation is provided through swagger, which is available at /doc/. For example, if you are hosting it at m9s.yoursite.com, it would be available at https://m9s.yoursite.com/doc/