Datamodel classes

Here we describe classes used in answers and their attributes, which may help you filter your answers as desired.

Base types

class pybatfish.datamodel.primitives.Assertion(type: pybatfish.datamodel.primitives.AssertionType, expect)[source]

A Batfish assertion.

Assertions are combined with a Question to create a Batfish check. An assertion can be on the number of results return by the question, or on the value of the answer itself.

  • type – an AssertionType
  • expect – the expected value (a.k.a as right-hand side) for the assertion to return True.
class pybatfish.datamodel.primitives.AssertionType[source]

Assertion type.

COUNT_EQUALS = 'countequals'

Number of results equals

COUNT_LESSTHAN = 'countlessthan'

Number of results is less than

COUNT_MORETHAN = 'countmorethan'

Number of results is more than

EQUALS = 'equals'

Result equals to value (list of rows). Experimental

class pybatfish.datamodel.primitives.VariableType[source]

Auto completion type.

ADDRESS_GROUP_NAME = 'addressGroupName'

address group name

ANSWER_ELEMENT = 'answerElement'

answer elements

APPLICATION_SPEC = 'applicationSpec'

application specifier

BGP_PEER_PROPERTY_SPEC = 'bgpPeerPropertySpec'

bgp peer properties

BGP_PROCESS_PROPERTY_SPEC = 'bgpProcessPropertySpec'

bgp process properties

BGP_ROUTES = 'bgpRoutes'

bgp routes

BGP_SESSION_COMPAT_STATUS_SPEC = 'bgpSessionCompatStatusSpec'

bgp session compatibility statuses

BGP_SESSION_STATUS_SPEC = 'bgpSessionStatusSpec'

bgp session statuses

BGP_SESSION_TYPE_SPEC = 'bgpSessionTypeSpec'

bgp session types

BOOLEAN = 'boolean'

boolean values

COMPARATOR = 'comparator'

comparators (<, <=, ==, >=, >, !=)

DISPOSITION_SPEC = 'dispositionSpec'


DOUBLE = 'double'

double values

FILTER = 'filter'

names or regex of filters

FILTER_NAME = 'filter'

name of filters

FILTER_SPEC = 'filterSpec'

filter specifier

FLOAT = 'float'

float values

FLOW_STATE = 'flowState'

flow states

HEADER_CONSTRAINT = 'headerConstraint'

packet header constraints

INTEGER = 'integer'

integer values

INTEGER_SPACE = 'integerSpace'

integer spaces

INTERFACE = 'interface'

names of interfaces

INTERFACES_SPEC = 'interfacesSpec'

interfaces specifier

INTERFACE_GROUP_NAME = 'interfaceGroupName'

interface group name

INTERFACE_NAME = 'interfaceName'

name of interfaces

INTERFACE_PROPERTY_SPEC = 'interfacePropertySpec'

interface properties

IP = 'ip'


IPSEC_SESSION_STATUS_SPEC = 'ipsecSessionStatusSpec'

ipsec session statuses

IP_PROTOCOL = 'ipProtocol'

ip protocols

IP_PROTOCOL_SPEC = 'ipProtocolSpec'

ip protocol specifier

IP_SPACE_SPEC = 'ipSpaceSpec'

ip space specifier

IP_WILDCARD = 'ipWildcard'

ip protocols

JAVA_REGEX = 'javaRegex'

java regex

JSON_PATH = 'jsonPath'

json path

JSON_PATH_REGEX = 'jsonPathRegex'

json path regex

LOCATION_SPEC = 'locationSpec'

location specifier

LONG = 'long'

long values

MLAG_ID = 'mlagId'

mlag id

MLAG_ID_SPEC = 'mlagIdSpec'

mlag id specifier

NAMED_STRUCTURE_SPEC = 'namedStructureSpec'

named structure type

NODE_NAME = 'nodeName'

name of nodes

NODE_PROPERTY_SPEC = 'nodePropertySpec'

node properties

NODE_ROLE_DIMENSION_NAME = 'nodeRoleDimensionName'

names of node role dimension

NODE_ROLE_NAME = 'nodeRoleName'

node role name

NODE_SPEC = 'nodeSpec'

node specifier

OSPF_INTERFACE_PROPERTY_SPEC = 'ospfInterfacePropertySpec'

ospf interface properties

OSPF_PROCESS_PROPERTY_SPEC = 'ospfProcessPropertySpec'

ospf process properties

PATH_CONSTRAINT = 'pathConstraint'

path constraints

PREFIX = 'prefix'


PREFIX_RANGE = 'prefixRange'

prefix ranges

PROTOCOL = 'protocol'

application-level protocols

QUESTION = 'question'


REFERENCE_BOOK_NAME = 'referenceBookName'

reference book name

ROUTING_PROTOCOL_SPEC = 'routingProtocolSpec'

routing protocols

STRING = 'string'

string values

STRUCTURE_NAME = 'structureName'

names of structures

SUBRANGE = 'subrange'


VRF = 'vrf'

names of vrfs

VXLAN_VNI_PROPERTY_SPEC = 'vxlanVniPropertySpec'

vxlan vni properties

ZONE = 'zone'

names of zones

class pybatfish.datamodel.primitives.AutoCompleteSuggestion(description: str, insertion_index: int, is_partial: bool, rank: int, text: str)[source]

Represent one auto complete suggestion.

Auto complete suggestions are returned by Batfish for auto complete queries.

  • description – A description of the suggestion (optional)
  • insertion_index – Index in original input string where suggested text should be inserted
  • is_partial – Whether this suggestion represents partial or full text
  • rank – Batfish may assign a rank to the suggestion
  • text – The actual suggested text
class pybatfish.datamodel.primitives.Edge(node1: str, node1interface, node2: str, node2interface)[source]

A network edge (i.e., a link between two node/interface pairs).

  • node1 – First node name
  • node1interface – First node’s interface name
  • node2 – Second node name
  • node2interface – Second node’s interface name
class pybatfish.datamodel.primitives.FileLines(filename: str, lines: List[int] = NOTHING)[source]

A class that represents a set of lines in a file.

  • filename – The filename referenced
  • lines – A list of lines referenced
class pybatfish.datamodel.primitives.Interface(hostname: str, interface: str)[source]

A network interface — a combination of node and interface names.

  • hostname – Node hostname to which this interface belongs
  • interface – Interface name
class pybatfish.datamodel.primitives.Issue(severity, explanation: str = NOTHING, type: pybatfish.datamodel.primitives.IssueType = NOTHING)[source]

Information about a bug/issue that Batfish has discovered.

  • severity – The integer severity of the issue
  • explanation – An explanation for the issue
  • type – An IssueType containing more information about the issue
class pybatfish.datamodel.primitives.IssueType(major: str, minor: str)[source]

Details about a particular Issue type.

  • major – Primary type of the issue
  • minor – Additional subcategory of the issue
class pybatfish.datamodel.primitives.ListWrapper[source]

Helper list class that implements _repr_html_().

ACL traces

class pybatfish.datamodel.acl.AclTrace(events: List[pybatfish.datamodel.acl.AclTraceEvent] = NOTHING)[source]

The trace of a packet’s life through an ACL.

Variables:events – A list of AclTraceEvent
class pybatfish.datamodel.acl.AclTraceEvent(class_name: Optional[str] = None, description: Optional[str] = None, lineDescription: Optional[str] = None)[source]

One event corresponding to a packet’s life through an ACL.

  • class_name – The type of the event that occurred while tracing.
  • description – The description of the event
  • lineDescription – ACL line that caused the event (if applicable)

Flows and packets

class pybatfish.datamodel.flow.EnterInputIfaceStepDetail(inputInterface: str, inputVrf: Optional[str])[source]

Details of a step representing the entering of a flow into a Hop.

  • inputInterface – Interface of the Hop on which this flow enters
  • inputVrf – VRF associated with the input interface
class pybatfish.datamodel.flow.ExitOutputIfaceStepDetail(outputInterface: str, transformedFlow: Optional[str])[source]

Details of a step representing the exiting of a flow out of a Hop.

  • outputInterface – Interface of the Hop from which the flow exits
  • transformedFlow – Transformed Flow if a source NAT was applied on the Flow
class pybatfish.datamodel.flow.FilterStepDetail(filter: str, filterType: str)[source]

Details of a step representing a filter step.

  • filter – filter name
  • type – filter type
class pybatfish.datamodel.flow.Flow(dscp, dstIp, dstPort, ecn, fragmentOffset, icmpCode, icmpVar, ingressInterface: Optional[str], ingressNode: Optional[str], ingressVrf: Optional[str], ipProtocol: str, packetLength: str, srcIp, srcPort, state, tag, tcpFlagsAck, tcpFlagsCwr, tcpFlagsEce, tcpFlagsFin, tcpFlagsPsh, tcpFlagsRst, tcpFlagsSyn, tcpFlagsUrg)[source]

A concrete IPv4 flow.

Noteworthy attributes for flow inspection/filtering:

  • srcIP – Source IP of the flow
  • dstIP – Destination IP of the flow
  • srcPort – Source port of the flow
  • dstPort – Destination port of the flow
  • ipProtocol – the IP protocol of the flow (as integer, e.g., 1=ICMP, 6=TCP, 17=UDP)
  • ingressNode – the node where the flow started (or entered the network)
  • ingressInterface – the interface name where the flow started (or entered the network)
  • ingressVrf – the VRF name where the flow started (or entered the network)
class pybatfish.datamodel.flow.HeaderConstraints(srcIps: Optional[str] = None, dstIps: Optional[str] = None, srcPorts=None, dstPorts=None, ipProtocols=None, applications=None, icmpCodes=None, icmpTypes=None, firewallClassifications=None, ecns=None, dscps=None, packetLengths=None, fragmentOffsets=None, tcpFlags=None)[source]

Constraints on an IPv4 packet header space.

Specify constraints on packet headers by specifying lists of allowed values in each field of IP packet.

  • srcIps (str) – Source location/IP
  • dstIps (str) – Destination location/IP
  • srcPorts – Source ports as list of ranges (e.g., "22,53-99")
  • dstPorts – Destination ports as list of ranges, (e.g., "22,53-99")
  • applications – Shorthands for application protocols (e.g., SSH, DNS, SNMP)
  • ipProtocols – List of well-known IP protocols (e.g., TCP, UDP, ICMP)
  • icmpCodes – List of integer ICMP codes
  • icmpTypes – List of integer ICMP types
  • firewallClassifications – List of flow states as classified by a stateful firewall (e.g., “new”, “established”)
  • dscps – List of allowed DSCP value ranges
  • ecns – List of allowed ECN values ranges
  • packetLengths – List of allowed packet length value ranges
  • fragmentOffsets – List of allowed fragmentOffset value ranges
  • tcpFlags – List of MatchTcpFlags – conditions on which TCP flags to match

Lists of values in each fields are subject to a logical “OR”:

>>> HeaderConstraints(ipProtocols=["TCP", "UDP"])
HeaderConstraints(srcIps=None, dstIps=None, srcPorts=None, dstPorts=None, ipProtocols=['TCP', 'UDP'], applications=None,
icmpCodes=None, icmpTypes=None, firewallClassifications=None, ecns=None, dscps=None, packetLengths=None, fragmentOffsets=None, tcpFlags=None)

means allow TCP OR UDP.

Different fields are ANDed together:

>>> HeaderConstraints(srcIps="", dstIps="", applications=["SSH"])
HeaderConstraints(srcIps='', dstIps='', srcPorts=None, dstPorts=None, ipProtocols=None, applications=['SSH'],
icmpCodes=None, icmpTypes=None, firewallClassifications=None, ecns=None, dscps=None, packetLengths=None, fragmentOffsets=None, tcpFlags=None)

means an SSH connection originating at and going to

Any None values will be treated as unconstrained.

class pybatfish.datamodel.flow.Hop(node: str, steps: List[pybatfish.datamodel.flow.Step])[source]

A single hop in a flow trace.

  • node – Name of node considered as the Hop
  • steps – List of steps taken at this Hop
class pybatfish.datamodel.flow.InboundStepDetail[source]

Details of a step representing the receiving (acceptance) of a flow into a Hop.

class pybatfish.datamodel.flow.MatchSessionStepDetail[source]

Details of a step for when a flow matches a firewall session.

class pybatfish.datamodel.flow.MatchTcpFlags(tcpFlags: pybatfish.datamodel.flow.TcpFlags, useAck: bool = True, useCwr: bool = True, useEce: bool = True, useFin: bool = True, usePsh: bool = True, useRst: bool = True, useSyn: bool = True, useUrg: bool = True)[source]

Match given TcpFlags.

For each bit in the TCP flags, a useX must be set to true, otherwise the bit is treated as “don’t care”.

  • tcpFlags – tcp flags to match
  • useAck
  • useCwr
  • useEce
  • useFin
  • usePsh
  • useRst
  • useSyn
  • useUrg
static match_ack()[source]

Return match conditions checking that ACK bit is set.

Other bits may take any value.

static match_established()[source]

Return a list of match conditions matching an established flow (ACK or RST bit set).

Other bits may take any value.

static match_rst()[source]

Return match conditions checking that RST bit is set.

Other bits may take any value.

static match_syn()[source]

Return match conditions checking that the SYN bit is set.

Other bits may take any value.

static match_synack()[source]

Return match conditions checking that both the SYN and ACK bits are set.

Other bits may take any value.

class pybatfish.datamodel.flow.OriginateStepDetail(originatingVrf: str)[source]

Details of a step representing the originating of a flow in a Hop.

Variables:originatingVrf – VRF from which the Flow originates
class pybatfish.datamodel.flow.RoutingStepDetail(routes: List[Any])[source]

Details of a step representing the routing from input interface to output interface.

Variables:routes – List of routes which were considered to select the output interface
class pybatfish.datamodel.flow.SetupSessionStepDetail[source]

Details of a step for when a firewall session is created.

class pybatfish.datamodel.flow.PathConstraints(startLocation: Optional[str] = None, endLocation: Optional[str] = None, transitLocations: Optional[str] = None, forbiddenLocations: Optional[str] = None)[source]

Constraints on the path of a flow.

  • startLocation – Location description of where a flow is allowed to start
  • endLocation – Location description of where a flow is allowed to terminate
  • transitLocation – Location description of where a flow must transit
  • startLocation – Location description of where a flow is not allowed to transit
class pybatfish.datamodel.flow.TcpFlags(ack: bool = False, cwr: bool = False, ece: bool = False, fin: bool = False, psh: bool = False, rst: bool = False, syn: bool = False, urg: bool = False)[source]

Represents a set of TCP flags in a packet.

  • ack
  • cwr
  • ece
  • fin
  • psh
  • rst
  • syn
  • urg
class pybatfish.datamodel.flow.Trace(disposition: str, hops: List[pybatfish.datamodel.flow.Hop])[source]

A trace of a flow through the network.

A Trace is a combination of hops and flow fate (i.e., disposition).

  • disposition – Flow disposition
  • hops – A list of hops (Hop) the flow took
class pybatfish.datamodel.flow.TransformationStepDetail(transformationType: str, flowDiffs: List[pybatfish.datamodel.flow.FlowDiff])[source]

Details of a step representation a packet transformation.

  • transformationType – The type of the transformation
  • flowDiffs – Set of changed flow fields

Reference Library

class pybatfish.datamodel.referencelibrary.AddressGroup(name: str, addresses=NOTHING, childGroupNames=NOTHING)[source]

Information about an address group.

  • name – The name of the group
  • addresses – a list of ‘addresses’ where each element is a string that represents an IP address (e.g., “”), prefix (e.g.,, or an address:mask (e.g., “”).
  • childGroupNames – a list of names of child groups in this address group. The child groups must exist in the same reference book. Circular descendant relationships between address groups are allowed. The address group is considered to contain all addresses that are directly in it or in any of its descendants.
class pybatfish.datamodel.referencelibrary.InterfaceGroup(name: str, interfaces=NOTHING)[source]

Information about an interface group.

  • name – The name of the group
  • interfaces – a list of interfaces, of type Interface.
class pybatfish.datamodel.referencelibrary.NodeRole(name: str, regex: str)[source]

Information about a node role.

  • name – Name of the node role.
  • regex – A regular expression over node names to describe nodes that belong to this role. The regular expression must be a valid Java regex.
class pybatfish.datamodel.referencelibrary.NodeRoleDimension(name: str, type: str = 'CUSTOM', roles=NOTHING)[source]

Information about a node role dimension.

  • name – Name of the node role dimension.
  • type – to capture if the dimension contains automatically inferred roles (AUTO) or user-defined roles (CUSTOM).
  • roles – The list of NodeRole objects in this dimension.
class pybatfish.datamodel.referencelibrary.NodeRolesData(roleDimensions=NOTHING)[source]

Information about a node roles data.

Variables:roleDimensions – A list of NodeRoleDimension objects
class pybatfish.datamodel.referencelibrary.ReferenceBook(name: str, addressGroups=NOTHING, interfaceGroups=NOTHING)[source]

Information about a reference book.

  • name – Name of the reference book.
  • addressGroups – A list of groups, of type AddressGroup.
  • interfaceGroups – A list of groups, of type InterfaceGroup.
class pybatfish.datamodel.referencelibrary.ReferenceLibrary(books=NOTHING)[source]

Information about a reference library.

Variables:books – A list of books of type ReferenceBook.


class pybatfish.datamodel.route.BgpRoute(network: str, originatorIp: str, originType: str, protocol: str, asPath: list = [], communities: list = [], localPreference: int = 0, metric: int = 0, sourceProtocol: str = None)[source]

A BGP routing advertisement.

  • network – The network prefix advertised by the route.
  • asPath – The AS path of the route.
  • communities – The communities of the route.
  • localPreference – The local preference of the route.
  • metric – The metric of the route.
  • originatorIp – The IP address of the originator of the route.
  • originType – The origin type of the route.
  • sourceProtocol – The source protocol of the route.
class pybatfish.datamodel.route.BgpRouteDiff(fieldName: str, oldValue: str, newValue: str)[source]

A difference between two BGP routes.

  • fieldName – A Flow field name that has changed.
  • oldValue – The old value of the field.
  • newValue – The new value of the field.
class pybatfish.datamodel.route.BgpRouteDiffs(diffs: List[pybatfish.datamodel.route.BgpRouteDiff])[source]

A set of differences between two BGP routes.

Variables:diffs – The set of BgpRouteDiff objects.


class pybatfish.datamodel.answer.base.Answer[source]

Represents a generic Batfish answer.


A dictionary representation of the full answer.


Return the name of the question that produced this answer.

class pybatfish.datamodel.answer.table.TableAnswer(dictionary)[source]

Batfish answer in the form of a table.


Return the excluded data for exclusion_name as a pandas.DataFrame.


Return answer data as a pandas.DataFrame.