Traffic Enforcement Configuration

Once the application is up and running, it’s time to configure it for enabling traffic mitigation. This means we need to create virtual scrubbers (objects containing protection policies based on target), each virtual scrubber inspects the traffic matching one, or more, destination subnets. Each virtual scrubber, identified by a target ID, has its own traffic enforcement profiles that can be configured/changed/inspected at runtime using the API.

This sections provides some basic knowledge for configuring the engine using the REST API. Please refer to the API documentation for the full API specifications.

Note that although this section covers the configuration using the REST API, a few command line tools (see Appendix A) are also available to ease the configuration, including:

  • nscrub-cli, implementing a console with autocompletion with all the functionalities implemented by the REST API.
  • nscrub-add, a wizard tool for creating new victims with a basic configuration (further customisations are usually needed using nscrub-cli or the API).
  • nscrub-export, a tool for dumping the current configuration for a specific victim.

Default credentials for configuring nscrub:

Username admin
Password admin
HTTP port 8880
HTTPs port 4443
Socket binding localhost


nScrub listens on localhost by default, please configure a different address (-G option) to use the REST API from a remote machine.

If you lost the admin password, you can reset it following the instructions below:

  1. shutdown nscrub
  2. run “redis-cli del nscrub.user.admin.password”
  3. restart nscrub

Victims definition

Victims can be dynamically added, removed and configured at runtime.

Read active victims using the REST API:

curl -u <user>:<password> "http://<host>:<port>/targets?action=list"

or do the same using the command line tool:

localhost:8880> list targets

Add a new victim:

curl -u <user>:<password> "http://<host>:<port>/targets?action=add&target_id=<victim name>&subnet=<subnet (CIDR notation)>"

Each victim is bound to a few profiles: default, black, white, gray. The default profile applies to all unknown sources, while the other profiles apply to the corresponding lists of source IPs (attackers). In essence black, white and gray are just placeholders for defining different traffic enforcement policies based on source IP “colour”. The white profile is a special profile, in fact source IPs recognised as real and legitimate are automatically added to this special list.


This section provides only a few examples of victim configuration, for the full settings please refer to the API documentation.

It is a common practice to set the “drop all” policy to the black profile:

curl -u <user>:<password> "http://<host>:<port>/profile/all/drop?target_id=<victim name>&profile=black&action=enable"

It is also a common practice to set the “accept all” policy to the white profile:

curl -u <user>:<password> "http://<host>:<port>/profile/all/accept?target_id=<victim name>&profile=white&action=enable"

The gray profile is usually used for applying special policies to “special” IPs. For instance it is a common practice to set the “default” policy to “drop” and then specify more specific policies to let specific traffic types through.

curl -u <user>:<password> "http://<host>:<port>/profile/default?target_id=<victim name>&profile=gray&action=update&value=drop"

The default profile is where the real traffic enforcement policies go, for checking unknown traffic. For instance it is also a common practice to set the default policy to drop:

curl -u <user>:<password> "http://<host>:<port>/profile/default?target_id=<victim name>&profile=default&action=update&value=drop"

Accept ICMP:

curl -u <user>:<password> "http://<host>:<port>/profile/icmp/accept?target_id=<victim name>&profile=default&action=enable"

Drop UDP:

curl -u <user>:<password> "http://<host>:<port>/profile/udp/drop?target_id=<victim name>&profile=default&action=enable"

Accept UDP port 53 (DNS):

curl -u <user>:<password> "http://<host>:<port>/profile/udp/src/53/accept?target_id=<victim name>&profile=default&action=enable"

Check TCP traffic:

curl -u <user>:<password> "http://<host>:<port>/profile/tcp/syn/check_method?target_id=<victim name>&profile=default&action=update&value=rfc"

It is also possible to set a rate limiter (in this example per source) to set a threshold to the traffic rate.

curl -u <user>:<password> "http://<host>:<port>/profile/rate?target_id=<victim name>&profile={black, white, gray, default}[&action=update&value=<pkts/s>]"

Many more policies are available, please refer to the full API documentation.

Please note all the settings can also be read, omitting the action (and value) parameter.

In order to temporarily disable traffic checks, it is possible to put the system in bypass state, both globally:

curl -u <user>:<password> "http://<host>:<port>/bypass?[action={enable, disable}]"

or per victim:

curl -u <user>:<password> "http://<host>:<port>/profile/bypass?target_id=<victim name>&profile=default[&action={enable, disable}]"