Set up analytics data feed

This guide walks you through how to set up and retrieve information using the Analytics data feed policy.

This feature allows you to retrieve data for a large number of devices, without having to directly call the Knox Guard server using the Knox Guard API. You’ll be able to consistently receive large amounts of data, without having to worry about timeouts or system stability.

While you must have Knox Guard Edition devices to use this feature, analytics data is available for all devices in your tenant.

Prerequisites

To use this feature, you must have:

• Knox Guard Edition devices.
• Access to the Knox API Portal. You can apply for access to the Knox API service by contacting your Samsung representative, or by creating a support ticket.
• For sub admins, the appropriate role permissions:
  • Analytics Data Feed
  • Allow access to Knox Cloud APIs portal

How to retrieve data using the analytics data feed

Retrieving analytics data involves five key steps:

1. Generate your Knox Guard client identifier and key pair.
2. Configure your analytics data feed settings on the Knox Guard console.
3. Generate your SFTP access token.
4. Retrieve data using an SFTP call.
5. Decrypt the downloaded files.

Step 1: Generate your Knox Guard client identifier and key pair

Knox Guard uses Knox Cloud Authentication, our legacy authentication scheme. Before you can retrieve or decrypt analytics data, you’ll need to generate your client identifier and key pair from the Knox API Portal. This is the same method you use to generate your REST API key. You’ll use these later on to generate your SFTP access token and decrypt the downloaded reports.

To generate your client identifier and key pair, follow steps 1 — 5 in the Knox Cloud Authentication customer start guide. As a summary:

1. Navigate to the Knox API Portal.
2. On the Download public and private key pair page, download the keys.json file that contains your public and private key pair.
3. On the Client identifiers page, generate your unique client identifier.

Once you have these, you can proceed with configuring your data feed settings.

Step 2: Configure your analytics data feed settings

Next, sign in to the Knox Guard console and define the information you’d like to retrieve. For more information on how to configure these settings and the types of data you can retrieve, see the admin guide.

Once you save your configuration, a success notification containing SFTP Server IP and SFTP Port information displays on the Knox Guard console. Save this — you’ll need these details to connect to the SFTP server in step 4.

It’ll take roughly 24 hours before the first data report is ready for retrieval. After 24 hours, new data is available at the intervals configured using the policy, and is stored for 15 days.

Step 3: Generate your SFTP access token

You can retrieve your data reports using an SFTP call. To connect to the SFTP server, you must provide your username and password. Your username is your Knox Customer ID, and you must obtain your password by generating an access token.

To do this, you must first download the Daas Commands library. You can then use the daas command in any command line interface (CLI) to generate your token. You’ll need these for step 3 and step 5.

• Command line

$ npm init -y
$ npm install -g @samsungknox/daas-cli

Once you’ve installed the library, you can use the daas command to generate your token.

• Command line

daas get-token --keys-file <path-to-keys.json> --client-id <client-id> --access-token-url <api-url>

Your access token expires after its validity time runs out; you must generate a fresh token.

Step 4: Retrieve data using an SFTP call

Once you’ve generated your access token, you can connect to the SFTP server using any CLI or SFTP client.

• Command line

sftp -P <sftp-port> <username>@<sftp-host>

When prompted for your password, enter the access token you generated in step 3. Once the connection is established, you can browse and download your reports as needed.

Every day, two types of files are delivered in your reports: a manifest.json file, and your analytics data, provided as GPG-encrypted CSV files (.csv.gpg).

We recommend you first download the manifest.json file. This file serves as an index for each delivery and lists key information such as the type of data recorded, when the snapshot was generated, files included in this delivery, and when it expires. You can use manifest.json to help identify which files you’d like to download.

Once you’ve downloaded your analytics reports to your local computer, you must decrypt them.

Step 5: Decrypt the downloaded files

The last step is to decrypt the data you’ve downloaded. You can do this with the daas command in any CLI.

• Command line

daas decrypt --keys-file <path-to-keys.json> --encrypted-file <path-to-file.csv.gpg>

Your decrypted CSV file is now ready to use. As new reports are delivered in intervals, repeat steps 3 — 5 each time you want to retrieve the latest data.