Skip to content

Configuration

Jump to bottom
danieljampen edited this page Jul 17, 2019 · 8 revisions

Structure

There are two main parts of the configuration file. The first part MULTIAV configures general options of the MultiAV:Extended 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
....

#=============================
## Plugin Configuration Part
[PLUGIN-A]
VARIABLE=VALUE
...
[PLUGIN-B]
VARIABLE=VALUE
...

MULTIAV:Extended configuration

General Settings

The first part of this section sets multiple configs which MultiAV:Extended 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: MultiAV:Extended 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.

Scan Strategy Settings

MultiAV:Extended 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 hypervisors / cloud computing services are supported and refer to the drivers parameter explination 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

PLUGIN_ID=10
#DOCKER_BUILD_URL_OVERRIDE=
DISABLED=1

(c) 2019 Daniel Jampen, ZHAW

Clone this wiki locally