Output Overview
Invariant creates a set of reports for each network snapshot it analyzes. These files can be accessed using the invariant show <file>
command. By default, the show
command displays the file as an interactive table, but it can also output the file as TSV or JSON.
# Collect the violations summary table as JSON and TSV
invariant show --json policy_violations > policy_violations.json
invariant show --tsv policy_violations > policy_violations.tsv
# View the olations summary table
invariant show policy_violations
# +----+---------+-------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------>
# | | index | ok | skipped | policy >
# |----+---------+-------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------>
# | 0 | 4 | False | False | {'comment': 'Access that the staff vlan has.', 'egress-network': {'list': None, 'object': {'source-address': array(['VLAN30'], dtype=object), 'source>
# +----+---------+-------+-----------+------------------------------------------------------------------------------------------------------------------------------------------------------>
Accessing Prior Snapshots
By default, the show
command accesses the most recent snapshot evaluated by the current CLI session. You can access prior snapshot files using the --snapshot
flag.
# Check if the most recent live scan has any violations
export LAST_SCAN_SNAPSHOT=$(invariant snapshots --tsv --network live_scans | head -2 | tail -1)
invariant show --json --snapshot $LAST_SCAN_SNAPSHOT | jq '.summary.policy_violations'
# 0
invariant show --json --snapshot $LAST_SCAN_SNAPSHOT | jq '.summary.critical_flows_violations'
# 1
The Output Files section below describes how to interpret the number of rows in each report.
Automation
The invariant run --condensed
switch produces very terse output which may be helpful in basic automation and scripting scenarios.
invariant run --condensed
# snapshot: cf2bb04f-554f-4a84-a3e0-bf12a13c0e4e
# outcome: Rule violations found
The condensed output will always write two lines to stdout: the first containing the snapshot ID and the second containing the outcome.
Another approach would be to use invariant run --json
. This output mode includes the snapshot ID and the row count for each report.
Both of these scenarios allow you to programmatically determine if a violation was found and get the snapshot ID for further examination.
invariant run --json > invariant_run.json
# Test whether there were any violations in the last run
jq .summary.policy_violations invariant_run.json
# 1
jq .summary.critical_flows_violations invariant_run.json
# 0
# Fetch the violations summary table using the snapshot ID
invariant show --json --snapshot $(jq -r .report.uuid invariant_run.json) policy_violations > policy_violations.json
Automation scenarios will use an API token. The API token can be provided to the invariant program through the environment variable INVARIANT_API_TOKEN
. The organization name is also required - this can be found in quickly by logging in and examining the URL: notice 5678
in https://app.prod.invariant.tech/5678/p/main/network/
.
export INVARIANT_API_TOKEN=<API token>
export INVARIANT_ORGANIZATION_NAME=1234
invariant run
When using an API token, the invariant show
command will require the --snapshot
option. See the examples above for ways to reliably get the snapshot ID from invariant run
.
Output Files
Access Policy Files
This section appears if one or more access policy rules were included in the snapshot.
These reports describe the pass/fail status of each rule, example virtual traceroutes, and relevant traffic flows.
File | Description | Rows Correspond To |
---|---|---|
critical_flows_ok | Passing critical flow rules. | Number of passing critical flow rules. |
policy_ok | Passing access policy rules. | Number of passing access policy rules. |
critical_flows_violations | Failing critical flow rules. | Number of failing critical flow rules (enforced rules only). |
critical_flows_violations_unenforced | Failing critical flow rules. | Number of failing critical flow rules (unenforced rules only). |
policy_violations | Failing access policy rules. | Number of failing access policy rules (enforced rules only). |
policy_violations_unenforced | Failing access policy rules. | Number of failing access policy rules (unenforced rules only). |
critical_flows_skipped | Invalid critical flow rules. | Number of invalid critical flow rules. |
critical_flows_logs | Processing summary for critical flow rules. | Number of critical flow rules. |
policy_skipped | Invalid access policy rules. | Number of invalid access policy rules. |
policy_logs | Processing summary for access policy rules. | Number of access policy rules. |
critical_flows_details | Traces, check logs for passing and failing rules. | Number of traces or checks - possibly more than one per rule. |
policy_details | Traces, check logs for passing and failing rules. | Number of traces or checks - possibly more than one per rule. |
Network Information Files
Complete information about the network model.
File | Description | Rows Correspond To |
---|---|---|
nodes | Network nodes (devices, hosts, cloud resources). | Number of nodes loaded in the model. |
interfaces | Network interfaces. | Number of interfaces loaded in the model. |
named_structures | Vendor-independent structures (ACLs, VXLANs, etc). | Number of abstract structures loaded in the model. |
vlan_properties | VLANs and VXLANs. | Number of VLANs and VXLANs loaded in the model. |
hsrp_properties | HSRP groups. | Number of HSRP groups loaded in the model. |
mlag_properties | MLAG domains. | Number of MLAG domains loaded in the model. |
ip_owners | IP assignments. | Number of interfaces with IP addresses assigned. |
vrrp_properties | VRRP groups. | Number of VRRP groups loaded in the model. |
routes | Routing tables. | Number of routing table entries across all devices in the model. |
Topology Files
File | Description | Rows Correspond To |
---|---|---|
layer_3_edges | Layer 3 edges. | Number of layer 3 edges in the model. |
layer_1_edges | User-provided layer 1 edges. | Number of user-provided layer 1 edges in the model. |
edges | Layer 3 edges (duplicate). | Number of layer 3 edges in the model. |
BGP Files
File | Description | Rows Correspond To |
---|---|---|
bgp_process_config | Configuration settings for BGP processes. | Number of BGP processes loaded in the model. |
bgp_peer_config | Configuration settings for configured BGP peerings. | Number of configured BGP peerings loaded in the model. |
bgp_session_compatibility | Issues found in configured BGP peerings. | Number of configured BGP peerings with issues found. |
bgp_session_status | Status information for configured BGP peerings. | Number of configured BGP peerings loaded in the model. |
bgp_edges | BGP edges. | Number of BGP edges loaded in the model. |
bgp_ribs | BGP RIBs. | Number of BGP RIB entries across all devices in the model. |
OSPF Files
File | Description | Rows Correspond To |
---|---|---|
ospf_process_config | OSPF routing processes. | Number of running OSPF processes in the model. |
ospf_interface_config | Interface-level OSPF configuration details. | Number of interfaces running OSPF. |
ospf_area_config | OSPF areas. | Number of OSPF areas in the model. |
ospf_session_compatibility | OSPF sessions. | Number of OSPF sessions in the model. |
Inconsistent Traffic Files
File | Description | Rows Correspond To |
---|---|---|
subnet_multipath | Examples of traffic flows that are treated differently (i.e., dropped versus forwarded) by different paths in the network. | Number of example flows found. |
loopback_multipath | Examples of traffic flows between loopbacks that are treated differently (i.e., dropped versus forwarded) in the presence of multipath routing. | Number of example flows found. |
Model Creation Files
Files in this section illustrate how the digital twin model was created from the provided input.
File | Description | Rows Correspond To |
---|---|---|
defined_structures | Structure definitions as they appear in config files (ACLs, VXLANs, etc). | Number of structure definitions found. |
referenced_structures | Structure references as they appear in config files (ACLs, VXLANs, etc). | Number of references to defined structures. |
unused_structures | Structure definitions not referenced or used. | Number of unused structure definitions. |
undefined_references | Structure references with no matching definition. | Number of undefined references. |
unconnected_nodes | Nodes with no connection to any other node in the model. | Number of unconnected nodes. |
file_parse_status | Parsing status of snapshot files. | Number of files found in the snapshot. |
ignored_lines | Lines parsed but ignored by the model. | Number of ignored lines. |
parse_warnings | Warnings that occurred when parsing snapshot files. | Number of warnings produced. |
Errors Files
File | Description | Rows Correspond To |
---|---|---|
errors | Errors encountered by Invariant. | Number of errors produced. |
Probes Files
File | Description | Rows Correspond To |
---|---|---|
probes | Quick virtual traceroutes fired from all nodes. | Number of traceroute targets. |