Quick Start

Currently, only Docker Compose based deployment is supported.

Using Docker Compose

First, you need to prepare a machine. The recommended configuration for the scanning machine is:

  • 16GB of RAM,

  • 2 cores,

  • 30GB of free disk space to store Docker images and scan results.

To start Artemis:

  • clone the https://github.com/CERT-Polska/Artemis/ repository,

  • copy the .env.example file to .env,

  • set FRONTEND_USERNAME and FRONTEND_PASSWORD in .env (these credentials will be required when logging in at localhost:5000),

  • execute the following command in your terminal in the Artemis directory:

    ./scripts/start --mode=<production|development>

After that you should be able to access the Artemis dashboard at localhost:5000.

The above command will automatically create a .env file with default settings if it doesn’t exist. You can edit this file later to configure various settings, including customizing the user-agent by setting the CUSTOM_USER_AGENT variable, as well as other relevant parameters.

We strongly recommend setting the CUSTOM_USER_AGENT and configuring rate-limiting for scanning (more information here: Cooperation with scanned entities). For a complete list of configuration variables and their descriptions, please refer to the Configuration options section in the documentation.

Note

Setting the mode to development provides you with some quality of life changes when developing project, e.g. enables use of pdb in the containers, opens postgres container port to your machine, starts web container in hot reload and mounts working directory to volumes of Karton workers

We recommend you to add additional Artemis modules from https://github.com/CERT-Polska/Artemis-modules-extra/ - these modules haven’t been included in core due to licensing reasons, but provide additional features such as e.g. SSL verification (certificate validity, proper redirect, etc.), subdomain takeover check or SQL injection check.

To do that, clone https://github.com/CERT-Polska/Artemis-modules-extra/ inside the Artemis directory and run ./scripts/start.

Note

Artemis exposes its API/web interface on port 5000. Even with authentication enabled, it is strongly recommended not to expose this port publicly (e.g. keep it on an internal network only), to prevent unauthorized use of the scanner and reduce exposure to attacks such as brute force or credential stuffing.

To add SSL termination consider using a reverse proxy such as nginx.

If you want to increase the number of instances of a module to speed up scanning, modify the numbers of instances in the .env file (by adding or updating the NUM_WORKERS_PER_CONTAINER_MODULE_NAME setting, e.g. by changing NUM_WORKERS_PER_CONTAINER_BRUTER=5 to NUM_WORKERS_PER_CONTAINER_BRUTER=20).

By default some modules are spawned in a couple of instances, but you may want more of them.

For the full list of available configuration options you may set in the .env file, see Configuration options.

Note

If you get an error that docker compose is not a valid command, that means that Docker Compose plugin is not installed. Please follow the instructions from https://docs.docker.com/compose/install/linux/#install-using-the-repository

The old docker-compose syntax is not recommended.

Adding targets to scan

To add targets to be scanned, select Add targets from the top navigation bar. Artemis takes input in the form of entries separated with newlines. Artemis works with both IPs and domains. It also supports IP ranges, both in the form of 127.0.0.1-127.0.0.10 or 127.0.0.0/30 and host:port syntax - in the latter case, no port scanning will be performed.

To be later able to filter various types of targets, provide a tag in the Tag field. You may also choose what modules will be executed, to increase scanning speed if you need only to check for a subset of vulnerabilities.

_images/adding-targets.png

Viewing results

To view results, click the View results link in the top navigation bar:

_images/viewing-results.png

Exporting reports

Besides viewing the raw results, you may want to generate HTML reports containing descriptions of found vulnerabilities, so that you can notify the administrators to get the vulnerabilities fixed.

To do that, please refer to Generating reports to be sent.

Stopping Artemis

To turn off Artemis (without removing the scan results and pending tasks), use:

./scripts/run_docker_compose --mode=<production|development> down

To remove all data, use:

./scripts/run_docker_compose --mode=<production|development> down --volumes