Why path tracing across vendors is hard
Tracing a packet through a single-vendor network is straightforward. The route table format is consistent, ACL syntax is uniform, and interface naming follows one convention. The moment you add a second vendor, every assumption breaks. IOS uses wildcard masks in ACLs. PAN-OS uses zone-based policies with application-aware rules. NX-OS has a different route table format with ubest/mbest notation. IOS-XR uses yet another syntax. SAMURAI’s traffic simulation engine handles all of them through a single hop-by-hop tracing pipeline.
Which device owns the source IP?
Before the first hop can be computed, SAMURAI needs to figure out which device owns the source IP. The resolution follows a strict priority order: interface IPs first (a directly connected interface is authoritative), then ARP tables, then the endpoint aggregation pipeline, then APIC host records (which resolve a MAC to a physical switch), and finally subnet matching as a last resort.
Interface IPs outrank ARP deliberately. If a router has 10.1.1.1 configured on GigabitEthernet0/1, that is the source device, regardless of what ARP says. The ipToDevice map is built with this priority baked in, so lookups are O(1) at trace time.
The first hop picks the VRF
VRF selection happens on the first hop. SAMURAI looks at the source IP and finds the connected or local route that matches it. The VRF of that route becomes the VRF for the entire trace. This matters in environments where the same IP range exists in multiple VRFs, where a trace that ignored VRFs would follow the wrong path.
Platform auto-detection (connectors/platform/platform.go) runs show version to identify the device as ios, nxos, nxos-aci, or ios-xr. The platform determines how routes are parsed and how ACLs are evaluated. NX-OS ACI requires a vsh prologue via ExecuteValidatedWithPrologue before any command executes.
Checking ACLs hop by hop
At each hop, SAMURAI checks the ACLs applied to the ingress and egress interfaces against the full 5-tuple (source IP, destination IP, protocol, source port and destination port). It handles Cisco-style inverted wildcard masks and the port operators eq, gt, lt, and range.
If the packet is permitted, the trace continues to the next hop. If denied, the trace stops and reports the denying ACL entry. If the next-hop resolves to an unmanaged device (one that is not registered in SAMURAI), the trace terminates with a “destination unmanaged” status. Default routes pointing outside the managed network end the trace the same way.
Why it traces both directions
SAMURAI runs the forward trace first, then the reverse trace with source and destination swapped. A path that works in one direction and fails in the other is a common cause of “it works from my desk but not from the server” tickets. The reverse trace uses the same resolution chain and ACL evaluation, starting from the destination device.
You get the path drawn in both directions across IOS, NX-OS, IOS-XR, PAN-OS and FTD, with the ACL decision at each hop written down, so nobody has to SSH into five boxes and run traceroutes to find out which firewall drops the packet.