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.Edge(node1: str, node1interface, node2: str, node2interface)

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

Variables

• node1 – First node name

• node1interface – First node’s interface name

• node2 – Second node name

• node2interface – Second node’s interface name

class pybatfish.datamodel.primitives.Interface(hostname: str, interface: str)

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

Variables

• hostname – Node hostname to which this interface belongs

• interface – Interface name

ACL Traces

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

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

Variables

events – A list of AclTraceEvent

class pybatfish.datamodel.acl.AclTraceEvent(description: Optional[str] = None)

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

Variables

description – The description of the event

class pybatfish.datamodel.acl.Fragment

An element in TraceElement.fragments, can be one of TextFragment or LinkFragment.

class pybatfish.datamodel.acl.LinkFragment(text: str, vendorStructureId: pybatfish.datamodel.acl.VendorStructureId)

Represents a Fragment that links to a vendor structure.

Variables

• text – Text content of the fragment

• vendorStructureId – Link of the fragment

class pybatfish.datamodel.acl.TextFragment(text: str)

Represents a plain-text Fragment.

Variables

text – Text content of the fragment

class pybatfish.datamodel.acl.TraceElement(fragments: List[pybatfish.datamodel.acl.Fragment])

Metadata used to create human-readable traces.

Variables

fragments – A list of Fragment which describes an element of a trace

class pybatfish.datamodel.acl.TraceTree(traceElement: pybatfish.datamodel.acl.TraceElement, children: List[TraceTree])

Represents a filter trace tree.

Variables

• traceElement – Metadata and description of the node

• children – A list of sub-traces, i.e. children of the node

class pybatfish.datamodel.acl.VendorStructureId(filename: str, structureType: str, structureName: str)

Identifies a vendor structure in a configuration file.

Variables

• filename – Filename of the configuration file

• structureType – Type of the vendor structure

• structureName – Name of the vendor structure

Flows and Packets

class pybatfish.datamodel.flow.ArpErrorStepDetail(outputInterface: Optional[str], resolvedNexthopIp: Optional[str])

Details of a step representing the arp error of a flow when sending out of a Hop.

Variables

• outputInterface – Interface of the Hop from which the flow exits

• resolvedNexthopIp – Resolve next hop Ip address

class pybatfish.datamodel.flow.DelegatedToNextVrf(nextVrf: str, type: str = 'DelegatedToNextVrf')

A flow being delegated to a different VRF for further processing.

class pybatfish.datamodel.flow.DeliveredStepDetail(outputInterface: Optional[str], resolvedNexthopIp: Optional[str])

Details of a step representing the flow is delivered or exiting the network.

Variables

• outputInterface – Interface of the Hop from which the flow exits

• resolvedNexthopIp – Resolve next hop Ip address

class pybatfish.datamodel.flow.Discarded(type: str = 'Discarded')

A flow being discarded.

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

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

Variables

• 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])

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

Variables

• 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, inputInterface: str, flow: Optional[pybatfish.datamodel.flow.Flow])

Details of a step representing a filter step.

Variables

• filter – filter name

• type – filter type

• inputInterface – input interface of the flow

• flow – current flow

class pybatfish.datamodel.flow.ForwardedIntoVxlanTunnel(vni: int, vtep: str, type: str = 'ForwardedIntoVxlanTunnel')

A flow being forwarded into a VXLAN tunnel.

class pybatfish.datamodel.flow.ForwardedOutInterface(outputInterface: str, resolvedNextHopIp: Optional[str] = None, type: str = 'ForwardedOutInterface')

A flow being forwarded out an interface.

If there is no resolved next-hop IP and this is the final step on this node, the destination IP of the flow will be used as the next gateway IP.

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, tcpFlagsAck, tcpFlagsCwr, tcpFlagsEce, tcpFlagsFin, tcpFlagsPsh, tcpFlagsRst, tcpFlagsSyn, tcpFlagsUrg)

A concrete IPv4 flow.

Noteworthy attributes for flow inspection/filtering:

Variables

• 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 either as its name (e.g., TCP) for well-known protocols or a string like UNNAMED_168

• 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)

get_flag_str()

Returns a print friendly version of all set TCP flags.

get_ip_protocol_str()

Returns a print-friendly version of IP protocol and any protocol-specific information (e.g., flags for TCP, type/code for ICMP.

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, ecns=None, dscps=None, packetLengths=None, fragmentOffsets=None, tcpFlags=None)

Constraints on an IPv4 packet header space.

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

Variables

• 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

• 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, ecns=None, dscps=None, packetLengths=None, fragmentOffsets=None, tcpFlags=None)

means allow TCP OR UDP.

Different fields are ANDed together:

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

means an SSH connection originating at 1.1.1.1 and going to 2.2.2.2

Any None values will be treated as unconstrained.

classmethod of(flow)

Create header constraints from an existing flow.

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

A single hop in a flow trace.

Variables

• node – Name of node considered as the Hop

• steps – List of steps taken at this Hop

class pybatfish.datamodel.flow.InboundStepDetail(interface: str)

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

Variables

interface – interface that owns the destination IP

class pybatfish.datamodel.flow.MatchSessionStepDetail(sessionScope: pybatfish.datamodel.flow.SessionScope, sessionAction: pybatfish.datamodel.flow.SessionAction, matchCriteria: pybatfish.datamodel.flow.SessionMatchExpr, transformation: Optional[List[pybatfish.datamodel.flow.FlowDiff]] = NOTHING)

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

Variables

• sessionScope – Scope of flows session can match (incoming interfaces or originating VRF)

• sessionAction – A SessionAction that the firewall takes for a matching session

• matchCriteria – A SessionMatchExpr that describes the match criteria of the session

• transformation – List of FlowDiffs that will be applied after session match

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)

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”.

Variables

• tcpFlags – tcp flags to match

• useAck –

• useCwr –

• useEce –

• useFin –

• usePsh –

• useRst –

• useSyn –

• useUrg –

static match_ack()

Return match conditions checking that ACK bit is set.

Other bits may take any value.

static match_established()

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

Other bits may take any value.

static match_not_established()

Return a list of match conditions matching a non-established flow.

Meaning both ACK and RST bits are unset. Other bits may take any value.

static match_rst()

Return match conditions checking that RST bit is set.

Other bits may take any value.

static match_syn()

Return match conditions checking that the SYN bit is set.

Other bits may take any value.

static match_synack()

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)

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[pybatfish.datamodel.flow.RouteInfo], forwardingDetail: Optional[pybatfish.datamodel.flow.ForwardingDetail], arpIp: Optional[str], outputInterface: Optional[str])

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

Variables

routes – List of routes which were considered to select the forwarding action

class pybatfish.datamodel.flow.SetupSessionStepDetail(sessionScope: pybatfish.datamodel.flow.SessionScope, sessionAction: pybatfish.datamodel.flow.SessionAction, matchCriteria: pybatfish.datamodel.flow.SessionMatchExpr, transformation: Optional[List[pybatfish.datamodel.flow.FlowDiff]] = NOTHING)

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

Variables

• sessionScope – Scope of flows session can match (incoming interfaces or originating VRF)

• sessionAction – A SessionAction that the firewall takes for a return traffic matching the session

• matchCriteria – A SessionMatchExpr that describes the match criteria of the session

• transformation – List of FlowDiffs that will be applied on the return traffic matching the session

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

Constraints on the path of a flow.

Variables

• startLocation – Location specification for where a flow is allowed to start

• endLocation – Node specification for where a flow is allowed to terminate

• transitLocations – Node specification for where a flow must transit

• forbiddenLocations – Node specification for 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)

Represents a set of TCP flags in a packet.

Variables

• ack –

• cwr –

• ece –

• fin –

• psh –

• rst –

• syn –

• urg –

class pybatfish.datamodel.flow.Trace(disposition: str, hops: List[pybatfish.datamodel.flow.Hop])

A trace of a flow through the network.

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

Variables

• 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])

Details of a step representation a packet transformation.

Variables

• 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)

Information about an address group.

Variables

• name – The name of the group

• addresses – a list of ‘addresses’ where each element is a string that represents an IP address (e.g., “1.1.1.1”), prefix (e.g., 1.1.1.0/24), or an address:mask (e.g., “1.1.1.1:0.0.0.8”).

• 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)

Information about an interface group.

Variables

• name – The name of the group

• interfaces – a list of interfaces, of type Interface.

class pybatfish.datamodel.referencelibrary.NodeRole(name: str, regex: str)

Information about a node role.

Variables

• 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, roles=NOTHING, roleDimensionMappings=NOTHING)

Information about a node role dimension.

Variables

• name – Name of the node role dimension.

• roles – The list of NodeRole objects in this dimension (deprecated).

• roleDimensionMappings – The list of RoleDimensionMapping objects in this dimension.

class pybatfish.datamodel.referencelibrary.NodeRolesData(defaultDimension: Optional[str] = None, roleDimensionOrder=NOTHING, roleMappings=NOTHING)

Information about a node roles data.

:ivar defaultDimension :ivar roleDimensionOrder: The precedence order of role dimensions. :ivar roleMappings: A list of RoleMapping objects

class pybatfish.datamodel.referencelibrary.ReferenceBook(name: str, addressGroups=NOTHING, interfaceGroups=NOTHING)

Information about a reference book.

Variables

• 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)

Information about a reference library.

Variables

books – A list of books of type ReferenceBook.

class pybatfish.datamodel.referencelibrary.RoleDimensionMapping(regex: str, groups: List[int] = [1], canonicalRoleNames: Dict[str, str] = {})

Information about a role dimension mapping.

Variables

• regex – A regular expression over node names to describe nodes that belong to this role. The regular expression must be a valid Java regex.

• groups – A list of group numbers (integers) that identify the role name for a given node name (default value is [1]).

• canonicalRoleNames – A map from Java regexes over role names determined from the groups to a canonical set of role names for this dimension (default value is {}).

class pybatfish.datamodel.referencelibrary.RoleMapping(name: str, regex: str, roleDimensionGroups: Dict[str, int], canonicalRoleNames: Dict[str, Dict[str, str]] = NOTHING)

A mapping from node name to role dimensions.

Variables

• name – (Optional) the name of the role mapping

• regex – A java regex over hostnames, with groups to extract role data

• roleDimensionGroups – a map from each role dimension name to the list of regex groups that signify the role name for that dimension.

• canonicalRoleNames – for each role dimension, a map from the default role name that was obtained from the node name to a canonical role name

Routes

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

A BGP routing advertisement.

Variables

• 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.

• nextHopIp – The next hop IP of the route.

• protocol – The protocol 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.

• tag – The tag of the route.

• weight – The weight of the route.

class pybatfish.datamodel.route.BgpRouteConstraints(prefix=None, complementPrefix: Optional[bool] = None, localPreference=None, med=None, communities=None, asPath=None)

Constraints on a BGP route announcement.

Specify constraints on route announcements by specifying allowed values in each field of the announcement.

Variables

• prefix – Allowed prefixes as a list of prefix ranges (e.g., “0.0.0.0/0:0-32”)

• complementPrefix – A flag indicating that all prefixes except the ones in prefix are allowed

• localPreference – List of allowed local preference integer ranges, as a string

• med – List of allowed MED integer ranges, as a string

• communities – List of allowed and disallowed community regexes

• asPath – List of allowed and disallowed AS-path regexes

class pybatfish.datamodel.route.BgpRouteDiff(fieldName: str, oldValue: str, newValue: str)

A difference between two BGP routes.

Variables

• 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])

A set of differences between two BGP routes.

Variables

diffs – The set of BgpRouteDiff objects.

class pybatfish.datamodel.route.NextHop

A next-hop of a route

class pybatfish.datamodel.route.NextHopDiscard(type: str = 'discard')

Indicates the packet should be dropped

class pybatfish.datamodel.route.NextHopInterface(interface: str, ip: Optional[str] = None, type: str = 'interface')

A next-hop of a route with a fixed output interface and optional next gateway IP.

If there is no IP, the destination IP of the packet will be used as the next gateway IP.

class pybatfish.datamodel.route.NextHopIp(ip: str, type: str = 'ip')

A next-hop of a route including the next gateway IP

class pybatfish.datamodel.route.NextHopVrf(vrf: str, type: str = 'vrf')

A next-hop of a route indicating the destination IP should be resolved in another VRF

class pybatfish.datamodel.route.NextHopVtep(vni: int, vtep: str, type: str = 'vtep')

A next-hop of a route indicating the packet should be routed through a VXLAN tunnel

Misc question outputs

class pybatfish.datamodel.primitives.FileLines(filename: str, lines: List[int] = NOTHING)

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

Variables

• filename – The filename referenced

• lines – A list of lines referenced