Using the REST API, a summary of the devices directly connected to the firewall can be retrieved. This has similarities with a listing of the ARP cache but provides extra information about each device. The device information is sent back by cOS Core in JSON format. This same information can also be retrieved by using the neighborcache CLI command with various command options.

Sending the Neighbor Cache Request

To retrieve the neighbor cache information, an HTTP GET should be sent to the following URI:

/api/oper/neighbor_devices

The GET has no optional parameters.

The Statistics Retrieved

The following is a list of the possible values sent back in the JSON reply:

When one of the above values is indicated as optional, this indicates that the value will not be present if it is either unavailable or not relevant.

The ethernet_object is the name of the first EthernetAddress object found in the cOS Core address book that has a MAC address matching the MAC address of the external device. If no such object is found then the value will not be included in the JSON reply. The EthernetAddress object will have to be first created manually by the administrator with the relevant MAC address.

The hostname value may be included in the JSON reply if the external device was allocated its IP address by cOS Core acting as a DHCP server. The hostname will be the name sent by the external device in its DHCP request for an IP address. If it did not send a name in the request the hostname value will not be included.

An Example JSON Reply

Below is an example of a typical JSON reply:

{
  "error": false,
  "devices": [
    {
      "interface": "wan",
      "ethernet_address": "00-50-8B-D9-16-5E",
      "ethernet_vendor": "Clavister",
      "ipv4": "203.0.113.6",
      "status": "Active"
    },
    {
      "interface": "dmz",
      "ethernet_address": "F8-B2-53-CF-2B-CD",
      "ethernet_object": "my-pc",
      "ethernet_vendor": "Example Corp.",
      "ipv4": "10.6.19.1",
      "status": "Inactive",
      "last_seen": 2
    }
  ]
}