Select Page

The security community develops and compiles all sorts of warnings and mitigation advisory events. This can include everything from downloadable blacklists with IP addresses with reported network cracking activity to advanced IDS/IPS systems like Bro which monitor traffic in your network and can pinpoint specific connections as attacks. One of the largest issues today is not getting this information, but figuring out how to make the best use of it. Traditionally, these events may have resulted in additional firewall rules at a single point of entry for a network or an individual host. This tends to be limiting such as ignoring east-to-west traffic in the former case or costing valuable CPU cycles in the latter. In either case, much of the cyber intel that exists both within a network and without is underutilized, if at all.

Thankfully, the switches used in the OpenFlow networks of today are more than capable of handling the resulting mitigation rules. Often, the only missing link is the controller that will inject mitigation events into the switches as flow entries in a network pipeline. Writing or modifying a controller to be cybersecurity-aware can be quite the task, but made easier by understanding some basic network pipeline mechanics. In this article, we will cover a point-solution training and research controller developed by Inside OpenFlow that can help with understanding abstract cybersecurity network pipelines including how security events can be turned into mitigation rules for every OpenFlow switch in a network. Let’s put that intel to work!

Mitigation Cybersecurity

Knowing that your network is under attack or may come under attack by certain hosts doesn’t do a lot of good if your network can’t use that information. When a host or connection is known to be a bad actor, your network must mitigate the situation. This is where Mitigation Cybersecurity comes into play. The basic concept is that there is some intelligence gathering application or service (either internal or external) is providing information about current threats. Cybersecurity intelligence can then be used in a variety of places to help protect your hosts. This information should be used wherever it can to protect your network. Ideally, the mitigation of attacks and threats should be layered from your Internet routers and firewalls right down to the hosts with each providing protection using their greatest strengths. This means that even (and especially) the network switches themselves should help with this mitigation to the fullest of their abilities and this is our main focus in this track.

Inside OpenFlow SecSwitch IP Reputation - End to End Protection

One of the basic types of cybersecurity intelligence comes in the form of simple IP blacklists. These may be compiled from third party companies that watch multiple networks and keeps track of bad actors and from internal monitoring applications such as Fail2Ban or Bro. Blacklists and whitelists are related to IP Reputation. More broadly, IP Reputation can assign a level of trustworthiness to an IP address. Negative IP Reputation intelligence could obviously come from the blacklists generated by internal and external intelligence as discussed above. Similarly, positive IP Reputation can come from whitelists written by internal network engineers for various reasons. One thing IP Reputation does not assume, however, is the action that should be taken on that reputation. In some networks, packets may be put under more scrutiny and processed by different means rather than blocking an IP address outright. This is why the pipeline stage we are going to cover is called IPRep rather than ACL or Blacklist. Although in this article it acts as a blacklist, later articles will expand on the function if the IPRep stage to just providing metadata information in the switch’s pipeline and move the final actions to another stage based on reputation.

Inside OpenFlow Security Switch

Inside OpenFlow is developing a Security Switch controller that addresses certain points provided in the articles in this Cybersecurity Track. That controller, called Security Switch, is designed to be an academic and demonstration tool that is easy to expand and understand. For the purposes of this article, we will cover the Mitigation API implemented for Security Switch and how that translates into a functional security platform. As we are covering blacklists, that is the focus of development for the version you will get to play with a bit later in the article.

Here we have a simplified overview of the end-to-end mitigation process covering three major areas of concern: getting mitigation rules into Security Switch (Mitigation API), storing mitigation rules where it can be observed (Live Controller Configuration), and transforming the rules to OpenFlow Flow Entries (IP Reputation Controller Stage).

Directly translating mitigation events from sources like an IDS into OpenFlow flow entries is not all that difficult and could be implemented in a specially designed Ryu App all in one go. The problem with this method is that it’s like programming directly in assembly language. Yeah, it would work and may be efficient at first, but it can be a pain to debug or fundamentally change any part of the controller. Over time, this results in spaghetti code, difficulty in training new developers, and possibly forced rewrites when the needs of the network change too much outside the original design parameters. This is why Security Switch is written in discrete exchangeable components more akin to high-level object-oriented programming.

Northbound Mitigation API

Security Switch provides a uniform REST API for Northbound communication from other applications. It is designed to be as accessible as possible using the most common web-based API style today. Information from external applications providing mitigation instructions is processed by an application-specific shim that converts the data into the appropriate JSON structure and sent over an HTTP request. Just about any programming language has native HTTP client and JSON libraries without the need for external dependencies. Further, any application developer who has had to interact with a third party REST API should feel right at home with Security Switch’s Mitigation API.

Inside OpenFlow Security Switch IP Reputation - Mitigation API

The idea of using shims to allow many applications to provide properly converted information to a central application is not a new idea. For example, Logstash, a log aggregation and filtering application, has over 50 officially supported input shim plugins supporting log entries from hundreds of different applications. Rather than implementing each shim in the main program, using external shims communicating with a standardized API allows for easy conversion of custom data.

In Security Switch’s case, these shims convert application events or other data into mitigation instructions. The Mitigation API itself has a couple endpoints in the release for this article: rules to access a list of rules in the IPRep configuration and drop_address to add a blacklist rule to the IPRep configuration. The API module does not depend on any internal knowledge of how the rules are finally implemented on the switch or even in the IPRep stage in the controller itself.

IP Reputation Stage and Live Configuration

When the Mitigation API receives a command such as drop_address, the supplied IP address is added to an object that implements a common Python interface for a setdoc. That set is accessed on the global live configuration tree and its self.add method is called with the IP address. Other than some code that ensures the supplied IP address is valid, the API code makes no further attempt process the instruction. Handling things like duplicates is assumed to be handled in the set as that is a property of that type (a set may not contain duplicate values).

Inside OpenFlow SecSwitch IP Reputation - IPRep and Live Config

On the other end of the live configuration tree is the IP Reputation stage of the controller pipeline. In keeping with separated concerns, the IPRep stage knows nothing about the Mitigation API or even the internals of the configuration tree. All it knows is that a list of rules will be available on the configuration tree at a set location. Further, the IPRep stage informs the configuration tree that it wishes to be notified when any changes to that set location is made, such as a rule being added or discarded.

The live configuration tree acts as the middleman providing some simple Pythonic interfaces that makes it easy on the developer to use. There is a bit going on internally (and I may cover in a future article) but neither the producers or consumers need to know about its implementation.

Southbound OpenFlow Messages

Now that the IP Reputation stage has access to the rules it should implement and when changes occur, it can focus on its job of controlling its owned table in an OF Switch. Keep in mind that this is only a single Stage in a Pipeline Instance for a specific OpenFlow switch. The IP Reputation stage is only supposed to handle its own tasks (adding flows that drop packets in a blacklist) and ensure that a table-miss flow forwards any unmatched packets to the table owned by the next stage in the Pipeline.

Inside OpenFlow Security Switch IP Reputation - IPRep to OpenFlow

From the event triggered when an IP is added to the blacklist (or initial reading of the configuration), the information passes through a few modifiers along the way. The IPRep stage converts blacklist entries into a higher-level match format. Specifically, it converts the IP address to something like {"ip_src": <IP>} which does not specify the IP version on purpose. It also does not contain information like the EtherType which the final flow will require. Instead, there is a match normalization function in Security Switch that converts the simplified form into a fully specified match condition including the appropriate EtherType and IP source field (ipv4_src or ipv6_src) based on parsing the IP address supplied. This final match condition is then placed in a FlowMod message with an empty action and sent to the Pipeline’s assigned OpenFlow Switch.

Now that the overall process is explained from start to finish, we can move on to actually testing out Security Switch.

Software Setup

This article covers two Inside OpenFlow applications: Security Switch, the controller, and Security Test, the testing environment for the controller. The system requirements are similar to our Simple Switch Reimagined. As always, we recommend using the VM set up in our Core OpenFlow Track and suggest running sudo apt-get dist-upgrade to make sure the VM is completely up to date.

Setup from Scratch (Didn't follow the Core OpenFlow Track)

If you did not follow the Core OpenFlow Track or need to build a new VM, follow these directions:

If you don’t want to follow those articles, here are the minimum requirements:

  • VM under VirtualBox or VMware with 4GB RAM (8GB recommended) and 4 cores (8 recommended).
  • Ubuntu 16.04.1 fully updated with sudo apt dist-upgrade. Note: Ubuntu automatically downloads and installs security updates shortly after boot so if you get a Resource temporarily unavailable error, wait a few moments and try again. This will take a few minutes on a new install.
  • Mininet 2.3.0d1 or above FROM SOURCE (use the repo linked)
  • Postman or some other REST API dev tool (examples assume Postman and our Postman Collections are only tested on Postman)
    • If not using the Chrome app, download the Linux standalone app beta from the Apps link at the top of the page, then click “Download Postman for Linux (Beta)”, then: You can skip the login process if you wish. On the Launcher (left menu), right click the Postman icon and click Lock to Launcher for easier starting. Otherwise, just install Chrome and the Chrome App, which will automatically add it to the Dash and can be added to the Launcher from there.
  • Atom or some other IDE supporting Python and CoffeeScript if you wish to browse the code (examples assume an up-to-date Atom)
    • To install, click the atom-amd64.deb file in the Downloads dropdown in Firefox or double click it from the Downloads folder in Files. Click the “Install” button when the Ubuntu Software app loads. Enter your password at the permissions prompt. Launch by opening the Dash and typing Atom. Click the Atom icon. Lock it to the Launcher if you wish.
    • Go to Edit → Preferences then click the Install tab on the left. Install the following packages:
      • autocomplete-python
      • linter-pylint
    • The following packages are recommended for ease of use depending on other editors you might use:
      • file-icons
      • minimap
      • minimap-highlight-selected
      • minimap-find-and-replace
      • minimap-git-diff
      • vim-mode-plus
      • vim-mode-plus-ex-mode
      • hyperclick
  • Byobu is recommended and is used in the screenshots on this site. It is a text-based window manager and terminal multiplexer providing additional functionality over screen and tmux. To install: It can be started by running byobu in an existing terminal session or running “Byobu Terminal” from the Dash. Press F1 for help in Byobu for keyboard shortcuts and the like.

The IOF Security Switch uses Python 3.5+ and will require the development libraries to be installed:

Updating Atom and its Configuration

If you are following along with Atom as your IDE, you may wish to update Atom to the latest version by going to and downloading the latest deb. Double click the deb file and upgrade as normal. Also, upgrade any installed Atom packages by clicking Edit → Preferences, clicking Updates, then updating all packages.

Update your linter-pylint configuration to use pylint3 under “Executable”. You may also want to update autocomplete-python‘s “Python Executable Paths” to also include $PROJECT/env/py3/bin/python3.

Finally, vim-mode was deprecated and now vim-mode-plus is recommended instead. Uninstall the vim-mode and ex-mode packages and install vim-mode-plus and vim-mode-plus-ex-mode.

Installing Security Switch

Downloadable Content – IOF Security Switch Controller

Download IOF Security Switch v0.1.2

Now that your environment is ready, download the Security Switch package above and extract it into a new folder under your OpenFlow workspace:

Now run the tools/env-exec script to set up the private environment Security Switch requires:

This will install all the additional libraries and runtimes required. Run the tests if you wish:

Inside OpenFlow Security Switch IP Reputation - SecSwitch Installed and Tested

Installing Security Test

The Security Test environment includes the custom Mininet topology we will be using in this article which is capable of emulating a few thousand hosts in a WAN (defaults to 100 hosts). Go ahead and download the Security Test archive and extract it aside the Security Switch package:

Downloadable Content – IOF Security Test – Security Controller Testing Environment

Download IOF Security Test v0.1.2

Now run Security Test’s env-exec to install additional libraries and runtimes required:

Inside OpenFlow Security Switch IP Reputation - SecSwitch Environment Setup

Quick Test

Now that both environments are set up, let’s perform a quick test to make sure it is working as expected. Open two terminals, one in each environment. If using Byobu, just press Ctrl+F2 instead to split the current terminal vertically.

Inside OpenFlow Security Switch IP Reputation - SecSwitch and SecTest Environments Side by Side

In the Security Switch environment, start ryu-manager with the IPRep demo:

Inside OpenFlow Security Switch IP Reputation - SecSwitch IPRep Demo Controller Started

Now in the Security Test environment, start Mininet with the Security Test topology:

Inside OpenFlow Security Switch IP Reputation - Mininet Started with SecTest Topology

First, perform a quick pingall command in Mininet. This will ensure that all the hosts in the topology specified can connect with each other.

Inside OpenFlow Security Switch IP Reputation - Mininet Pingall Success

Then, run the custom pingbulk command to have one of the hosts ping all emulated WAN IPs on the WAN host and then another pingbulk command to have all emulated WAN IPs ping a specific host:

Inside OpenFlow Security Switch IP Reputation - SecTest Pingbulk Success with No Blacklist

Start a new terminal in the Security Switch environment or press Shift+F2 in Byobu to split the current session horizontally. Run the following command:

Inside OpenFlow Security Switch IP Reputation - SecSwitch Drop Address API Call

Run the pingbulk commands again and we should now see that one of the WAN addresses failed to be pinged and is unable to ping:

Inside OpenFlow Security Switch IP Reputation - SecTest Pingbulk with Expected Failure

If everything looks as expected, now we can cover how to use the Mitigation API.

Mitigation API

The Mitigation REST API is a work in progress and will be expanded as this Cybersecurity Track covers additional issues. It is not meant as a be-all and end-all method of creating an API for cybersecurity mitigation. The same is true of Security Switch itself. Instead, these are guides on how someone might choose to attack cybersecurity issues and hopefully provide some insight and new ideas to the party. That said, let’s take a look at what is currently in the Mitigation API and what is planned.


Much of the design for the data structure and API endpoints is heavily based on Bro’s NetControl API. In fact, this track is planned to cover full integration with Bro with Security Switch as the example, but there is quite a bit that is needed before we get there and that is what we will be discussing between now and then.

As mentioned, the Mitigation API is an HTTP-based API designed to be RESTful, meaning that it uses HTTP commands and URIs to represent the state of the mitigation live configuration. There were several other options like XML-RPC and SOAP, but REST APIs with JSON tend to be much easier to implement and use and are now far more popular. Further, a REST API allows just about any program to interact with the controller in any modern language with relative ease. As an example, the CLI tool used to call the drop_address endpoint in the previous section is actually written in CoffeeScript (a transpiled ECMAScript language) and runs on Node.js.

The API is implemented through Ryu’s built-in WSGI framework. This allows it to be compatible with other Ryu applications that also provide REST and WebSockets APIs. The development plan for Security Switch is to also provide the API through WebSockets using the same WSGI framework to leverage the event-based nature of Security Switch itself.


The Mitigation API has a URI root of /v1.0/mitigation/ with the endpoints underneath. Body content both to and from the API are expected to be well-formed JSON documents with a content type of application/json. The currently implemented endpoints are:

  • rules (GET) – Retrieve a list of active mitigation rules exposed as objects.
    Example: GET http://localhost:8080/v1.0/mitigation/rules
    Provides (pretty-printed):

    The list includes the drop rule added by the drop_address endpoint used in the previous section.
  • drop_address (POST) – Adds a drop rule with the specified IP address.
    Example: POST http://localhost:8080/v1.0/mitigation/drop_address
    POST Data: {"address": ""}
    Provides: (pretty-printed):

    The response is the rule object created from the command that is added to the mitigation rule set. This command is also idempotent; if the resulting rule is already in the mitigation rule set, no action is taken and the response is guaranteed to have the equivalent rule data already in the rule set.

The immediately planned endpoints include:

  • rules (POST) – Insert a new fully-qualified rule.
    The drop_address endpoint is a convenience method that creates and inserts the fully qualified rule. Since this first iteration of Security Switch only contains a blacklist, POSTing a new rule is redundant. Later versions will support other rule and entity types. This will also be the only way of adding some types of rules that do not have high-level methods like drop_address.
  • rules/<id|cid> (GET, PUT, PATCH, DELETE) – Perform various actions on a specific rule based on the internal ID (id) or the optional client ID (cid).

Testing the Mitigation Pipeline with IOF Security Test

In this initial version of Security Switch, we have some basic filtering available on the traffic between hosts in the network. We also need a way to properly test the capabilities of Security Switch and that is where Security Test comes in. Security Test is designed to provide tools and a network topology to test Security Switch as it develops. When new features are added to Security Switch, new tools and tests will be added to Security Test. Let’s go over a few of the features and how they can be used to test your own modifications and environments.

Mininet Topology with Emulated WAN

One of the central features to Security Test is its Mininet topology. It is based on the Datacenter Topology discussed in Custom Mininet Topologies and Introducing Atom. It was expanded in two major ways: the addition of a WAN host and the automatic configuration of the Mininet hosts so they have access to the Security Test tools.

Security Test Mininet Topology

Each host has a custom mount point that allows easy access to the Security Test tools. When the host is initiated, its own /sectest mountpoint is bound to the Security Test project directory where the topology source lives, wherever that may be. In addition, each host is provided with the Security Test private environment so each command run through mininet is effectively run with tools/env-exec.

As with the original datacenter topology, the number of racks and hosts per rack can be changed at start. By default, it starts 2 racks with 2 hosts per rack. If you wanted to have 5 racks, each with 10 hosts, you can change the --topo=sectest argument to --topo=sectest,5,10.

Finally, the number of external hosts emulated by wan1 can be changed by setting the third argument like so: --topo=sectest,5,10,1000. Set to 100 by default, it can be set to any number restricted by the kernel support for secondary addresses on a single interface. Although I’ve tested with 100,000 emulated hosts, anything over 10,000 can take a very long time to initialize. This does not seem to be a limitation with the bulkip subcommand (explained in the subsection below) but rather with the kernel itself.

Bulk IP Assignment

Behind the scenes, the Security Test Mininet Topology uses a CLI tool included with the Security Test suite. For assigning a block of IP addresses to an interface, a JSON file is created including the blocks that should be assigned. The file generated by the Security Test Topology looks like this:

That file is then passed to the sectest bulkip subcommand with the file passed in as an argument. Inside the wan1 host in the Security Test Topology, the command looks like this (note that /sectest is bound automatically for convenience):

This command then creates a couple new files in the same directory as the bulkip.json file: ip-batch and ips.csv. The ip-batch file is passed to the native ip command in Linux in the wan1 host to set up all of the secondary addresses. The ips.csv file contains a list of all created IP addresses so other tools can easily have access to the IP list. It takes the form of:

This tool is not limited to use in Mininet. It is designed to be used on physical or virtual hosts to help test hardware switches as well.

Testing Connectivity

The other sectest subcommand implemented for this article is pingbulk, which we used while testing the installation near the beginning of the article. Its full form is:

The first argument is the location of the bulkip.json file that should be used. The second argument determines the direction of the ping. If this is run on the host with the bulk IPs, target may be specified to have the current host ping the target from every IP address in the bulk IP ranges. If target is not specified, the tool attempts to ping all IP addresses in the bulk IP ranges from the current host.

Looking at the commands we ran in Mininet earlier, this command runs on host h1r1 and pings all the addresses in the configuration file specified:

The start of the command in Mininet determines which host to run it on, so the sectest pingbulk command is run on the h1r1 host. Similarly, the following will run on wan1 and ping h1r1 from every address in the configuration file specified:

Currently, the pingbulk command calls ping or ping6 to perform the ping with a few options that cause the ping to fail quickly if the host doesn’t respond. This may be changed at some later point to parallelize the pinging process.

Only the Beginning

Security Switch and its testing environment, Security Test, will be expanded as new articles are published covering new topics; however, a great effort will be made to make sure publically described APIs and CLI commands will retain the same usage throughout the track. It is our hope that after a few articles, you will feel comfortable experimenting and modifying Security Switch for your own projects and research. We plan on covering more of the internals to Security Switch going forward, covering topics like staged and independent processes for network control and why it matters for an R&D platform.

If you’ve enjoyed this article, please consider sharing with your colleagues and leave questions and feedback in the comments below. We would be very interested to hear about what you would like to see discussed in future articles and features you would like to see in a security-aware controller.

Happy Coding!

Share This