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 IPSet
s 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 rangesdst
- a list of destination IP rangesapp
- the name of the permitted applicationname
- 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: 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 asnot 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()
.
-