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)[source]
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
ACL Traces
- class pybatfish.datamodel.acl.AclTrace(events: List[AclTraceEvent] = NOTHING)[source]
The trace of a packet’s life through an ACL.
- Variables:
events – A list of
AclTraceEvent
- class pybatfish.datamodel.acl.AclTraceEvent(description: str | None = None)[source]
One event corresponding to a packet’s life through an ACL.
- Variables:
description – The description of the event
- class pybatfish.datamodel.acl.Fragment[source]
An element in
TraceElement.fragments
, can be one ofTextFragment
orLinkFragment
.
- class pybatfish.datamodel.acl.LinkFragment(text: str, vendorStructureId: VendorStructureId)[source]
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)[source]
Represents a plain-text
Fragment
.- Variables:
text – Text content of the fragment
- class pybatfish.datamodel.acl.TraceElement(fragments: List[Fragment])[source]
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: TraceElement, children: List[TraceTree])[source]
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)[source]
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: str | None, resolvedNexthopIp: str | None)[source]
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')[source]
A flow being delegated to a different VRF for further processing.
- class pybatfish.datamodel.flow.DeliveredStepDetail(outputInterface: str | None, resolvedNexthopIp: str | None)[source]
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.EnterInputIfaceStepDetail(inputInterface: str, inputVrf: str | None)[source]
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: str | None)[source]
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: Flow | None)[source]
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.Flow(dscp, dstIp, dstPort, ecn, fragmentOffset, icmpCode, icmpVar, ingressInterface: str | None, ingressNode: str | None, ingressVrf: str | None, ipProtocol: str, packetLength: str, srcIp, srcPort, tcpFlagsAck, tcpFlagsCwr, tcpFlagsEce, tcpFlagsFin, tcpFlagsPsh, tcpFlagsRst, tcpFlagsSyn, tcpFlagsUrg)[source]
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)
- class pybatfish.datamodel.flow.ForwardedIntoVxlanTunnel(vni: int, vtep: str, type: str = 'ForwardedIntoVxlanTunnel')[source]
A flow being forwarded into a VXLAN tunnel.
- class pybatfish.datamodel.flow.ForwardedOutInterface(outputInterface: str, resolvedNextHopIp: str | None = None, type: str = 'ForwardedOutInterface')[source]
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.HeaderConstraints(srcIps: str | None = None, dstIps: str | None = None, srcPorts=None, dstPorts=None, ipProtocols=None, applications=None, icmpCodes=None, icmpTypes=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.
- 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 to2.2.2.2
Any
None
values will be treated as unconstrained.- classmethod of(flow: Flow) HeaderConstraints [source]
Create header constraints from an existing flow.
- class pybatfish.datamodel.flow.Hop(node: str, steps: List[Step])[source]
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)[source]
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: SessionScope, sessionAction: SessionAction, matchCriteria: SessionMatchExpr, transformation: List[FlowDiff] | None = NOTHING)[source]
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: 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”.
- Variables:
tcpFlags – tcp flags to match
useAck
useCwr
useEce
useFin
usePsh
useRst
useSyn
useUrg
- static match_ack() MatchTcpFlags [source]
Return match conditions checking that ACK bit is set.
Other bits may take any value.
- static match_established() List[MatchTcpFlags] [source]
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() List[MatchTcpFlags] [source]
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() MatchTcpFlags [source]
Return match conditions checking that RST bit is set.
Other bits may take any value.
- static match_syn() MatchTcpFlags [source]
Return match conditions checking that the SYN bit is set.
Other bits may take any value.
- static match_synack() MatchTcpFlags [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.PathConstraints(startLocation: str | None = None, endLocation: str | None = None, transitLocations: str | None = None, forbiddenLocations: str | None = None)[source]
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.RoutingStepDetail(routes: List[RouteInfo], forwardingDetail: ForwardingDetail | None, arpIp: str | None, outputInterface: str | None)[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 forwarding action
- class pybatfish.datamodel.flow.SetupSessionStepDetail(sessionScope: SessionScope, sessionAction: SessionAction, matchCriteria: SessionMatchExpr, transformation: List[FlowDiff] | None = NOTHING)[source]
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.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.
- Variables:
ack
cwr
ece
fin
psh
rst
syn
urg
Reference Library
- class pybatfish.datamodel.referencelibrary.AddressGroup(name: str, addresses=NOTHING, childGroupNames=NOTHING)[source]
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)[source]
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(*args, **kwargs)[source]
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(*args, **kwargs)[source]
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: str | None = None, roleDimensionOrder=NOTHING, roleMappings=NOTHING)[source]
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)[source]
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)[source]
Information about a reference library.
- Variables:
books – A list of books of type
ReferenceBook
.
- class pybatfish.datamodel.referencelibrary.RoleDimensionMapping(*args, **kwargs)[source]
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)[source]
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 = None, sourceProtocol: str | None = None, tag: int = 0, weight: int = 0)[source]
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: bool | None = None, localPreference=None, med=None, communities=None, asPath=None)[source]
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)[source]
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[BgpRouteDiff])[source]
A set of differences between two BGP routes.
- Variables:
diffs – The set of BgpRouteDiff objects.
- class pybatfish.datamodel.route.BgpSessionProperties(localAs, remoteAs, localIp: str, remoteIp: str)[source]
Properties of a BGP session.
Properties that may be needed in order to simulate a route map that is used in a particular BGP session.
- Variables:
localAs – The AS number of the session’s local peer
remoteAs – The AS number of the session’s remote peer
localIp – The IP address of the session’s local peer
remoteIp – The IP address of the session’s remote peer
- class pybatfish.datamodel.route.NextHopDiscard(type: str = 'discard')[source]
Indicates the packet should be dropped
- class pybatfish.datamodel.route.NextHopInterface(interface: str, ip: str | None = None, type: str = 'interface')[source]
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')[source]
A next-hop of a route including the next gateway IP