Forward Networks API

Forward Networks API v1.3 can help you automate tasks in the Forward Platform and integrate it with other tools. Use cases include:

  • Triggering network Snapshot collection
  • Automating Check and Alias creation/updates
  • Building custom dashboards and alerts
  • Exporting network Snapshots for sharing or archival purposes

If you have any questions or feedback, please contact us at info@forwardnetworks.com. We’d love to hear from you. Enjoy!

HTTP Verbs

This API strives to use appropriate HTTP verbs for each operation.

Verb Description
GET Used for retrieving resources.
HEAD Used for retrieving only the HTTP headers for resources.
POST Used for creating a resource.
PATCH Used for updating resources with partial JSON data. Only fields that have changed need be supplied.
PUT Used for replacing a resource or collection (creating if it doesn’t exist yet).
DELETE Used for deleting resources.

Authentication

This API uses Basic Authentication. This means that a Base64-encoded username + password (or username + API token) is sent in the Authorization header of each request. For security reasons, we recommend always using HTTPS.

API tokens can be generated on the account settings page in the application. They work like passwords in API requests, but API tokens are different from passwords in a few key ways:

  1. API tokens can’t be used to log in.
  2. API tokens are randomly generated and thus harder for attackers to guess than many passwords.
  3. API tokens satisfy the two-factor authentication (2FA) requirement in organizations that use 2FA.
  4. API tokens keep working even if you change your password.
  5. API tokens can be deleted at any time.

If you write a program that uses the API with a fixed set of credentials, consider creating a dedicated user account for that purpose—one that has only the access permissions it needs.

Networks

In this API, a network is a model of a real network. To represent change over time, a network can have Snapshots, each associated with a specific moment in time. Snapshots are constructed by collecting the current configuration and state of every device in the network, inferring the network’s topology, then building a comprehensive behavioral model.

This section is just about listing, creating, renaming and deleting networks. Throughout the API, networks are referenced by their unique identifier, often called networkId. Some endpoints reference a network indirectly using just a unique Snapshot identifier, often called snapshotId.

GET/networks

Lists all networks

 

POST/networks

Creates a network

 

PATCH/networks/{networkId}

Renames a network

 

DELETE/networks/{networkId}

Deletes a network

 

Network Setup

The resources below are for defining a network’s device sources. A device source is fundamentally a hostname or IP address ("host") and port to which the network’s Collector can connect to gather the configuration and state information needed to model one or more network devices.

A device source can include a "type", a "loginCredentialId" for authentication, and optional settings for fine-tuning the collection process. The Collector will attempt to automatically determine the correct device type and login credentials (from those that have been defined) if those fields aren’t specified.

Define any required device credentials and jump servers first, then reference them by id in device sources. A jump server is an intermediate host through which the Collector can be configured to access device sources that it can’t access directly.

Note: Only a Collector stores and uses passwords and private keys. For this reason, device credential and jump server operations require the network’s Collector to be online.

DeviceCredential Types
Type Fields Referencing DeviceSource Field Purpose
LOGIN usernamepassword loginCredentialId SSH or Telnet
PRIVILEGED_MODE password privilegedModePasswordId Cisco or Cisco-like devices
SHELL usernamepassword shellCredentialId Avi controllers
KEY_STORE contentpassword keyStoreId SSL/TLS (currently for OpenFlow switches only)

 

GET/networks/{networkId}/deviceCredentials

Lists a network’s device credentials

 

POST/networks/{networkId}/deviceCredentials

Creates or replaces a network device credential

 

PATCH/networks/{networkId}/deviceCredentials/{credentialId}

Updates a network device credential

 

DELETE/networks/{networkId}/deviceCredentials/{credentialId}

Deletes a network device credential

 

GET/networks/{networkId}/deviceSources

Gets a network’s device sources

 

POST/networks/{networkId}/deviceSources

Creates or updates network device sources

 

PUT/networks/{networkId}/deviceSources/{deviceSourceName}

Creates or replaces a network device source

 

DELETE/networks/{networkId}/deviceSources/{deviceSourceName}

Deletes a network device source

 

GET/networks/{networkId}/jumpServers

Lists a network’s jump servers

 

POST/networks/{networkId}/jumpServers

Creates or replaces a jump server

 

PATCH/networks/{networkId}/jumpServers/{jumpServerId}

Updates a jump server

 

DELETE/networks/{networkId}/jumpServers/{jumpServerId}

Deletes a jump server

 

Network Collection

Use these resources to query the state of a network’s Collector, to trigger a collection of configuration and state from a network’s devices, or to cancel an in-progress collection. The application offers additional Collector configuration options, such as defining a collection schedule.

POST/networks/{networkId}/cancelcollection

Cancels an in-progress network collection

 

GET/networks/{networkId}/collector/status

Gets the status of a network’s collector

 

POST/networks/{networkId}/startcollection

Triggers a network collection

 

Network Snapshots

Once a network Snapshot has been collected, the Forward Platform processes it to build a model and to compute the results of any Checks defined in the network. Snapshot processing time is typically just a few seconds, but varies by network size and complexity and by available computing power.

The resources in this section are for listing Snapshots, exporting or importing a Snapshot as a .zip file, and deleting Snapshots.

GET/networks/{networkId}/snapshots

Lists all Snapshots

 

POST/networks/{networkId}/snapshots

Imports a Snapshot

 

GET/networks/{networkId}/snapshots/latestProcessed

Returns the latest processed Snapshot

 

GET/snapshots/{snapshotId}

Exports a Snapshot

 

DELETE/snapshots/{snapshotId}

Deletes a Snapshot

 

Network Snapshot Data Files

Sometimes it’s useful to access the raw data that the Forward Platform collected from a device. The resources in this section are for listing and downloading these data files.

GET/snapshots/{snapshotId}/devices/{deviceName}/files

Lists a device’s data files

 

Network Topology

A network’s topology influences the behavior of the network model and how automatic network layout works. The Forward Platform determines what device links to include in its network model using 1) automatic discovery using collected LLDP/CDP information, 2) automatic inference based on the MAC addresses devices have learned, and 3) any user-defined link overrides, which have the highest precedence.

The resources in this section are for listing all of a network’s device links and for listing and defining link overrides. An override is bidirectional and either "present" (the link exists) or "absent" (the link doesn’t exist).

PUT/networks/{networkId}/topology

Sets the topology overrides

 

GET/snapshots/{snapshotId}/topology

Gets the network topology

 

GET/snapshots/{snapshotId}/topology/overrides

Gets the topology overrides

 

POST/snapshots/{snapshotId}/topology/overrides

Edits the topology overrides

 

PUT/snapshots/{snapshotId}/topology/overrides

Sets the topology overrides

 

Network Layout

The resources in this section are for accessing and updating the network layout, which is represented as (x, y) coordinates for all devices and their hosts. In the application, the layout coordinate system is oriented such that the positive x-axis points to the right and the positive y-axis points down. The location of the origin is unimportant. The distance unit should be roughly the length of the shortest link in the diagram. Scale is somewhat important, since it can affect how large the application renders network nodes and labels.

GET/networks/{networkId}/layout

Gets the network layout

 

POST/networks/{networkId}/layout

Updates the network layout

 

GET/snapshots/{snapshotId}/layout

Gets the network layout

 

PUT/snapshots/{snapshotId}/layout

Updates the network layout

 

Path Search

These APIs take description(s) of packets at network ingress as input, trace the packets through the network and return the corresponding paths. Search results are computed in permit all mode, which traces traffic past any ACL drops to determine downstream behavior.

Aliases

An Alias is a flexible way to group infrastructure elements (like network devices, interfaces, and end hosts) or packet header values (like VLAN IDs, IP addresses, and L4 ports). Aliases simplify the definition of policy checks and help when searching the network.

Here are some examples of Alias definitions in JSON.

Alias Type JSON Notes
Devices
{
  "name": "tor_switches",
  "type": "DEVICES",
  "values": ["dc?-tor*", "tor-*"]
}
The "values" are device names and/or name patterns containing glob wildcards (e.g. *?[abc][0‑9]).
Interfaces
{
  "name": "vlan_20_access",
  "type": "INTERFACES",
  "values": ["SF-ACC-0-8 et[12]"]
}
The "values" are device interface names and/or name patterns. Each name or pattern must contain exactly one space, which separates the device name part from the interface name part.
{
  "name": "vlan_20_to_29_access",
  "type": "INTERFACES",
  "vlanIds": ["20-29"],
  "vlanIntfTypes": ["ACCESS"]
}
It can be convenient to define a set of device interfaces using a set of VLAN IDs. "vlanIntfTypes" can be ["TRUNK"]["ACCESS"] or omitted (for both). If "values" is also present, it further restricts the set of matching interfaces.
Hosts
{
  "name": "web_servers",
  "type": "HOSTS",
  "values": ["10.30.1.0/24"],
  "locations": ["tor_switches"]
}
The "values" are host names, IP subnets and/or MAC addresses. The "locations" are device or interface names or aliases. At least one of "locations" and "values" must be specified.
Header Values
{
  "name": "VOIP",
  "type": "HEADERS",
  "values": {
    "eth_type": ["0x800"],
    "ip_proto": ["UDP"],
    "tp_port": ["10000", "20000"]
  }
}
Supported header types are:

  • mac_addr – MAC addresses
  • eth_type – Ethernet types
  • vlan_vid – VLAN IDs/ranges
  • ip_addr – IP addresses/blocks
  • ip_proto – IP protocols
  • tp_port – L4 ports/ranges

At least one type must be specified.

The resources below are for reading, creating, updating and deleting the Aliases associated with a network Snapshot. Changes to a Snapshot’s Aliases propagate forward to later Snapshots, including future Snapshots.

Checks

Checks verify network policy and behavior. They cover security, reachability, fault tolerance, and compliance and can help network operators prevent regressions and confirm that desired end-to-end behavior holds as the network evolves.

There are 5 main types of checks:

  • Existence verifies that specific traffic is allowed between one or more points within the network.
  • Isolation verifies that specific traffic is prohibited between one or more points within the network.
  • Reachability verifies that specific traffic gets delivered to its intended destination.
  • Predefined checks are a library of common checks which apply to typical network designs.
  • NQEBETA (Network Query Engine) checks are custom queries for consistency or policy violations.

Here are some examples of check definitions in JSON.

Type Check JSON Notes
Existence

Traffic matches:

from web_servers
status dropped
{
  "checkType": "Existential",
  "filters": {
    "from": {
      "location": {
        "type": "HostAliasFilter",
        "value": "web_servers"
      }
    },
    "flowTypes": ["DROPPED"]
  },
  "noiseTypes": []
}
Supported flowTypes values are:

  • VALID – delivered
  • LOOP – ended in a loop
  • BLACKHOLE – dropped, no matching rule
  • DROPPED – dropped by a rule
  • INADMISSIBLE – dropped at edge of network
  • UNREACHABLE – failed ARP resolution

If present, the flowTypes array must contain exactly one value.

The noiseTypes field is required.

Traffic matches:

from admin_servers
with L4 Dest Porthttp
and IP Dest10.1.0.0/16
and notVLAN ID3007
through BB-1
ingress 1-FWALL-1
with L4 Dest Porthttp
to web_servers
status delivered
{
  "checkType": "Existential",
  "filters": {
    "from": {
      "location": {
        "type": "SubnetLocationFilter",
        "value": "10.1.40.215"
      },
      "headers": [
        {
          "type": "PacketFilter",
          "values": {
            "ipv4_dst": ["10.1.0.0/16"]
          }
        },
        {
          "type": "NotFilter",
          "clause": {
            "type": "PacketFilter",
            "values": {
              "vlan_vid": ["3007"]
            }
          }
        }
      ]
    },
    "chain": [
      {
        "transitType": "ingress",
        "location": {
          "type": "InterfaceFilter",
          "values": ["BB-1 ge-0/0/3"]
        }
      },
      {
        "transitType": "through",
        "location": {
          "type": "DeviceFilter",
          "values": ["1-FWALL-1"]
        },
        "headers": [
          {
            "type": "PacketAliasFilter",
            "value": "http",
            "direction": "dst"
          }
        ]
      }
    ],
    "to": {
      "location": {
        "type": "HostAliasFilter",
        "value": "web_servers"
      }
    },
    "flowTypes": ["VALID"]
  },
  "noiseTypes": []
}
The location filter types are:

  • SubnetLocationFilter
    – value: an IP address or subnet
  • HostFilter
    – values: an array containing one host or Edge Node name, IP address, subnet, or MAC address
  • DeviceFilter
    – values: an array containing one device name
  • InterfaceFilter
    – values: an array containing one interface name, qualified with its device name
  • VrfFilter
    – values: an array containing one VRF name, optionally qualified with a device name
  • HostAliasFilter
    – value: a HOSTS Alias name
  • DeviceAliasFilter
    – value: a DEVICES Alias name
  • InterfaceAliasFilter
    – value: an INTERFACES Alias name

The header filter types are:

  • PacketFilter
    – values: an object mapping one header field type to an array containing one header value
  • PacketAliasFilter
    – value: a HEADERS Alias name
    – direction: either src or dst

The most common header field types are:

  • ipv4_src / ipv4_dst
  • ipv6_src / ipv6_dst
  • mac_src / mac_dst
  • tp_src / tp_dst
  • eth_type
  • vlan_vid
  • ip_proto

NotFilter can wrap a filter to negate it.

Each object in chain must specify a transitType of throughingress, or egress.

SubnetLocationFilterHostFilter, and HostAliasFilter are not permitted in the chain array.

Isolation

No traffic matches:

from internet
to db_servers
status delivered
{
  "checkType": "Isolation",
  "filters": {
    "from": {
      "location": {
        "type": "InterfaceAliasFilter",
        "value": "internet"
      }
    },
    "to": {
      "location": {
        "type": "HostAliasFilter",
        "value": "db_servers"
      }
    },
    "flowTypes": ["VALID"]
  },
  "noiseTypes": []
}
Isolation check JSON has the same shape and constraints as Existence check JSON.
Reachability

All traffic is delivered
to destination:

from web_servers
with L4 Dest PortMySQL
to db_servers
{
  "checkType": "Reachability",
  "filters": {
    "from": {
      "location": {
        "type": "HostAliasFilter",
        "value": "web_servers"
      },
      "headers": [
        {
          "type": "PacketAliasFilter",
          "value": "MySQL",
          "direction": "dst"
        }
      ]
    },
    "to": {
      "location": {
        "type": "HostAliasFilter",
        "value": "db_servers"
      }
    },
  },
  "noiseTypes": []
}
Reachability check JSON differs from Existence check JSON in a few ways:

  1. from is required.
  2. to is optional and cannot specify header values.
  3. chain is not permitted.
  4. flowTypes is not permitted.
  5. NotFilter is not permitted.

If to is specified, the check verifies that all traffic matching the rest of the query get delivered to the location(s) in the to clause.

If to is not specified, the check verifies that all traffic matching the query gets delivered out of any edge port; none gets dropped or blackholed or enters into a forwarding loop.

Predefined

VLAN Consistency

VLANs should be
consistently defined on
interfaces on either side
of each link in the network.

{
  "checkType": "Predefined",
  "predefinedCheckType": "VLAN_CONSISTENCY"
}
A Predefined check is either on or off for a Snapshot, so a Snapshot should never have more than one check with the same predefinedCheckType.

VLAN Existence

Edge trunk interfaces
must carry all specified
VLANs.

{
  "checkType": "Predefined",
  "predefinedCheckType": "VLAN_EXISTENCE",
  "params": {
    "interfaces": [
      "SF-ACC-0-0 et3",
      "SF-ACC-0-0 et4",
      "SF-ACC-0-1 et3",
      "SF-ACC-0-1 et4"
    ],
    "vlans": ["20-24", "31"]
  }
}
Each Predefined check type accepts different parameters in the params object. A table below lists them all.
NQEBETA

Find every interface whose admin status is up but operational status is not up.

{
  "checkType": "NQE",
  "name": "interface status consistency",
  "query": "
    foreach device in network.devices
    foreach i in device.interfaces
    where i.adminStatus == AdminStatus.UP
       && i.operStatus != OperStatus.UP
    select {
      deviceName: device.name,
      interfaceName: i.name,
      adminStatus: i.adminStatus,
      operStatus: i.operStatus
    }"
}
This check iterates through all interfaces on all devices and returns the device name and interface name for each interface whose admin status is UP but operational status is not UP. The check passes if the network has no such interfaces.

For more information about NQE checks and help writing queries, see the Documentation, Data Model, and Examples panes in the application’s NQE check editor.

The table below describes the parameters of each Predefined check type.

Predefined Check Type Parameters
NO_LOOP "noiseTypes": string[]
HOSTNAME_UNIQUENESS "ignoredKeys": string[]
BGP_ROUTE_CONSISTENCY "ignoredDevicePairs": [string, string][]
BGP_NEXT_HOP_REACHABILITY "ignoredKeys": string[]
BGP_NEIGHBOR_ADJACENCY "ignoredKeys": string[]
BGP_ROUTER_ID "ignoredKeys": string[]
EBGP_SELECTION_OVER_IBGP "ignoredKeys": string[]
FHRP_PEERING "ignoredKeys": string[]
DUPLEX_CONSISTENCY "ignoredLinks": string[][]
IP_UNIQUENESS "ignoredIpAddresses": string[]
LINK_SPEED_CONSISTENCY "ignoredLinks": string[][]
MTU_CONSISTENCY "ignoredLinks": string[][]
PORT_CHANNEL_CONSISTENCY "ignoreDownInterfaces": boolean
"internalPortsOnly": boolean
"ignoredLinks": string[][]
"ignoredPortChannels": string[]
SHORTEST_PATH "deviceGroups": string[][]
"noiseTypes": string[]
TRUNK_INTERFACE_WHITELIST "interfaces": string[]
"ignoredKeys": string[]
VLAN_EXISTENCE "interfaces": string[]
"vlans": string[]
"ignoredKeys": string[]
VLAN_CONSISTENCY "checkNativeVlans": boolean
"ignoredLinks": string[][]
BGP_VPC_PARAMETER_CONSISTENCY "ignoreASNs": boolean
"ignoreCommunityLists": boolean
"ignoredKeys": string[]
BGP_COMMUNITY_LIST "patterns": [string, string][]
"ignoredKeys": string[]
LEARNED_MAC_CONSISTENCY "ignoredKeys": string[]
HOSTNAME_CONSISTENCY "pattern": string
"ignoredDevices": string[]
SOFTWARE_VERSION_CONSISTENCY "checkDiscoveredPeers": boolean
"deviceGroups": string[]
"ignoredDeviceGroups": string[]
"ignoredDeviceSets": string[][]
VPC_PARAMETER_CONSISTENCY "ignoredDevicePairs": [string, string][]
VPC_INTERFACE_PARAMETER_CONSISTENCY "ignoredDevicePairs": [string, string][]
VPC_MST_REGION_CONSISTENCY "ignoredDevicePairs": [string, string][]
VPC_DEDICATED_KEEPALIVE_LINK "checkDedicatedVrf": boolean
"ignoredDevicePairs": [string, string][]
VPC_ROLE_PRIORITY "primaryPriority": integer
"secondaryPriority": integer
"ignoredDevicePairs": [string, string][]
VPC_STP_PRIORITY "ignoredDevicePairs": [string, string][]
SSH_RSA_KEY_LENGTH "minKeyLength": integer
"ignoredDevices": string[]

When a new check is added to a Snapshot, its result is immediately evaluated for that Snapshot. Check creation and deletion propagate forward to later Snapshots of the network, just like Aliases.

GET/snapshots/{snapshotId}/checks

Gets all checks (with status)

 

Parameters

Name Description
snapshotId *
string
(path)
snapshotId

Responses

Code Description
200
OK
[
  {
    "creationDateMillis": "2020-04-21T22:45:02.126Z",
    "definition": {
      "checkType": "Isolation"
    },
    "description": "string",
    "id": "string",
    "name": "string",
    "status": "NONE"
  }
]
409

The system is currently processing this Snapshot.

Note: GET /networks/{networkId}/snapshots/latestProcessed can be used to determine when processing of the latest Snapshot is done or to identify an alternate Snapshot that has already been processed.

{
  "apiUrl": "string",
  "httpMethod": "GET",
  "message": "string",
  "reason": {}
}

POST/snapshots/{snapshotId}/checks

Adds a check

 

DELETE/snapshots/{snapshotId}/checks

Deactivates all checks

 

GET/snapshots/{snapshotId}/checks/{checkId}

Gets a check (with status)

 

DELETE/snapshots/{snapshotId}/checks/{checkId}

Deactivates a check

 

GET/snapshots/{snapshotId}/predefinedChecks

Gets available predefined checks