Skip to main content

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.

FileDescriptionRows Correspond To
critical_flows_okPassing critical flow rules.Number of passing critical flow rules.
policy_okPassing access policy rules.Number of passing access policy rules.
critical_flows_violationsFailing critical flow rules.Number of failing critical flow rules (enforced rules only).
critical_flows_violations_unenforcedFailing critical flow rules.Number of failing critical flow rules (unenforced rules only).
policy_violationsFailing access policy rules.Number of failing access policy rules (enforced rules only).
policy_violations_unenforcedFailing access policy rules.Number of failing access policy rules (unenforced rules only).
critical_flows_skippedInvalid critical flow rules.Number of invalid critical flow rules.
critical_flows_logsProcessing summary for critical flow rules.Number of critical flow rules.
policy_skippedInvalid access policy rules.Number of invalid access policy rules.
policy_logsProcessing summary for access policy rules.Number of access policy rules.
critical_flows_detailsTraces, check logs for passing and failing rules.Number of traces or checks - possibly more than one per rule.
policy_detailsTraces, 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.

FileDescriptionRows Correspond To
nodesNetwork nodes (devices, hosts, cloud resources).Number of nodes loaded in the model.
interfacesNetwork interfaces.Number of interfaces loaded in the model.
named_structuresVendor-independent structures (ACLs, VXLANs, etc).Number of abstract structures loaded in the model.
vlan_propertiesVLANs and VXLANs.Number of VLANs and VXLANs loaded in the model.
hsrp_propertiesHSRP groups.Number of HSRP groups loaded in the model.
mlag_propertiesMLAG domains.Number of MLAG domains loaded in the model.
ip_ownersIP assignments.Number of interfaces with IP addresses assigned.
vrrp_propertiesVRRP groups.Number of VRRP groups loaded in the model.
routesRouting tables.Number of routing table entries across all devices in the model.

Topology Files

FileDescriptionRows Correspond To
layer_3_edgesLayer 3 edges.Number of layer 3 edges in the model.
layer_1_edgesUser-provided layer 1 edges.Number of user-provided layer 1 edges in the model.
edgesLayer 3 edges (duplicate).Number of layer 3 edges in the model.

BGP Files

FileDescriptionRows Correspond To
bgp_process_configConfiguration settings for BGP processes.Number of BGP processes loaded in the model.
bgp_peer_configConfiguration settings for configured BGP peerings.Number of configured BGP peerings loaded in the model.
bgp_session_compatibilityIssues found in configured BGP peerings.Number of configured BGP peerings with issues found.
bgp_session_statusStatus information for configured BGP peerings.Number of configured BGP peerings loaded in the model.
bgp_edgesBGP edges.Number of BGP edges loaded in the model.
bgp_ribsBGP RIBs.Number of BGP RIB entries across all devices in the model.

OSPF Files

FileDescriptionRows Correspond To
ospf_process_configOSPF routing processes.Number of running OSPF processes in the model.
ospf_interface_configInterface-level OSPF configuration details.Number of interfaces running OSPF.
ospf_area_configOSPF areas.Number of OSPF areas in the model.
ospf_session_compatibilityOSPF sessions.Number of OSPF sessions in the model.

Inconsistent Traffic Files

FileDescriptionRows Correspond To
subnet_multipathExamples of traffic flows that are treated differently (i.e., dropped versus forwarded) by different paths in the network.Number of example flows found.
loopback_multipathExamples 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.

FileDescriptionRows Correspond To
defined_structuresStructure definitions as they appear in config files (ACLs, VXLANs, etc).Number of structure definitions found.
referenced_structuresStructure references as they appear in config files (ACLs, VXLANs, etc).Number of references to defined structures.
unused_structuresStructure definitions not referenced or used.Number of unused structure definitions.
undefined_referencesStructure references with no matching definition.Number of undefined references.
unconnected_nodesNodes with no connection to any other node in the model.Number of unconnected nodes.
file_parse_statusParsing status of snapshot files.Number of files found in the snapshot.
ignored_linesLines parsed but ignored by the model.Number of ignored lines.
parse_warningsWarnings that occurred when parsing snapshot files.Number of warnings produced.

Errors Files

FileDescriptionRows Correspond To
errorsErrors encountered by Invariant.Number of errors produced.

Probes Files

FileDescriptionRows Correspond To
probesQuick virtual traceroutes fired from all nodes.Number of traceroute targets.