Custom Application

Name the application of traffic to a given host, protocol and port

A custom application entry maps traffic to a host address, IP protocol and port onto an application name of your choice. Flows matching an entry are recorded with that application name instead of the detected one. Entries are stored on the device and pushed to the traffic analysis service whenever they change.

API

• Data (CUSTOM_APPLICATION object):

  {
      "id": 1,
      "host": {
          "host_type": "ip",
          "host_value": "192.0.2.10"
      },
      "protocol": 6,
      "port": 9000,
      "application": "clickhouse"
  }

  • id - unsigned integer assigned by the device; used to address the entry; ignored in POST
  • host - the host the traffic belongs to
    • host_type - always ip
    • host_value - IPv4 or IPv6 address
  • protocol - IP protocol number, for example 6 for TCP or 17 for UDP
  • port - TCP or UDP port
  • application - the application name to record

  All fields except id are mandatory when adding an entry. The combination of host, protocol and port must be unique.

• Get all entries

  • Path: /api/cmm/applications
  • Method: GET
  • Minimum user role: viewer
  • Response on success (200 OK): array of CUSTOM_APPLICATION objects in data

• Get one entry

  • Path: /api/cmm/applications/{id}
  • Method: GET
  • Minimum user role: viewer
  • Response on success (200 OK): CUSTOM_APPLICATION object in data
  • Response on failure (404 Not Found): {"message": "Failed to fetch custom application entry with id = <id>: entry is not found", "data": null}

• Add entries

  • Path: /api/cmm/applications
  • Method: POST
  • Minimum user role: operator
  • Request body: array of CUSTOM_APPLICATION objects without id
  • Response on success (200 OK): the created entries with their id in data
  • Response on failure:
    • 400 Bad Request, Failed to add new custom application entries: invalid format of payload when the body is not an array, a mandatory field is missing or host_type is not ip
    • 400 Bad Request, Failed to add new custom application entries: some entries are not unique when two entries of the request are equal
    • 409 Conflict, Failed to add new custom application entries: entry already exists: [...] when an entry with the same host, protocol and port is stored already

• Edit entries

  • Path: /api/cmm/applications
  • Method: PUT
  • Minimum user role: operator
  • Request body: array of objects with a mandatory id and the fields to change; fields that are omitted keep their value
  • Response on success (200 OK): the changed entries in data. An entry whose values did not change is neither updated nor returned, so the array may be empty.
  • Response on failure:
    • 404 Not Found, Failed to update custom application entries: entry with id = <id> does not exist
    • 400 Bad Request, Failed to update custom application entries: entry with id = <id> is duplicated by another entry with the same id in the request
    • 400 Bad Request, ... becomes non-unique after the modification when the change would create two equal entries

• Delete one entry

  • Path: /api/cmm/applications/{id}
  • Method: DELETE
  • Minimum user role: operator
  • Response on success (200 OK): {"message": "The custom application entry with id = <id> has been removed successfully", "data": null}
  • Response on failure (404 Not Found): {"message": "Failed to remove custom application entry with id = <id>: entry is not found", "data": null}

• Delete all entries

  • Path: /api/cmm/applications
  • Method: DELETE
  • Minimum user role: operator
  • Response on success (200 OK): {"message": "Successfully removed all custom application entries", "data": null}; succeeds also when the list is empty

Back to Index