Directory structure

Invariant works by evaluating a directory containing your network configuration files, your Invariant rules, and other metadata.

There are three ways to cause Invariant to evaluate your directory:

Create a git repository containing your directory following this structure. Connect Invariant to the git repository and Invariant will evaluate every commit to the default branch.
Create a local directory. Run the Invariant CLI command “invariant run” from the local directory.
Create a zip file containing your directory. Upload the zip file to the Invariant UI.

The directory must follow the structure defined here.

A complete example directory is available here: https://github.com/InvariantTech/demo/tree/main/enterprise.

Sub-directories

These are the sub-directories Invariant understands. See the reference listing below for details on the kind of data expected for each sub-directory.

Invariant uses Batfish to parse, normalize, and model your network based on its config files. You can enhance the Batfish model directly by providing supplemental configuration files in the “hosts”, “iptables”, and/or “batfish” sub-directories. Sub-directories that will be passed to Batfish are labeled as such in the table and reference section below.

When writing Invariant policy rules you may refer to named IP networks and named services (e.g. service SSH should not be permitted for traffic from network GUEST to network DATACENTER). These definitions would be placed in the “def” directory in the Aerleon definition format. Note that Invariant has built-in default definitions for many well-known services (e.g. HTTPS, SSH) based on the IANA service name and port number registry (RFC6335). It also includes built-in default definitions for some common network names (e.g. RFC1918, LOOPBACK). Your definitions may override the built-in default definitions.

‍

Path	Required?	Description
configs/	Yes (one or both)	Place network device configuration files here.
aws_configs/	Yes (one or both)	Place AWS network device configuration data here.
def/		Define named IP networks and named services (port + protocol).
invariant/policies/		Define Invariant rules here.
invariant/def/		Define Invariant locations.
hosts/		Add hosts to the network model.
iptables/		If using hosts, place iptables host firewall rules here.
batfish/layer1_topology.json		Layer 1 cabling information.
batfish/isp_config.json		Add ISPs, transit ISPs and/or internet to the network model.
batfish/runtime_data.json		Add “line down” scenarios to the network model.
batfish/external_bgp_announcements.json		Inject custom BGP announcements into the network model.

Sub-directory reference

This section describes each sub-directory and its expected data in detail.

configs/

Parsed by: Batfish.

Place network device configuration files here. Typically these would be device configuration files collected using RANCiD or specific SHOW commands. Or they could be device configuration files that you maintain in a version control repository representing approved configurations you plan to deploy or have deployed.

Many network device vendor file formats are supported. For a complete list see Supported Platforms.

It can be helpful to include a RANCiD vendor tag at the top of each network configuration file in order to clarify the file format. This is particularly helpful for preventing small Arista configs from being parsed as Cisco configs. An example of a RANCiD vendor tag appears here: https://github.com/InvariantTech/demo/blob/main/arista-campus-fabric/configs/LEAF1A.cfg.

Security note: network device configuration files often contain passwords or other credentials. Netconan is an open-source tool which scrubs passwords and credentials from network device configuration files. While Invariant will immediately discard any passwords and credentials, you are encouraged to run this tool on all files Invariant will process.

Batfish provides more detailed documentation on acceptable configs per vendor as well as guidance on how to generate those configs. See https://batfish.readthedocs.io/en/latest/formats.html. A complete example is available here: https://github.com/InvariantTech/demo/tree/main/enterprise.

aws_configs/

Parsed by: Batfish.

Place AWS network configuration files here. Batfish directly understands and models AWS network devices. Typically these would be the output of various “describe_” AWS API calls.

Batfish provides more detailed documentation on this topic. See https://batfish.readthedocs.io/en/latest/formats.html#aws. A complete example including aws_configs is available here: https://github.com/InvariantTech/demo/tree/main/enterprise.

def/

Parsed by: Aerleon.

When writing Invariant policy rules you may refer to named IP networks and named services (e.g. service SSH should not be permitted for traffic from network GUEST to network DATACENTER). These definitions would be placed in the “def” directory in the Aerleon definition format. Note that Invariant has built-in default definitions for a long list of well-known services (e.g. HTTPS, SSH) based on the IANA service name and port number registry (RFC6335). It also includes built-in default definitions for some common network names (e.g. RFC1918, LOOPBACK). Your definitions may override the built-in default definitions.

Example definition files can be found here: https://github.com/InvariantTech/demo/blob/main/enterprise/def/networks.yaml and here: https://github.com/aerleon/aerleon/blob/main/def/naming.yaml.

invariant/

Parsed by: Invariant.

Invariant policy rules and location definitions should be placed here. A detailed description of each sub-directory is provided below.

invariant/policies/

Invariant will load and evaluate rules from YAML rules files found in your project directory. Rules can define traffic that should always be deliverable (critical flow rules) or never be deliverable (access policy rules) in your network.

Detailed documentation for Invariant policies is available here: https://www.invariant.tech/documentation/rules.

invariant/def/

Invariant policy rules may refer to named groups of network interfaces (called “locations”). Groups can be selected by device / interface name or name pattern, by IP network, by zone, by VRF, or some combination thereof. Groups can also be built up from other named groups of interfaces.

Place definitions for named groups of network interfaces in this sub-directory.

Detailed documentation for Invariant location definitions is available here: https://www.invariant.tech/documentation/rules#locations.

hosts/

Parsed by: Batfish.

Batfish can insert hosts into the network model. Those hosts can have iptables host firewalls applied.

Place one JSON file per host in this directory. The JSON file structure and more detailed documentation can be found in the Batfish documentation: https://batfish.readthedocs.io/en/latest/formats.html#modeling-hosts.

iptables/

Parsed by: Batfish.

Used in conjunction with the “hosts” sub-directory.

Batfish can insert hosts into the network model. Those hosts can have iptables host firewalls applied.

Place iptables files in this sub-directory. Your iptables files should be referenced by your host definitions.

Batfish provides additional documentation on this topic: https://batfish.readthedocs.io/en/latest/formats.html#modeling-hosts.

batfish/

Parsed by: Batfish.

Invariant uses Batfish to parse, normalize, and model your network based on its config files. You can enhance the Batfish model directly by providing supplemental configuration files.

These model enhancements are documented by Batfish here: https://batfish.readthedocs.io/en/latest/formats.html#supplemental-data-formats. A brief summary of each file is provided below.

batfish/layer1_topology.json

Layer 1 cabling information. In many cases Batfish will correctly infer your network topology by looking at network interfaces with adjacent IP addresses. The layer 1 topology file provides an opportunity to override the inferred topology.

batfish/isp_config.json

Add ISPs, transit ISPs and/or internet to the network model. Invariant can be used to model scenarios involving internet transit and ISP connections. In these scenarios you would not have network configuration files for ISP devices, but you can summarize the function of those ISPs using this Batfish file.

Real networks sometimes expect a default route for 0.0.0.0/0 to be provided by an external network (ISP). This isp_config.json file can be used to supply such a route to your network. You may also be able to accomplish this using external_bgp_announcements.json as described below.

This file can create a special node named “internet” in the network model. You can target that network node in your Invariant rules.

batfish/runtime_data.json

Add “line down” scenarios to the network model. Please note that while Batfish also supports link bandwidth modeling through this file, Invariant does not offer any interesting features that use it.

batfish/external_bgp_announcements.json

Inject custom BGP announcements into the network model.

If your network relies on a BGP injector, you may be able to model the injector directly depending on the injector platform. However, if the injector is not directly supported, it may be possible to represent those announcements using this file.

‍