RPC server

Tasos Laskos edited this page Feb 2, 2016 · 23 revisions


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-name="Pipe 1" --nickname="My Dispatcher" --address=

Adding more in order to form a Grid:

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

Lather, rinse, repeat:

arachni_rpcd --pipe-name="Pipe 3" --nickname="My third Dispatcher" --address= --neighbour=
arachni_rpcd --pipe-name="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 is fairly straightforward:

Arachni - Web Application Security Scanner Framework v1.1
   Author: Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>

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

   Website:       http://arachni-scanner.com
   Documentation: http://arachni-scanner.com/wiki

Usage: ./bin/arachni_rpcd [options]

  -h, --help                  Output this message.

      --version               Show version information.

      --address ADDRESS       Hostname or IP address to bind to.

      --external-address ADDRESS
                              Hostname or IP address to advertise.

      --port NUMBER           Port to listen to.
                                (Default: 7331)

      --port-range BEGINNING-END
                              Specify port range for the spawned RPC instances.
                                (Default: 1025-65535)

      --pool-size SIZE        How many Instances to have available at any given time.
                                (Default: 5)

      --reroute-to-logfile    Reroute all output to log-files under: /Users/zapotek/workspace/arachni/logs/

      --verbose               Show verbose output.
                                (Only applicable when '--reroute-to-logfile' is enabled.)

      --debug [LEVEL 1-3]     Show debugging information.
                                (Only applicable when '--reroute-to-logfile' is enabled.)

      --only-positives        Only output positive results.
                                (Only applicable when '--reroute-to-logfile' is enabled.)

      --neighbour URL         URL of a neighbouring Dispatcher.

      --weight FLOAT          Weight of this node.

      --pipe-id ID            Identifier for the attached bandwidth pipe.

      --nickname NAME         Nickname for this Dispatcher.

      --ssl-ca FILE           Location of the CA certificate (.pem).

      --server-ssl-private-key FILE
                              Location of the server SSL private key (.pem).

      --server-ssl-certificate FILE
                              Location of the server SSL certificate (.pem).

      --client-ssl-private-key FILE
                              Location of the client SSL private key (.pem).

      --client-ssl-certificate FILE
                              Location of the client SSL certificate (.pem).

      --snapshot-save-path DIRECTORY
                              Directory under which to store snapshots of suspended scans.