{ "openapi": "3.1.0", "info": { "title": "Forward Networks: Path Search API", "summary": "Trace packets through the network model", "description": "These APIs take as input the most common packet header fields together with the ingress device the packet enters\nat and trace that packet through the network returning the corresponding paths (list of hops and interfaces) that\nthat packet will take. Search results are computed in _permit-all mode_, which traces traffic past any ACL drops\nto determine downstream behavior, thereby decoupling the _forwarding outcome_ and _security outcome_ for a path.\n\nIn addition to packet descriptions, the APIs also accept other parameters that determine which results are returned\nwhen the query has multiple results.\n- `maxCandidates`: Limits the number of results computed, before applying any ranking criteria\n- `maxResults`: Limits the number of results returned by the API, after applying ranking criteria\n- `intent`: Specifies a preference for paths where traffic gets delivered vs. those with reachability violations\n such as drops, blackholes, or loops.\n\n| Intent | Description |\n| ------ | ----------- |\n| `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. |\n| `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. |\n| `VIOLATIONS_ONLY` | Similar to `PREFER_VIOLATIONS`, but returns only the violations even when there are fewer than `maxResults` violations. |\n\nGiven a query and search criteria, the path search workflow is as follows. Starting with all flows in the network:\n\n1. Filter using packet criteria (`srcIp`, `dstIp`, `ipProto`, `srcPort`, `dstPort`, `icmpType`)\n2. Sort (`intent`) - preference for delivered or undelivered paths\n3. Limit (`maxCandidates`)\n4. Compute forwarding and security outcomes\n5. Filter (`intent`) - optional step limiting results to undelivered flows when `intent` is `VIOLATIONS_ONLY`\n6. Sort by flow relevance - Uses similar sorting criteria as the application's\n [path search](https://docs.fwd.app/latest/application/search/path-analysis/) page. A key ranking factor is path\n length, preferring longer paths (greatest reach) in the network over shorter ones.\n7. Limit (`maxResults`)\n8. Compute network functions - optional step, only if requested\n9. Return results\n\nThe APIs also provide access to _return paths_, which are the paths taken by response traffic heading back from the\ndestination to the source. This includes modeling the forwarding behavior of any stateful firewalls or load\nbalancers that might only permit response traffic to flow through if the request traffic establishes required state\nin the device.\n\nA common use case is to find a single relevant path result for some packets. The default values for the search\ncriteria (`intent = PREFER_DELIVERED`, `maxCandidates = 5000`, `maxResults = 1`), provide access to the most\nrelevant path for the given packet description. This returns similar results as the first search result displayed\nfor that query in the application's path search page.", "contact": { "email": "support@forwardnetworks.com" }, "license": { "name": "MIT", "url": "https://spdx.org/licenses/MIT" }, "version": "${apiVersion}" }, "servers": [ { "url": "/api" } ], "security": [ { "api_token": [] } ], "tags": [ { "name": "Path Search", "description": "Trace packets through the network model" } ], "paths": { "/l7-applications": { "get": { "tags": [ "Path Search" ], "summary": "List known L7 applications", "operationId": "getL7Applications", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/L7Application" } } } } } } } }, "/networks/{networkId}/paths": { "get": { "tags": [ "Path Search" ], "summary": "Trace packets through the network", "operationId": "getPaths", "parameters": [ { "name": "networkId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "the device from which the traffic originates. If this is specified, then the srcIp will be considered as a\npacket header only, else, the srcIp will be resolved to specific location(s) and used as the source in the\npath search. Either the source device or srcIp must be specified.", "schema": { "type": "string" } }, { "name": "srcIp", "in": "query", "description": "the source IP address or subnet of packets entering the network. For multicast (*, G) paths, set srcIp = G\n(multicast group address).", "schema": { "type": "string" } }, { "name": "dstIp", "in": "query", "description": "the destination IP address or subnet of packets entering the network. For multicast (*, G) paths, set dstIp\n= G (multicast group address).", "required": true, "schema": { "type": "string" } }, { "name": "intent", "in": "query", "description": "Specifies the intent for the search. Default PREFER_DELIVERED.\n*PREFER_VIOLATIONS*: Prefer paths that result in the traffic not getting delivered, e.g. drops, blackholes,\nloops. An example usage is while trying to evaluate if the specified traffic always gets delivered to the\ndestination along all path choices.\n*PREFER_DELIVERED*: Prefer paths that result in the traffic getting delivered. An example usage is while\ntrying to evaluate if traffic gets delivered to the destination along any path choice.\n*VIOLATIONS_ONLY*: Search for paths where traffic is not delivered to the destination.", "schema": { "$ref": "#/components/schemas/SearchIntent", "default": "PREFER_DELIVERED" } }, { "name": "ipProto", "in": "query", "description": "the IP protocol", "schema": { "type": "integer", "format": "int32" } }, { "name": "srcPort", "in": "query", "description": "the L4 source port, like \"80\" or a range \"8080-8088\"", "schema": { "type": "string" } }, { "name": "dstPort", "in": "query", "description": "the L4 destination port, like \"80\" or a range \"8080-8088\"", "schema": { "type": "string" } }, { "name": "icmpType", "in": "query", "description": "the ICMP type. Implies ipProto = 1.", "schema": { "type": "integer", "format": "int32" } }, { "name": "fin", "in": "query", "description": "the FIN (finish) bit (0 or 1). Implies ipProto = 6.", "schema": { "type": "integer", "format": "int32" } }, { "name": "syn", "in": "query", "description": "the SYN (synchronize) bit (0 or 1). Implies ipProto = 6.", "schema": { "type": "integer", "format": "int32" } }, { "name": "rst", "in": "query", "description": "the RST (reset) bit (0 or 1). Implies ipProto = 6.", "schema": { "type": "integer", "format": "int32" } }, { "name": "psh", "in": "query", "description": "the PSH (push) bit (0 or 1). Implies ipProto = 6.", "schema": { "type": "integer", "format": "int32" } }, { "name": "ack", "in": "query", "description": "the ACK (acknowledgment) bit (0 or 1). Implies ipProto = 6.", "schema": { "type": "integer", "format": "int32" } }, { "name": "urg", "in": "query", "description": "the URG (urgent) bit (0 or 1). Implies ipProto = 6.", "schema": { "type": "integer", "format": "int32" } }, { "name": "appId", "in": "query", "description": "the L7 app-id or \"unidentified\" to exclude paths that traverse firewall policies with app-id matches. If the\nsystem doesn't recognize the provided value, it handles the value the same as \"unidentified\" and includes\nthe value in the `unrecognizedValues` response field. The applications that are recognized by the model can\nbe obtained using GET /api/l7-applications.", "schema": { "type": "string" } }, { "name": "userId", "in": "query", "description": "the L7 user-id or \"unidentified\" to exclude paths that traverse firewall policies with user-id matches. If\nthe system doesn't recognize the provided value, it handles the value the same as \"unidentified\" and\nincludes the value in the `unrecognizedValues` response field. See [Path Analysis with Layer 7\nUser-Group](https://docs.fwd.app/latest/application/search/path-analysis/layer7_ugroup/) for more info.", "schema": { "type": "string" } }, { "name": "userGroupId", "in": "query", "description": "the L7 user-group-id. If the system doesn't recognize the provided value, the search returns 0 results as\nthere are no paths that traverse firewall policies with that user-group-id match, and the value is included\nin the `unrecognizedValues` response field. See [Path Analysis with Layer 7\nUser-Group](https://docs.fwd.app/latest/application/search/path-analysis/layer7_ugroup/) for more info.", "schema": { "type": "string" } }, { "name": "url", "in": "query", "description": "the L7 URL that traffic of interest is trying to access. Prefix wildcards are supported for subdomains.\nSuffix wildcards are supported for top-level domains and URL paths. See [Path Analysis with Layer 7\nURL](https://docs.fwd.app/latest/application/search/path-analysis/layer7_url/) for more policy patterns\nsupported in the model.", "schema": { "type": "string" } }, { "name": "includeTags", "in": "query", "description": "If true, the response will include device tags for each hop.", "schema": { "type": "boolean", "default": false } }, { "name": "includeNetworkFunctions", "in": "query", "description": "If true, the response includes detailed forwarding info for each hop.\nNote: Setting this to true increases the API response time.", "schema": { "type": "boolean", "default": false } }, { "name": "maxCandidates", "in": "query", "description": "the limit on the number of search results computed, before applying any ranking criteria. Permitted range =\n1 to 10,000. Default 5,000.", "schema": { "type": "integer", "format": "int32", "default": 5000 } }, { "name": "maxResults", "in": "query", "description": "the limit on the number of search results returned by the API. First, the platform computes up to\nmaxCandidates results that match the search criteria. Then they are sorted by various ranking criteria. A\nkey ranking factor is path length, preferring longer paths (greatest reach) in the network over shorter\nones. Finally, the API limits the number of returned search results to maxResults. Permitted range = 1 to\nmaxCandidates. Default 1.", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "maxReturnPathResults", "in": "query", "description": "the limit on the number of return path search results. Permitted range = 0 to 10,000. Default 0. Multicast\n(*, G) and (S, G) queries will always return 0 return path results regardless of this value.", "schema": { "type": "integer", "format": "int32", "default": 0 } }, { "name": "maxSeconds", "in": "query", "description": "the timeout duration. Permitted range = 1 to 300. Default 30.", "schema": { "type": "integer", "format": "int32", "default": 30 } }, { "$ref": "#/components/parameters/SnapshotId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PathSearchResponse" } } } }, "409": { "description": "The system is currently processing this Snapshot.\n\nNote: GET /networks/{networkId}/snapshots/latestProcessed can be used to determine when processing of the\nlatest Snapshot is done or to identify an alternate Snapshot that has already been processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } } }, "/networks/{networkId}/paths-bulk": { "post": { "tags": [ "Path Search" ], "summary": "Trace sets of packets through the network", "operationId": "getPathsBulk", "parameters": [ { "name": "networkId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/SnapshotId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PathSearchBulkRequest" } } }, "required": true }, "responses": { "200": { "description": "The response is an array containing a result (a `PathSearchResponse` or an error object) for each query in\nthe request, in the same order. An error object has an `\"error\": true` property. Each query is evaluated\nindependently.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PathSearchResponse" } } } } }, "400": { "description": "The request failed input validation. For example, a request parameter is outside the permitted range or an\ninput path search query had an invalid IP protocol and ICMP type combination.", "content": {} }, "409": { "description": "The system is currently processing this Snapshot.\n\nNote: GET /networks/{networkId}/snapshots/latestProcessed can be used to determine when processing of the\nlatest Snapshot is done or to identify an alternate Snapshot that has already been processed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } } }, "/networks/{networkId}/paths-bulk-seq": { "post": { "tags": [ "Path Search" ], "summary": "Trace sets of packets through the network", "operationId": "getPathsBulkSeq", "parameters": [ { "name": "networkId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/SnapshotId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PathSearchBulkRequest" } } }, "required": true }, "responses": { "200": { "description": "The response is a sequence of a result (a `PathSearchResponse` or an error object) for each query in the\nrequest, in the same order. Each result is prefixed by an ASCII Record Separator (0x1E), and ends with an\nASCII Line Feed character (0x0A), as described in [RFC 7464: JSON Text\nSequences](https://tools.ietf.org/html/rfc7464). An error object has an `\"error\": true` property. Each query\nis evaluated independently.", "content": { "application/json-seq": { "schema": { "$ref": "#/components/schemas/PathSearchResponse" } } } }, "400": { "description": "The request failed input validation. For example, a request parameter is outside the permitted range or an\ninput path search query had an invalid IP protocol and ICMP type combination.", "content": {} }, "409": { "description": "The system is currently processing this Snapshot.\n\nNote: GET /networks/{networkId}/snapshots/latestProcessed can be used to determine when processing of the\nlatest Snapshot is done or to identify an alternate Snapshot that has already been processed.", "content": { "application/json-seq": { "schema": { "$ref": "#/components/schemas/ErrorInfo" } } } } } } } }, "components": { "schemas": { "ErrorInfo": { "type": "object", "required": [ "httpMethod", "apiUrl", "message" ], "properties": { "httpMethod": { "type": "string", "examples": [ "GET" ], "enum": [ "GET", "HEAD", "POST", "PUT", "PATCH", "DELETE" ] }, "apiUrl": { "type": "string", "examples": [ "/api/version" ] }, "message": { "type": "string", "description": "A description of the error" }, "reason": { "type": "string" } } }, "L7Application": { "type": "object", "properties": { "id": { "type": "string" } } }, "PathSearchBulkRequest": { "type": "object", "required": [ "queries" ], "properties": { "queries": { "type": "array", "items": { "$ref": "#/components/schemas/PathSearchQuery" } }, "intent": { "$ref": "#/components/schemas/SearchIntent", "description": "Specifies the intent for the search. Default PREFER_DELIVERED.\n*PREFER_VIOLATIONS*: Prefer paths that result in the traffic not getting delivered, e.g. drops, blackholes,\nloops. An example usage is while trying to evaluate if the specified traffic always gets delivered to the\ndestination along all path choices.\n*PREFER_DELIVERED*: Prefer paths that result in the traffic getting delivered. An example usage is while\ntrying to evaluate if traffic gets delivered to the destination along any path choice.\n*VIOLATIONS_ONLY*: Search for paths where traffic is not delivered to the destination.", "examples": [ "PREFER_DELIVERED" ], "default": "PREFER_DELIVERED" }, "maxCandidates": { "type": "integer", "format": "int32", "description": "the limit on the number of search results computed, before applying any ranking criteria. Permitted range =\n1 to 10,000. Default 5,000.", "examples": [ 5000 ] }, "maxResults": { "type": "integer", "format": "int32", "description": "the limit on the number of search results returned by the API. First, the platform computes up to\nmaxCandidates results that match the search criteria. Then they are sorted by various ranking criteria. A\nkey ranking factor is path length, preferring longer paths (greatest reach) in the network over shorter\nones. Finally, the API limits the number of returned search results to maxResults. Permitted range = 1 to\nmaxCandidates. Default 1.", "examples": [ 1 ] }, "maxReturnPathResults": { "type": "integer", "format": "int32", "description": "the limit on the number of return path search results. Permitted range = 0 to 10,000. Default 0. Multicast\n(*, G) and (S, G) queries will always return 0 return path results regardless of this value.", "examples": [ 0 ] }, "maxSeconds": { "type": "integer", "format": "int32", "description": "the timeout duration per search query. Permitted range = 1 to 300. Default 30.", "examples": [ 30 ] }, "maxOverallSeconds": { "type": "integer", "format": "int32", "description": "the overall timeout duration. Permitted range = 1 to 7,200. Default equal to the timeout duration for a\nsingle query.", "examples": [ 300 ] }, "includeTags": { "type": "boolean", "description": "If true, the response will include device tags for each hop.", "examples": [ false ] }, "includeNetworkFunctions": { "type": "boolean", "description": "If true, the response includes detailed forwarding info for each hop.\nNote: Setting this to true increases the API response time.", "examples": [ false ] } } }, "PathSearchResponse": { "type": "object", "properties": { "srcIpLocationType": { "type": "string", "description": "Specifies the location discovery method for source IP.\nThe enum values are ordered from most precise to least precise discovery method.\n*INTERFACE*: The IP is a configured IP address of one or more device interfaces.\n*HOST*: The IP corresponds to discovered host(s).\n*SNAT* : The IP is used as the post-translated IP of a Source NAT function in the network and is assumed to\nbe located on the gateway device(s) performing this translation.\n*CO_LOCATED*: The IP is configured on a gateway device as a /32 or /128 route whose next hop is a known\nhost.\n*INTERFACE_ATTACHED_SUBNET*: The IP falls within the attached subnet of L3 interface(s).\n*INTERNET*: The IP is in the public internet and was located at the network's Internet Node. This discovery\nmethod is only applicable when an Internet Node is configured in the network.\n*ROUTE*: The IP was located based on injected routes in the network.\n*MULTICAST*: The IP is a multicast group address. This discovery method is used to locate the rendezvous\npoints of the multicast group and use their IP addresses as IP source.", "enum": [ "INTERFACE", "HOST", "SNAT", "CO_LOCATED", "INTERFACE_ATTACHED_SUBNET", "INTERNET", "ROUTE", "MULTICAST" ] }, "dstIpLocationType": { "type": "string", "description": "Specifies the location discovery method for destination IP.\nThe enum values are ordered from most precise to least precise discovery method.\n*INTERFACE*: The IP is a configured IP address of one or more device interfaces.\n*HOST*: The IP corresponds to discovered host(s).\n*DNAT*: The IP gets DNAT'd in the network. The IP may either correspond directly to a VIP on a load balancer\nor a DNAT'd IP on other devices such as routers. This discovery method is only used to locate destination IP\naddresses. DNAT’d IP addresses are recursively resolved to determine where traffic to a given destination IP\nmust be delivered in the network.\n*CO_LOCATED*: The IP is configured on a gateway device as a /32 or /128 route whose next hop is a known\nhost.\n*INTERFACE_ATTACHED_SUBNET*: The IP falls within the attached subnet of L3 interface(s).\n*INTERNET*: The IP is in the public internet and was located at the network's Internet Node. This discovery\nmethod is only applicable when an Internet Node is configured in the network.\n*ROUTE*: The IP was located based on injected routes in the network.\n*MULTICAST*: The IP is a multicast group address.", "enum": [ "INTERFACE", "HOST", "DNAT", "CO_LOCATED", "INTERFACE_ATTACHED_SUBNET", "INTERNET", "ROUTE", "MULTICAST" ] }, "info": { "$ref": "#/components/schemas/PathInfo" }, "returnPathInfo": { "$ref": "#/components/schemas/PathInfo" }, "timedOut": { "type": "boolean" }, "queryUrl": { "type": "string", "description": "A Forward application URL at which this path search can be explored or refined interactively" }, "unrecognizedValues": { "$ref": "#/components/schemas/UnrecognizedValues", "description": "L7 values from the request that were unrecognized by the system" } } }, "SearchIntent": { "type": "string", "enum": [ "PREFER_VIOLATIONS", "PREFER_DELIVERED", "VIOLATIONS_ONLY" ] }, "DeviceType": { "type": "string", "enum": [ "UNKNOWN", "ROUTER", "SWITCH", "VSWITCH", "FIREWALL", "LOADBALANCER", "BUNDLED_ROUTER", "CIRCUIT", "L2_VPN_SERVICE", "MISSING_PEER", "MPLS_VPN_SERVICE", "INTERNET_SERVICE", "INTRANET_SERVICE", "SYNTHETIC_ENCRYPTOR", "HYPERVISOR", "CONTROLLER", "WAN_OPTIMIZER", "OPENFLOW_SWITCH", "SD_WAN", "RIVERBED_INTERCEPTOR", "WIFI_AP", "ENCRYPTOR", "DDI", "NIC", "AWS_CLOUD", "AWS_SUBNET", "AWS_RT", "AWS_INTERNET_GW", "AWS_NAT_GW", "AWS_VPN_GW", "AWS_LB", "AWS_GLOBAL_ACCELERATOR", "AWS_DIRECT_CONNECT_GW", "AWS_TRANSIT_GW", "AWS_LOCAL_GW", "AWS_NETWORK_FIREWALL", "AWS_GATEWAY_LB", "AWS_SERVICE_ENDPOINT", "EDGE_VM", "AZURE_CLOUD", "AZURE_SUBNET", "AZURE_VNET", "AZURE_VNET_GW", "AZURE_FIREWALL", "AZURE_APP_GW", "AZURE_FRONTDOOR", "AZURE_LB", "AZURE_VWAN_HUB", "AZURE_VPN_GATEWAY", "AZURE_P2S_VPN_GATEWAY", "AZURE_EXPRESS_ROUTE_GATEWAY", "AZURE_VIRTUAL_APPLIANCE", "AZURE_EXPRESS_ROUTE_CIRCUIT", "GCP_CLOUD", "GCP_RT", "GCP_SUBNET", "GCP_LB", "GCP_TRAFFIC_DIRECTOR", "GCP_VPN_GW", "GCP_NAT_GW", "GCP_SERVICE_ATTACHMENT", "ALKIRA_CLOUD" ] }, "AclFunction": { "type": "object", "properties": { "name": { "type": "string", "description": "the name of the ACL that is applied to traffic" }, "context": { "type": "string", "description": "the context in which the ACL function is applied", "enum": [ "INPUT", "OUTPUT" ] }, "action": { "type": "string", "description": "the action taken by the ACL function", "enum": [ "PERMIT", "DENY" ] } } }, "InterfaceFunctionL2Info": { "type": "object", "properties": { "interfaceName": { "type": "string" } } }, "InterfaceFunctionL3Info": { "type": "object", "properties": { "interfaceName": { "type": "string" }, "vrf": { "type": "string", "description": "Null if the interface does not belong to any VRF" } } }, "InterfaceFunction": { "type": "object", "properties": { "l2": { "$ref": "#/components/schemas/InterfaceFunctionL2Info" }, "l3": { "$ref": "#/components/schemas/InterfaceFunctionL3Info" }, "securityZone": { "type": "string" } } }, "NetworkFunctions": { "type": "object", "properties": { "acl": { "type": "array", "items": { "$ref": "#/components/schemas/AclFunction" } }, "egress": { "$ref": "#/components/schemas/InterfaceFunction" }, "ingress": { "$ref": "#/components/schemas/InterfaceFunction" } }, "description": "Detailed forwarding info" }, "PathHop": { "type": "object", "properties": { "deviceName": { "type": "string" }, "displayName": { "type": "string", "description": "Alternate device name that might be more recognizable but isn’t necessarily unique in the network. For cloud\ndevices, this is the name configured in the cloud provider’s console." }, "deviceType": { "$ref": "#/components/schemas/DeviceType" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "present only if device tags are specifically requested" }, "parseError": { "type": "boolean", "description": "`true` indicates that this device’s behavior model might not be reliable" }, "ingressInterface": { "type": "string", "description": "the physical interface name, where traffic entered the device" }, "egressInterface": { "type": "string", "description": "the physical interface name, where traffic exited the device.\nAbsent if this is the last hop and traffic did not exit the device." }, "behaviors": { "type": "array", "items": { "type": "string", "enum": [ "L2", "L3", "NAT", "PBR", "ACL_PERMIT", "ACL_DENY" ] }, "description": "Specifies the forwarding behaviors experienced by traffic at the device.\n*L2*: Forwarded at layer 2.\n*L3*: Routed at layer 3.\n*NAT*: NAT transformations applied.\n*PBR*: Forwarded using Policy-Based Routing.\n*ACL_PERMIT*: ACLs were applied to traffic at the device and the traffic was permitted.\n*ACL_DENY*: ACLs were applied to traffic at the device and the traffic was dropped." }, "networkFunctions": { "$ref": "#/components/schemas/NetworkFunctions" }, "backfilledFrom": { "type": "string", "description": "the collection instant from which the device was backfilled" } } }, "Path": { "type": "object", "properties": { "forwardingOutcome": { "type": "string", "description": "Specifies the traffic forwarding outcome along a path.\n*DELIVERED*: Traffic was delivered to destination IP’s discovered location(s).\n*DELIVERED_TO_INCORRECT_LOCATION*: Traffic was delivered out of some edge ports. However, traffic did not\nreach the expected delivery locations based on destination IP’s discovered locations. One scenario where\nthis occurs is when a device in the middle of the actual path from source IP to destination IP is not\nconfigured for collection in the Forward platform. For example, suppose the actual device path is A -> B ->\nC, and only devices A and C are part of the snapshot in the Forward platform. In this case, the path would\nshow traffic exiting device A at some edge port, but since destination IP is discovered to reside at device\nC, traffic is delivered to an incorrect location.\n*BLACKHOLE*: Traffic was implicitly dropped at the last hop, since the device had no matching rule. For\nexample, if a router does not have a default route, traffic to any IP that is not in the routing table gets\nblackholed.\n*DROPPED*: Traffic was explicitly dropped at the last hop, e.g. by a null route.\n*INADMISSIBLE*: Traffic was not admitted into the network. The first hop interface does not accept the\ntraffic, e.g. incoming traffic had a vlan tag 10 while the ingress interface is an access interface that\nonly permits traffic with vlan tag 20.\n*UNREACHABLE*: ARP/NDP resolution failed along the path resulting in traffic not getting delivered to the\nintended destination.\n*LOOP*: Traffic entered a forwarding loop.", "enum": [ "DELIVERED", "DELIVERED_TO_INCORRECT_LOCATION", "DROPPED", "LOOP", "INADMISSIBLE", "BLACKHOLE", "UNREACHABLE" ] }, "securityOutcome": { "type": "string", "description": "Specifies whether traffic is denied by ACL rules at any hop along the path.\n*PERMITTED*: All ACLs along the path permitted traffic to flow through.\n*DENIED*: Traffic was dropped by ACLs at some hop along the path. Note that the ACL drop may not always\noccur at the last hop since search results are computed in permit all mode.", "enum": [ "PERMITTED", "DENIED" ] }, "hops": { "type": "array", "items": { "$ref": "#/components/schemas/PathHop" } } } }, "TotalHits": { "type": "object", "properties": { "type": { "type": "string", "description": "Specifies the type of total hits.\n*LOWER_BOUND*: There may be additional hits that were not included in the results either because the\nrequested number of hits were found, or the request timed out.\n*EXACT*: There are exactly this many hits.", "enum": [ "LOWER_BOUND", "EXACT" ] }, "value": { "type": "integer", "format": "int64" } }, "description": "Number of ways in which traffic matching the search criteria is forwarded in the network. Multiple ECMP path\nchoices for traffic lead to separate results. In addition, depending on the scope of query terms, there\nmight be multiple results along a single path. For example a search without IP protocol or destination port\nrestrictions can result in multiple results along a single device path if there are different ACLs that\npermit or deny traffic to different destination ports." }, "PathInfo": { "type": "object", "properties": { "paths": { "type": "array", "items": { "$ref": "#/components/schemas/Path" } }, "totalHits": { "$ref": "#/components/schemas/TotalHits" } } }, "UnrecognizedValues": { "type": "object", "properties": { "appId": { "type": "array", "items": { "type": "string" } }, "userGroupId": { "type": "array", "items": { "type": "string" } }, "userId": { "type": "array", "items": { "type": "string" } } } }, "PathSearchQuery": { "type": "object", "required": [ "dstIp" ], "properties": { "from": { "type": "string", "description": "the device from which the traffic originates. If this is specified, then the srcIp will be considered as a\npacket header only, else, the srcIp will be resolved to specific location(s) and used as the source in the\npath search. Either the source device or srcIp must be specified." }, "srcIp": { "type": "string", "description": "the source IP address or subnet of packets entering the network. For multicast (*, G) paths, set srcIp = G\n(multicast group address).", "examples": [ "10.10.10.10" ] }, "dstIp": { "type": "string", "description": "the destination IP address or subnet of packets entering the network. For multicast (*, G) paths, set dstIp\n= G (multicast group address).", "examples": [ "10.10.10.64/28" ] }, "ipProto": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 255, "description": "the IP protocol", "examples": [ 6 ] }, "srcPort": { "type": "string", "description": "the L4 source port, like \"80\" or a range \"8080-8088\"", "examples": [ "80" ] }, "dstPort": { "type": "string", "description": "the L4 destination port, like \"80\" or a range \"8080-8088\"", "examples": [ "8080-8088" ] }, "icmpType": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 255, "description": "the ICMP type. Implies ipProto = 1." }, "fin": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 1, "description": "the FIN (finish) bit (0 or 1). Implies ipProto = 6.", "examples": [ 1 ] }, "syn": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 1, "description": "the SYN (synchronize) bit (0 or 1). Implies ipProto = 6.", "examples": [ 1 ] }, "rst": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 1, "description": "the RST (reset) bit (0 or 1). Implies ipProto = 6.", "examples": [ 1 ] }, "psh": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 1, "description": "the PSH (push) bit (0 or 1). Implies ipProto = 6.", "examples": [ 1 ] }, "ack": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 1, "description": "the ACK (acknowledgment) bit (0 or 1). Implies ipProto = 6.", "examples": [ 1 ] }, "urg": { "type": "integer", "format": "int32", "minimum": 0, "maximum": 1, "description": "the URG (urgent) bit (0 or 1). Implies ipProto = 6.", "examples": [ 1 ] }, "appId": { "type": "string", "description": "the L7 app-id or \"unidentified\" to exclude paths that traverse firewall policies with app-id matches. If the\nsystem doesn't recognize the provided value, it handles the value the same as \"unidentified\" and includes\nthe value in the `unrecognizedValues` response field. The applications that are recognized by the model can\nbe obtained using GET /api/l7-applications.", "examples": [ "ssh" ] }, "userId": { "type": "string", "description": "the L7 user-id or \"unidentified\" to exclude paths that traverse firewall policies with user-id matches. If\nthe system doesn't recognize the provided value, it handles the value the same as \"unidentified\" and\nincludes the value in the `unrecognizedValues` response field. See [Path Analysis with Layer 7\nUser-Group](https://docs.fwd.app/latest/application/search/path-analysis/layer7_ugroup/) for more info.", "examples": [ "user1" ] }, "userGroupId": { "type": "string", "description": "the L7 user-group-id. If the system doesn't recognize the provided value, the search returns 0 results as\nthere are no paths that traverse firewall policies with that user-group-id match, and the value is included\nin the `unrecognizedValues` response field. See [Path Analysis with Layer 7\nUser-Group](https://docs.fwd.app/latest/application/search/path-analysis/layer7_ugroup/) for more info.", "examples": [ "group1" ] }, "url": { "type": "string", "description": "the L7 URL that traffic of interest is trying to access. Prefix wildcards are supported for subdomains.\nSuffix wildcards are supported for top-level domains and URL paths. See [Path Analysis with Layer 7\nURL](https://docs.fwd.app/latest/application/search/path-analysis/layer7_url/) for more policy patterns supported\nin the model.", "examples": [ "*.example.com" ] } } } }, "parameters": { "SnapshotId": { "name": "snapshotId", "in": "query", "description": "An optional Snapshot id. If omitted, the network’s latest processed Snapshot is used.", "schema": { "type": "string" } } }, "securitySchemes": { "api_token": { "type": "http", "scheme": "basic" } } } }