Path Search
These APIs take as input the most common packet header fields together with the ingress device the packet enters at and trace that packet through the network returning the corresponding paths (list of hops and interfaces) that that packet will take. Search results are computed in permit-all mode, which traces traffic past any ACL drops to determine downstream behavior, thereby decoupling the forwarding outcome and security outcome for a path.
In addition to packet descriptions, the APIs also accept other parameters that determine which results are returned when the query has multiple results.
maxCandidates: Limits the number of results computed, before applying any ranking criteriamaxResults: Limits the number of results returned by the API, after applying ranking criteriaintent: Specifies a preference for paths where traffic gets delivered vs. those with reachability violations such as drops, blackholes, or loops.
| Intent | Description |
|---|---|
PREFER_DELIVERED | Prefer paths that result in traffic getting delivered. An example usage is to verify that it's possible for the specified traffic to get delivered to the destination along some path. |
PREFER_VIOLATIONS | Prefer paths that result in the traffic not getting delivered, such as drops, blackholes, and loops. An example usage is to verify that the specified traffic gets delivered to the destination along all possible paths. |
VIOLATIONS_ONLY | Similar to PREFER_VIOLATIONS, but returns only the violations even when there are fewer than maxResults violations. |
Given a query and search criteria, the path search workflow is as follows. Starting with all flows in the network:
- Filter using packet criteria (
srcIp,dstIp,ipProto,srcPort,dstPort,icmpType) - Sort (
intent) - preference for delivered or undelivered paths - Limit (
maxCandidates) - Compute forwarding and security outcomes
- Filter (
intent) - optional step limiting results to undelivered flows whenintentisVIOLATIONS_ONLY - Sort by flow relevance - Uses similar sorting criteria as the application's path search page. A key ranking factor is path length, preferring longer paths (greatest reach) in the network over shorter ones.
- Limit (
maxResults) - Compute network functions - optional step, only if requested
- Return results
The APIs also provide access to return paths, which are the paths taken by response traffic heading back from the destination to the source. This includes modeling the forwarding behavior of any stateful firewalls or load balancers that might only permit response traffic to flow through if the request traffic establishes required state in the device.
A common use case is to find a single relevant path result for some packets. The default values for the search
criteria (intent = PREFER_DELIVERED, maxCandidates = 5000, maxResults = 1), provide access to the most
relevant path for the given packet description. This returns similar results as the first search result displayed
for that query in the application's path search page.