The Perygee hub is an executable program deployed as a Docker container that aggregates network traffic before uploading to the Perygee platform. The aggregation centers around pairs of communicating networked devices which enables automated local device discovery and analysis of traffic patterns including protocols, data volume, and the communicating devices.
Creating a hub
First, navigate to the hubs page by clicking on “More” on the left-side panel, and then clicking “Hubs” to view the list of your current hubs.
From there, click the “New hub” button in the top right. This will prompt for a name for the new
hub. Enter a name and click the “Create” button. This will create the new hub and open the hub
detail view.
Create a hub access token
In order for a hub on your network to communicate with the Perygee platform to retrieve its
configuration and upload aggregated network traffic data, it will need an access token. These access
tokens are used to authenticate to the platform and should be handled sensitively, just like a
password.
First, navigate to the hub detail view which opens by default if you’re creating a new hub or by selecting an existing hub from the admin console. Then click the “New access token” button on the far right which will prompt for a name for the access token. Enter the name and click the “Create” button. This will bring up a new dialog including the actual access token and the shell commands to start a Docker container running the hub with the new access token. IMPORTANT: This is the only time you will be able to see the access token value, so record it appropriately. Once the access token value has been recorded, close the dialog.
Installing a hub on your network
On a device that is connected to replicated network traffic for analysis, the hub can be started with:
docker run \
--cap-add=NET_RAW \
--cap-add=NET_ADMIN \
--network=host \
--restart=unless-stopped \
-e API_URL={{PERYGEE-API-BASE-URL}} \
-e HUB_SECRET={{HUB-ACCESS-TOKEN}} \
perygee/hub
The {{PERYGEE-API-BASE-URL}} and {{HUB-ACCESS-TOKEN}} placeholders will need to be updated accordingly.
A physical hardware appliance can be provided by Perygee to host the hub Docker container. Contact Perygee for more information.
Configuring a hub
By default, a new hub has a minimal configuration that will not monitor any traffic and thus will
not produce any aggregated network traffic data or discovered devices. However, once a hub is
installed and running on your network (with its access token), it will periodically upload a report.
This is one way to know that the hub is running successfully. One of the key sections of each
report is the “networkInterfaces”. From this section, you can identify the interface name/s and the
subnet/s from which to analyze data.
In the left-side panel, select “More” then “Hubs” to retrieve a list of all hubs and then click on the specific hub to edit. The “Latest Hub
Report” is shown at the bottom of the view. The current “Hub Configuration” is shown just above the
“Latest Hub Report”. To edit the configuration, click the “Edit Hub Configuration” button on the far
right which will open a modal with guided configuration options. Once the desired settings are updated, click the “Save” button on the bottom of the modal.