Skip to main content
Sumo Logic

Collect Events for Box

This page provides instructions for setting up event collection from Box for analysis in Sumo Logic. Click a link to jump to a topic:

Log types

The Sumo Logic App for Box collects Box events, which are described in detail in the Box documentation.

Requirements and process overview

Before you begin setting up log collection, review the required prerequisites and process overview described in the following sections.

Prerequisites

  • Before you can collect events for the Sumo Logic App for Box, you must have a co-admin Box user with the  Run new reports and access existing reports permission. 
  • The integration between Sumo and Box requires relies upon SumoJanus, described below. The system where you deploy SumoJanus and configure your installed collector and script source must have Java.

Process Overview

Setting up event collection from Box for analysis in Sumo Logic includes the following tasks, which must be performed in the order in which they are presented.

  1. Download the SumoJanus packages necessary for authentication.
  2. Deploy the SumJanus package on a local server running the Sumo Logic Collector..
  3. Edit the local properties file with the Okta token created in step 1. The Properties file will be generated in step 2 when you download and deploy the SumoJanus package.
  4. Configure an Installed Collector and
  5. Configure a Script Source in Sumo Logic to send the data from Okta to Sumo Logic.

Configuring Box event collection

This section walks you through the process of setting up log collection from Box for analysis in Sumo Logic. Click a link to jump to a topic.

Step 1: Download the SumoJanus packages 

The following SumoJanus files are required to collect logs from Box. SumoJanus is a proprietary library used for script-based collection from applications such as Okta, Box, and Salesforce.

The SumoJanus v3.0.0 package file:

The Box bundle package for SumoJanus:

Step 2: Deploy the SumoJanus packages

The deployment steps vary, depending on whether or not you have set up the SumoJanus package previously. 

If you have never set up SumoJanus
  1. Copy the two package files you downloaded to the same folder, then unzip them there.
    • On Linux, run the following commands:

      tar xzvf sumojanus-dist.3.0.0.tar.gz
      tar xzvf sumojanus-box-3.0.0-box.tar.gz

    • On Windows, use Windows Explorer to open the packages.

After you unzip the package files, there should be a folder called sumojanus, with all of the files from both packages, like this:
box-sumojanus.png

If you have previously set up SumoJanus
  1. Back up conf/sumologic.properties.
  2. Copy the file sumojanus-3.0.0-box.tar.gz (or sumojanus-box-3.0.0.zip)to the parent folder where SumoJanus is currently installed. (So this folder should contain the folder sumojanus.)
  3. Unzip the file:

    • On Linux, unzip sumojanus-3.0.0-box.tar.gz using the following command:

      tar xzvf sumojanus-3.0.0-box.tar.gz

    • On Windows, use Windows Explorer to unzip sumojanus-box-3.0.0.zip

This will copy the files from the Box package to the sumojanus folder.

Step 3: Edit the properties file

  1. Open the sumojanus/conf/sumologic.properties file in a text editor and add the following lines:

    [boxcollector]
    token_path = ${path}/data/box_enc.token
    stream_pos_path = ${path}/data/box_stream_position.dat
    # optional, default is admin event
    #event_type = admin
    # optional, encrypt token file or not. Default is false
    encrypt_token_file = true
    # Optional, Overwrite default encryption key
    # encryption_key =
    # optional, startTime to query for Event Log files, in epoch milliseconds, optional, default is 2 days back.
    #startTime = 1435709058000
    # optional, endTime to query for Event Log files, in epoch milliseconds
    #endTime = 1436377600000
  2. Save your changes.

Step 4: Authenticate Box

As part of authentication, the script will open and listen to port 8080. It will also create a token file under the sumojanus/data folder. Before you begin, make sure the local firewall settings and file permissions allow these operations. On Windows machines, you may need to create a firewall exception rule to allow port 8080 to be opened. Also on Windows machines, use a different browser than Internet Explorer (e.g Chrome or Firefox) for the authentication procedure.

  1. If you are currently logged in to your Box account, log out.
  2. From the sumojanus folder, run:
    • For Linux: bin/SumoJanus_Box.bash -s
    • For Windows: bin\SumoJanus_Box.bat -s
  3. If Box presents a Disabled by Administrator message, follow the steps below to grant access to the Sumo app, and then re-run the script.
    1. Log in to Box and select Admin Console at the top of the screen.
    2. Go to Enterprise Settings or Business Settings and click on Apps.
    3. In the Custom Applications section, choose Authorize New App.authorize-new-app.jpg 
    4. In the App Authorization window, enter the Client ID for the Sumo app, nzjjxne0gqax07n4u5idwj7i8ravboqv, in the API Key field, and click Next.
      app-authorization.png
    5. On the next page, in the Report and Settings row, checkmark the Run new reports and access existing reports option, and save your changes.
      box-privileges.png 
    6. Repeat Step 2 (re-run the script).
  4. The script opens the browser. Log in to Box and click Authorize.
  5. Once Authorized, the app will be enabled within your Developer enterprise.
     box_authorize_564x354.png
  6. To grant access to all requested permissions, click Grant access to Box.box_grant_access_566x376.png
  7. Your browser will display the message:  "This site can't be reached". 
    Edit the URL for the page to change the protocol from "https" to "http" then hit enter. 
  8. Once permissions are granted, the script saves the access token to a local file—the default location is ${path}/data or ./data. Verify that the file is actually created. If not, repeat the authentication steps. box_token_620x35.png
  9. The path to this token file is configured in the file conf/sumologic.properties, under the property token_path.

  10. (Optional) Test the script manually before you deploy it to production. To do so, go to the sumojanus folder and run the following command:

    bin\SumoJanus_Box.bash

You should now see Box events collected printed out. Once you see them, close the CLI (Windows) or shell (Linux) to kill the running script (by default it runs for 30 minutes).

Step 5: Deploy the configuration on your production system 

The steps for deploying the configuration to production vary, depending on whether or not SuperJanus 3.0 is already deployed to production.

If you do not have SumoJanus 3.0 on the production system

Copy the whole sumojanus folder to your production system where you set up the Sumo collector. We recommend putting this folder under the Collector folder.

Make sure the collector has write permission to this folder, as the script will need to write locally on a regular basis.

If you already have SumoJanus 3.0 on the production system 

If you are using SumoJanus 3.0 on the target box as part of another script collection, Salesforce for example, the folder sumojanus already exists on your system. Do the following:

  1. Back up the file conf/sumologic.properties.
  2. Copy only the configuration section of conf/sumologic.properties to the target box. (This is the section you edited earlier.)
  3. Unzip only the bundle package sumojanus-3.0.0-box.tar.gz to the sumojanus folder.
  4. Copy the token file just generated to sumojanus/data.

Step 6: Configure a Collector

Configure an installed collector. Linux and Windows are supported.

Step 7: Configure a source

For guidance creating your source category naming convention, see Best Practices: Good Source Category, Bad Source Category.

  1. Configure a script source.
    script-source-box.png
  2. Configure the source fields:
    1. Name. (Required) BoxCollector. (Description is optional.)
    2. Source Category. (Required) box
    3. Frequency (Required) Every 5 Minutes
    4. Specify a timeout for your command: Active the checkbox and select 60 Minutes
    5. Command (Required) /bin/bash (specify the correct path on your system)
    6. Script (Required) Use the path to sumojanus that you created in the Production Deployment step, such as /home/ubuntu/sumojanus/bin/SumoJanus_Box.bash. (Do not select “Type the script to execute.”)
    7. Working Directory. /home/ubuntu/sumojanus
  3. Click Save.

Sample log messages

{
   "source": {
      "type": "user",
      "id": "225980941",
      "name": "First Last",
      "login": "user@sumologic.com"
   },
   "created_by": {
      "type": "user",
      "id": "225980941",
      "name": "First Last",
      "login": "user@sumologic.com"
   },
   "created_at": "2016-12-15T11:08:58-08:00",
   "event_id": "7988d00a-aca3-4454-9021-652477f4fa78",
   "event_type": "LOGIN",
   "ip_address": "1.1.1.1",
   "type": "event",
   "session_id": null,
   "additional_details": null
}

{
   "source": {
      "type": "user",
      "id": "262207389",
      "name": "user",
      "login": "luser@sumologic.com"
   },
   "created_by": {
      "type": "user",
      "id": "225980941",
      "name": "first last",
      "login": "user1@sumologic.com"
   },
   "created_at": "2016-12-14T16:09:33-08:00",
   "event_id": "d82f1946-2c51-43fe-bfcc-3452f9e2f6ff",
   "event_type": "DELETE_USER",
   "ip_address": "1.1.1.1",
   "type": "event",
   "session_id": null,
   "additional_details": null
}

Query sample

Top 10 Failed Logins

_sourceCategory=box  type "event_type" login
| json "created_at","ip_address","event_type","created_by.name","created_by.login" as messagetime,src_ip,event_type, src_user,src_login nodrop
| json "source.name","source.login","source.type"  as dest_user,dest_login, item_type nodrop
| where event_type="FAILED_LOGIN" 
| count as EventCount by src_user,src_login,src_ip | top 10 src_user,src_login,src_ip by EventCount