Introduction

This API 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

Each API section below includes an OpenAPI specification that can be used to generate client SDKs to help speed up integration. If you use several API sections, you might prefer using a single spec:

• Forward Networks OpenAPI spec (includes all sections)

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

Change Policy

The Forward Networks API is designed to be stable and reliable. We understand the importance of these qualities. At the same time, we aim to continually improve the API and deliver new functionality. To these ends, we’ve adopted this change policy:

• Non-breaking changes are common and are introduced without advance notice. Non-breaking changes include:
  • Adding a new API operation
  • Adding an optional new query parameter to a request
  • Adding an optional new JSON property in a request
  • Adding a new JSON property in a response
  • Adding a new possible value for a JSON property in a request or response
• Breaking changes are rare and avoided if at all possible. When one is deemed necessary, a breaking change will be announced in the API Release Notes at least three (3) releases (approx. 3 months) in advance. The announcement will include instructions for minimizing the impact of the change. The affected API operations, parameters, and properties will be marked as deprecated in this document during the 3 releases of advance notice. We also make every effort to identify customers who will be affected and personally and proactively notify them. Breaking changes include:
  • Removing an API operation
  • Removing a JSON property from a response
  • Requiring a query parameter or JSON property in a request

Authentication

This API uses Basic authentication. This means that a Base64-encoded credential pair is sent in the Authorization header of each request, as in Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=. Common tools and libraries such as curl, Requests, and Axios can format this header. A Linux shell can also Base64-encode: echo -n username:password | base64.

API tokens (access key + secret key) are the preferred credential type for API requests. Traditional credentials (username + password) are also accepted for most account types, but not for SSO (SAML) accounts. You can generate API tokens in the application on the account settings page. API tokens are different from traditional credentials in a few key ways:

1. API tokens can’t be used to log in.
2. API tokens are longer than most passwords and are created using a cryptographically strong random number generator to protect against brute-force password-guessing attacks.
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.

To avoid sending credentials unencrypted through the network, use HTTPS.

HTTP Verbs

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

HTTP Status Codes

This API uses standard HTTP status codes. Each operation’s documentation identifies the status code that it uses to indicate success (typically 200 OK or 204 No Content) and any notable client (4xx) error codes that it might return.

An error response’s body is an ErrorInfo JSON object whose message property describes the problem. Some 4xx error codes that can occur for nearly every API operation are listed below.

Current Version

The API’s current version is the Forward Platform’s current release version: …. The resource below simply returns the release version and build number.

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.

Network Setup

The resources below are for defining a network’s devices and other collection sources. A classic device 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 the network device.

A classic device can include a "type", one or more credential IDs for authentication, and optional settings for fine-tuning the collection process. The Collector will attempt to automatically determine the correct device type and 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 classic devices. A jump server is an intermediate host through which the Collector can be configured to access devices 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.

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, to define collection schedules, or to cancel an in-progress 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.

Network Devices

Use these resources to retrieve basic information about the devices in a network Snapshot or to access the raw data (configuration and state) files that the Forward Platform collected from a device.

The last operation below lists devices that are apparently missing from the network Snapshot—neighbors of modeled devices that can be added to the network using the Network Setup API.

Synthetic Devices

The Forward Platform models network connectivity between customer edge devices via user-defined synthetic devices. These include an internet node, intranet nodes, L2 VPNs, L3 VPNs, WAN circuits, and encryptors.

The resources in this section are for defining, updating, and retrieving a network’s synthetic devices. Changes to a network’s synthetic devices affect future Snapshots.

Network Topology

A network’s topology influences the behavior of the network model and how automatic network layout works in the application. 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).

Network Locations

Each network has 1) a list of user-defined locations at which devices can be represented in network diagrams and 2) an atlas, which can map each device to a user-defined location. Additionally, devices at the same user-defined location can be grouped into device clusters to declutter the network diagram.

The system automatically assigns cloud (AWS/GCP/Azure) devices to predefined cloud locations. All other devices can be assigned to user-defined locations via the atlas. Devices that have no location assigned appear in the default (“Unassigned”) location.

When creating or updating a user-defined location, you can choose its id (like "sjc-01b") or allow the system to generate a numeric one (like "56"). A user-chosen location identifier:

• must not exceed 16 characters,
• must contain only letters, digits, and hyphens,
• must begin with a letter,
• must not end with a hyphen or have consecutive hyphens,
• must be unique, ignoring case (to avoid confusion), and
• must be different from the names of other location, ignoring case (to avoid confusion).

This section includes:

• operations for listing, creating, updating, and deleting user-defined locations,
• operations for retrieving and updating the atlas of device location assignments, and
• operations for defining and managing device clusters.

Device Tags

A network can include a list of user-defined device tags. These tags can be associated with devices and/or endpoints as metadata. Tags can be used in NQE queries and to filter devices in various workflows in the application. A device tag can also be assigned a color to make it easier to identify its associated devices in network diagrams.

This section includes operations for listing and managing device tags. It includes operations for adding, removing, and replacing all tags for network devices and endpoints.

Note: The following operations from other sections (Network Setup and Network Devices) can include device tags in their responses if specifically requested:

• GET /api/networks/{networkId}/classic-devices?with=tags
• GET /api/networks/{networkId}/classic-devices/{deviceName}?with=tags
• GET /api/networks/{networkId}/devices?with=tags
• GET /api/networks/{networkId}/devices/{deviceName}?with=tags

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 criteria
• maxResults : Limits the number of results returned by the API, after applying ranking criteria
• intent : Specifies a preference for paths where traffic gets delivered vs. those with reachability violations such as drops, blackholes, or loops.

Given a query and search criteria, the path search workflow is as follows.

Starting with all flows in the network:

1. Filter using packet criteria (srcIp, dstIp, ipProto, srcPort, dstPort, icmpType)
2. Sort (intent) - preference for delivered or undelivered paths
3. Limit (maxCandidates)
4. Compute forwarding and security outcomes
5. Filter (intent) - optional step limiting results to undelivered flows when intent = VIOLATIONS_ONLY
6. 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.
7. Limit (maxResults)
8. Compute network functions - optional step, only if requested
9. 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, and 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.

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.

{
  "name": "tor_switches",
  "type": "DEVICES",
  "values": ["dc?-tor*", "tor-*"]
}

{
  "name": "vlan_20_access",
  "type": "INTERFACES",
  "values": ["SF-ACC-0-8 et[12]"]
}

{
  "name": "vlan_20_to_29_access",
  "type": "INTERFACES",
  "vlanIds": ["20-29"],
  "vlanIntfTypes": ["ACCESS"]
}

{
  "name": "web_servers",
  "type": "HOSTS",
  "values": ["10.30.1.0/24"],
  "locations": ["tor_switches"]
}

{
  "name": "VOIP",
  "type": "HEADERS",
  "values": {
    "eth_type": ["0x800"],
    "ip_proto": ["UDP"],
    "tp_port": ["10000", "20000"]
  }
}

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:

• NQE (Network Query Engine) checks are a library of common or custom queries for consistency or policy violations.
• Predefined checks are a library of common checks which apply to typical network designs.
• 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.

Here are some examples of check definitions in JSON.

{
  "checkType": "NQE",
  "queryId": "FQ_6ac3682c92a74b778d98584aea8afa5fe40f2150",
  "commitId": "ee6efd2c0a53e30d9549db86dea523fa5d07f60d"
}

{
  "checkType": "Predefined",
  "predefinedCheckType": "VLAN_CONSISTENCY"
}

{
  "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"]
  }
}

{
  "checkType": "Existential",
  "filters": {
    "from": {
      "location": {
        "type": "HostAliasFilter",
        "value": "web_servers"
      }
    },
    "flowTypes": ["DROPPED"]
  }
}

{
  "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",
          "value": "BB-1 ge-0/0/3"
        }
      },
      {
        "transitType": "through",
        "location": {
          "type": "DeviceFilter",
          "value": "1-FWALL-1"
        },
        "headers": [
          {
            "type": "PacketAliasFilter",
            "value": "http",
            "direction": "dst"
          }
        ]
      }
    ],
    "to": {
      "location": {
        "type": "HostAliasFilter",
        "value": "web_servers"
      }
    },
    "flowTypes": ["VALID"]
  }
}

{
  "checkType": "Isolation",
  "filters": {
    "from": {
      "location": {
        "type": "InterfaceAliasFilter",
        "value": "internet"
      }
    },
    "to": {
      "location": {
        "type": "HostAliasFilter",
        "value": "db_servers"
      }
    },
    "flowTypes": ["VALID"]
  }
}

{
 "checkType": "Reachability",
  "filters": {
    "from": {
      "location": {
        "type": "HostAliasFilter",
        "value": "web_servers"
      },
      "headers": [
        {
          "type": "PacketAliasFilter",
          "value": "MySQL",
          "direction": "dst"
        }
      ]
    },
    "to": {
      "location": {
        "type": "HostAliasFilter",
        "value": "db_servers"
      }
    }
  }
}

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

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.

NQE

Network Query Engine (NQE) enables you to query for information about your network. For more information about NQE queries and for help writing queries, see the NQE tutorial or the Data Model pane in the application’s NQE query editor.

The NQE API allows you to run NQE queries on a network Snapshot. You may also filter and order the results by providing a QueryOptions object.

Vulnerability Analysis

Operating system and application-level vulnerabilities are regularly discovered on all kinds of network devices. The operations in this section can help network operators identify impacted devices and update them to mitigate the vunerabilities.

User Accounts

The operations in this section require the Org Admin role.

System Administration

The operations in this section require the Org Admin role. Importing a new CVE index (CVE database) is for on‑premises Forward Enterprise deployments only.

The CVE index defines all security vulnerabilities that the Forward Platform analyzes.