Skip to content

Configuration

Jump to bottom
sakkiii edited this page Jul 2, 2021 · 2 revisions

Structure

There are two main parts of the configuration file. The first part MULTIAV configures general options of the MultiAV2 tool. The second part addresses the plugins to use where each plugin has its own section like PLUGIN-A.

#=============================
# General Settings Part
[MULTIAV]
VARIABLE=VALUE
...
#=============================
## Scan Strategy Settings Part
SCAN_STRATEGY=VALUE
....
#=============================
## Database Settings Part
DATABASE_PLUGIN=VALUE
DATABASE_HOST=VALUE
DATABASE_USER=VALUE
....
#=============================
## Plugin Configuration Part
[PLUGIN-A]
VARIABLE=VALUE
...
[PLUGIN-B]
VARIABLE=VALUE
...

MultiAV2 configuration

General Settings

The first part of this section sets multiple configs which MultiAV2 requires regardless of the used scan strategy (configured later). The default options are the following:

[MULTIAV]
INITIAL_SCAN_TIME_AVERAGE=20
DOCKER_NETWORK_NO_INTERNET=10.192.212.0/24
DOCKER_NETWORK_NO_INTERNET_NAME=multiav-no-internet-bridge
DOCKER_NETWORK_INTERNET=10.168.137.0/24
DOCKER_NETWORK_INTERNET_NAME=multiav-internet-bridge
  • INITIAL_SCAN_TIME_AVERAGE: MultiAV2 tracks how long scans take on average. This is used to calculate multiple metrics depending on the scan strategy in use. This config defines the initial value in seconds.
  • DOCKER_NETWORK_NO_INTERNET: Defines the subnet to use for the docker network without internet access. Use the CDIR notation to define the networks base address and subnet mask.
  • DOCKER_NETWORK_NO_INTERNET_NAME: Defines the name of the docker network without internet access.
  • DOCKER_NETWORK_INTERNET: Defines the subnet to use for the docker network with internet access. Use the CDIR notation to define the networks base address and subnet mask.
  • DOCKER_NETWORK_INTERNET_NAME: Defines the name of the docker network with internet access.

Database Settings

The first part of this section sets multiple configs which MultiAV2 requires regardless of the used database connection (configured later). The default options are the following:

DATABASE_PLUGIN=postgres
DATABASE_NAME=database_name
DATABASE_USER=database_user
DATABASE_PASSWORD=database_pwd
DATABASE_HOST=hostname
  • DATABASE_PLUGIN: MultiAV2 Only Support postgres
  • DATABASE_NAME: Database Name in postgres server
  • DATABASE_USER: Database username in postgres server
  • DATABASE_PASSWORD: Database password in postgres user
  • DATABASE_HOST: Database IP-Address in postgres user

Scan Strategy Settings

MultiAV2 supports three scan strategies. A scan strategy refers to the way the program handles the scan tasks and dispatches them. The following list briefly describes the strategies:

  • Local-No-Limit Strategy: MultiAV will create as much containers as required to execute all tasks simultaneously on the local system. This behavior could overload the system when too many scans are executed in parallel.
  • Local-Limit Strategy: The tasks will be dispached locally similar to the local-no-limit strategy. However, the strategy implements a queue in which each task is added on creation. You are able to define the maximal amount of containers and scans per container MultiAV is allowed to create. This allows to define boundaries to prevent overloading problems as possible with the local-no-limit strategy.
  • Auto-Scale Strategy: This strategy uses the power of docker-machine to create worker nodes which it'll use to execute the actual scans. It automatically creates new workers if the current queue could be processed faster with more worker nodes. The settings in the config file allow you to define boundaries like the minimal and maximal amount of workers the system is allowed to handle or the docker-machine create command the system has to execute to create a new worker node.

Local-No-Limit Strategy

SCAN_STRATEGY=local-no-limit
MAX_SCANS_PER_CONTAINER=1
  • MAX_SCANS_PER_CONTAINER: defines the maximal amount of scans a container is allowed to processes in parallel. Choose 1 as limit to create a system where each scan is executed in it's own scan-container to prevent possible side effects by other scans which could impacting the scan result.

Local-Limit Strategy

SCAN_STRATEGY=local-limit
MAX_CONTAINERS = 8
MAX_SCANS_PER_CONTAINER=1
  • MAX_CONTAINERS: defines the maximal amount of container the system is allowed to create.
  • MAX_SCANS_PER_CONTAINER: defines the maximal amount of scans a container is allowed to processes in parallel. Choose 1 as limit to create a system where each scan is executed in it's own scan-container to prevent possible side effects by other scans which could impacting the scan result.

Auto-Scale Strategy

SCAN_STRATEGY=auto-scale
EXPECTED_MACHINE_STARTUP_TIME=130
MINIMAL_MACHINE_RUN_TIME=480
MIN_MACHINES=1
MAX_MACHINES=16
MAX_SCANS_PER_CONTAINER=1
MAX_CONTAINERS_PER_MACHINE=8
CMD_DOCKER_MACHINE_CREATE=
  • EXPECTED_MACHINE_STARTUP_TIME: set the time you think is required to create a new worker node with docker-machine and upload all docker images to it. This time is used as initial time and will be updated with each created machine to be more accurate.
  • MINIMAL_MACHINE_RUN_TIME: defines the time a worker node should be online at minimum. After creation of the worker node, a timer with the value of this config is created. The executed function then checks whether the machine is actually still used and automatically shuts the machine down if not. The system automatically handles the MIN_MACHINE requirement and does not shut down machines when the defined minimal amount is reached.
  • MIN_MACHINES: defines the minimal amount of worker nodes the system should have running at all times. This value can also be set to 0 if you do not wish to have any idle workers at any time. Note that setting MIN_MACHINES to 0 impacts the scan time of the first scan, as before executing the scan, the system has to create at least one worker node which could take some time.
  • MAX_MACHINES: defines the maximal amount of worker nodes the system is allowed to create.
  • MAX_SCANS_PER_CONTAINER: defines the maximal amount of scans a container is allowed to processes in parallel. Choose 1 as limit to create a system where each scan is executed in it's own scan-container to prevent possible side effects by other scans which could impacting the scan result.
  • MAX_CONTAINERS_PER_MACHINE: defines the maximal amount of container the system is allowed to create per worker node.
  • CMD_DOCKER_MACHINE_CREATE: set the docker-machine create parameters here. the system appends what ever you'll set here to "docker-machine create " and executes it in order to create a new worker node. Check out the docker-machine drivers page here to see which hyper-visors / cloud computing services are supported and refer to the drivers parameter explanation section to learn about the required parameters. Example for openstack (replace all values in curly brackets according to your setup): CMD_DOCKER_MACHINE_CREATE=openstack --openstack-flavor-id {id} --openstack-image-id {guid} --openstack-auth-url https://xxx.yyy:5000/v3 --openstack-username {username} --openstack-password {password} --openstack-tenant-id {id} --openstack-tenant-name {name} --openstack-domain-name Default --openstack-ssh-user {user}.

Plugin Configuration

For each plugin, the config file has it's own section with the corresponding config. The config values which are viable for all plugins are described below. Additionally, please refer to the default config file here as it contains all possible config values for all supported plugins.

[PLUGIN-A]
#SCAN_TIMEOUT=
#DOCKER_BUILD_URL_OVERRIDE=
#ENABLE_INTERNET_ACCESS=
DISABLED=1
  • [Optional] SCAN_TIMEOUT: overwrites the timeout of the scan call itself. if the scanner does not report any results after the timeout expires, the result will be set to "timeout".
  • [Optional] DOCKER_BUILD_URL_OVERRIDE: can be used to set an URL from which the system will build the container instead of trying to pull it from the official docker store.
  • [Optional] ENABLE_INTERNET_ACCESS: allows to enable internet access for this plugin. If enabled (value set to 1), the container will be placed in a network with internet access. WARNING this could result in samples leaked to the vendors of the plugin.
  • DISABLED: set this value to 0 or False to enable respectively to 1 or True to disable the plugin .

NOTE: Each plugin could have own, additional configs. They are preset in the default config file and explained in the config file itself.

Don't forget to ⭐ this repo if you like MultiAV2!
Clone this wiki locally