Implementation Notes

IP Objects

This tool uses IPy to handle IP addresses, ranges, and sets. However, it extends that functionality to include some additional methods for IPSets as well as an IPPairs class to efficiently represent sets of IP pairs.

All of these classes can be imported directly from fwunit.

Rules

The output of the processing step is a JSON-formatted object. The rules key gives a list of rule objects, each of which has keys

  • src - a list of source IP ranges
  • dst - a list of destination IP ranges
  • app - the name of the permitted application
  • name - the name of the rule

The rules are normalized as follows (and this is what consumes most of the time in processing):

  • For a given source and destination IP and application, exactly 0 or 1 rules match; stated differently, there’s no need to consider rules in order.
  • If traffic matches a rule, it is permitted. If no rule matches, it is denied.
  • Policies allowing any application are represented by explicit rules for each known application, with the addition of rules with application ‘@@other’ to represent the unknown applications.

Loading Source Objects

Rule sets are embedded in Source objects, which provide a set of useful methods for analysis. In a testing environment, rule sets are loaded via TestContext; this section describes access to rules within fwunit itself.

To get a source object, you will first need a config, which can be retrieved from load_config():

fwunit.analysis.config.load_config(filename="fwunit.yaml")
Parameters:filename – the configuration filename to load
Returns:a config object

Load a configuration file. As a side-effect, this function chdir’s to the configuration directory.

The function operates on the assumption that a single process will only ever reference one configuration, and thus caches the configuration after the first call. Subsequent calls with the same filename will return the same object. Subsequent calls with a different filename will raise an exception.

With the config object in hand, call load_source():

fwunit.analysis.sources.load_source(config, source)
Parameters:
  • config – a config object
  • source – the name of the source to load
Returns:

a source object

Return type:

Source

Load the ruleset for the given source. The source parameter can be a source name from the configuration, or a filename.

Rulesets are cached globally to the process.

Using Source Objects

class fwunit.analysis.sources.Source

The data from a particular source in fwunit.yaml, along with some analysis methods.

rulesForApp(app):
Parameters:app – application name
Returns:list of rules

Get the rules for the given app, or if no such app is known, for @@other.

rulesDeny(src, dst, apps)
Parameters:
  • src – source IPs
  • dst – destination IPs
  • apps (list or string) – application names

Returns True if the rules deny all traffic from src to dst via all given apps; otherwise False.

rulesPermit(src, dst, apps)
Parameters:
  • src – source IPs
  • dst – destination IPs
  • apps (list or string) – application names

Returns True if the rules allow all traffic from src to dst via all given apps; otherwise False.

Note that rulesdeny(..) is not the same as not rulesPermit(..): if some – but not all – traffic is permitted from src to dst, then both methods will return False.

allApps(src, dst, debug=False)
Parameters:
  • src – source IPs
  • dst – destination IPs
  • debug – if True, log the full list of matching flows

See allApps().

sourcesFor(dst, app, ignore_sources=None)
Parameters:
  • dst – destination IPs
  • app – application
  • ignore_sources – source IPs to ignore

See sourcesFor().