Skip to content
This repository

RPC Server (Dispatcher) -- v0.4.6

Dispatchers are remote agents which provide you with scanner Instances -- Instances are the entities that actually perform the scans.

Its main job is to maintain a pool of Instances and, whenever a clients issues a dispatch RPC call, to pop one from the pool and pass its connection details (URL and authentication token) to the client.

Just as importantly, it's responsible for never letting the pool deplete by replenishing it after every dispatch call.

Setting up Dispatchers across multiple machines allows you to spread out the workload of many scans across multiple nodes.

If you are interested in providing webappsec scanning services you can write your own client using the RPC API.



Starting a Dispatcher can be as simple as running: arachni_rpcd

This will bind on localhost:7331 by default.


A grid is a network of interconnected Dispatchers which can be quite useful when dealing with large workloads.

In order to connect Dispatchers into a Grid you'll need to:

  • Specify an IP address or hostname on which the Dispatcher will be accessible by the rest of the Grid nodes (i.e. other Dispatchers).
  • Specify a neighbouring Dispatcher when running a new one.

After that, they will build and maintain their network themselves.

Load balancing

Load balancing is the default operation of the Grid; nomatter which member receives the dispatch call, the Instance will be provided by the least burdened member.

This is completely transparent to the client and allows you to easily scale up your operation by simply adding more Dispatchers to the Grid as necessary.

To (un)favor certain Dispatchers you can use the --weight option, the given float will be multiplied against the load-balancing score of a Dispatcher and that product will serve as the new score -- lower is better.


Starting the first Dispatcher:

arachni_rpcd --nickname="My Dispatcher" --address=

Adding more in order to form a Grid:

arachni_rpcd --nickname="My second Dispatcher" --address= --neighbour=

Lather, rinse, repeat:

arachni_rpcd --nickname="My third Dispatcher" --address= --neighbour=
arachni_rpcd --nickname="My fourth Dispatcher" --address= --neighbour=

Line aggregation

In addition to the default Grid setup requirements, line-aggregation also requires a bandwidth pipe identifier used to distinguish between the different paths to the target web application. This allows the system to identify independent bandwidth lines to the target in order to split the workload in a way that will aggregate the collective bandwidth.

Line aggregation only takes effect when performing multi-Instance scans and the :grid_mode option has been explicitely set to :aggregate (see Instance#scan).


Starting the first Dispatcher:

arachni_rpcd --pipe-id="Pipe 1" --nickname="My Dispatcher" --address=

Adding more in order to form a Grid:

arachni_rpcd --pipe-id="Pipe 2" --nickname="My second Dispatcher" --address= --neighbour=

Lather, rinse, repeat:

arachni_rpcd --pipe-id="Pipe 3" --nickname="My third Dispatcher" --address= --neighbour=
arachni_rpcd --pipe-id="Pipe 4" --nickname="My fourth Dispatcher" --address= --neighbour=

Security considerations

This is very important, you should read it thoroughly.

By default, all connections are performed over encrypted sockets using SSL. This takes care of encryption but not authN/authZ which is a very important issue when it comes to the Dispatcher.

The Dispatcher is a dispatch server, and as such, its focus is on maintaining a pool of running servers, ready to be used at a moment's notice. A major part of maintaining that pool is replenishing it once a dispatch call has been performed -- i.e. when a server if pop'ed from the pool, another one must be pushed.

When you take into account that server shutdown is delegated to the client the security issue becomes crystal clear. Clients can easily fork-bomb the machine on which a Dispatcher is running.

This makes it crucial to provide Dispatcher access to trusted clients only. Sufficient authN/authZ can be achieved by either:

  • Configuring the relevant SSL options for both the clients and dispatch servers.
  • Rolling your own network security scheme via a VPN or something similar.

Help output

The help output of the RPC server if fairly straightforward:

Arachni - Web Application Security Scanner Framework v0.4.6
   Author: Tasos "Zapotek" Laskos <>

           (With the support of the community and the Arachni Team.)


  Usage:  arachni_rpcd [options]

  Supported options:

    --help                      output this

    --address=<host>            specify address to bind to
                                    (Default: localhost)

    --external-address=<host>   specify the external address used to access this Dispatcher
                                    (Defaults to the value of '--address'.)

    --port=<num>                specify port to listen to
                                    (Default: 7331)


                                specify port range for the RPC instances
                                    (Make sure to allow for a few hundred ports.)
                                    (Default: 1025-65535)

    --reroute-to-logfile        reroute all output to a logfile under 'logs/'

    --pool-size=<num>           how many server workers/processes should be available
                                  at any given moment (Default: 5)

    --neighbour=<URL>           URL of a neighbouring Dispatcher (used to build a grid)

    --weight=<float>            weight of the Dispatcher

    --pipe-id=<string>          bandwidth pipe identification

    --nickname=<string>         nickname of the Dispatcher


    SSL --------------------------

    (All SSL options will be honored by the dispatched RPC instances as well.)
    (Do *not* use encrypted keys!)

    --ssl-pkey   <file>         location of the server SSL private key (.pem)
                                    (Used to verify the server to the clients.)

    --ssl-cert   <file>         location of the server SSL certificate (.pem)
                                    (Used to verify the server to the clients.)

    --node-ssl-pkey   <file>    location of the client SSL private key (.pem)
                                    (Used to verify this node to other servers.)

    --node-ssl-cert   <file>    location of the client SSL certificate (.pem)
                                    (Used to verify this node to other servers.)

    --ssl-ca     <file>         location of the CA certificate (.pem)
Something went wrong with that request. Please try again.