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

  • You must have Admin or Co-Admin Box user permissions. See Step 5: Authenticate Box Prerequisites for more information. 
  • The integration between Sumo and Box requires the SumoJanus configuration, 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. Configure an Installed Collector.
  2. Download the SumoJanus for Box package necessary for authentication.
  3. Deploy the SumoJanus for Box package on the local server that is running the Sumo Logic Collector.
  4. Edit the local properties file. The Properties file will be generated in step 2 when you download and deploy the SumoJanus package.
  5. Authenticate Box.
  6. Configure a source to send the data 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. 

Step 1: Configure a Collector

If you don't already have an installed collector, set one up now. Linux and Windows are supported.

Step 2: Download the SumoJanus for Box package 

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

SumoJanus for Box v3.0.0 package file:

Step 3: Deploy the SumoJanus for Box package

In this task, you copy the package file to the folder where it will be deployed and then unpack the contents.

  1. Copy the downloaded package file to the location where it will be deployed.
  2. Unpack the contents of the file in that location, in one of the following ways:
  • On Linux, run the following command:
tar xzvf sumojanus-box-dist.3.0.0.tar.gz
  • On Windows, you can use Windows Explorer to open the package and copy it to the target folder.

After you unpack the file, there should be a folder called sumojanus-box that contains files like this:

Box_sumojanux-box_folder.png

Step 4: Edit the properties file

In this task, you modify the properties file.

  1. Open the sumojanus-box/conf/sumologic.properties file in an ASCII text editor. 

  2. 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
    
  3. Save your changes.

Step 5: Authenticate Box

This section shows you how to set up authentication.

Prerequisites
  • You must have Admin or Co-Admin role permissions to perform this procedure. A Co-Admin user only needs “Runs new report and access existing reports” privilege (under “Reports and Settings” section, as shown in the following image).

box-privileges.png

  • You need an internet-connected computer with a web browser. We recommended that you use a Chrome or Firefox browser for the authentication procedure, not Internet Explorer (IE).
  • As part of authentication, the script opens and listens to port 8080. It also creates a token file under the sumojanus-box/data folder. 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.
  • Verify the current JRE folder the collector is using by going to the collector folder under config/wrapper.conf, and looking for the wrapper.java.command variable.

To authenticate Box, do the following: 

  1. Set the JAVAPATH variable. Review the main script (bin/SumoJanus_Box.bash for Linux or bin/SumoJanus_Box.bat for Windows) for the full path of the java.exe file and verify or modify the JAVAPATH variable, as shown in the following example: 
JAVAPATH=”/usr/local/SumoCollector/jre1.8.0_172/bin/“
  1. If you are logged in to your Box account, log out.
  2. From the sumojanus-box folder, open a terminal window and run one of the following commands:
    • For Linux: bin/SumoJanus_Box.bash -s
    • For Windows: bin\SumoJanus_Box.bat -s
  3. If Box presents a Disabled by Administrator message, follow these steps to grant access to the Sumo app, then re-run the script.
    1. Go to Enterprise Settings or Business Settings and click Apps.
    2. Scroll to the Invididual Application Controls section, search for SumoLogic, and select Available for the app SumoLogic_BoxCollector
    3. Repeat Step 3 (re-run the script). The script opens a browser window.
  1. When the script opens the browser, provide your Box email password and click Authorize. Once Authorized, the app is enabled within your Developer enterprise. NOTE: If the SumoJanus script does not open a browser, it prints a URL in the terminal window that you can copy and paste into a browser to open the window.

Box_collection_Login-page-Box.png

  1. To grant access to all requested permissions, click Grant access to Box. 

.box_grant_access_566x376.png

Your browser will display the message:  "This site can't be reached." This is expected.

  1. Copy the URL from the browser, change the protocol from "https" to "http" then use one of the following options ON THE SAME MACHINE where the script is running (in case your browser is actually on a different machine):
    • For Linux, open a terminal window and run: curl -X GET ‘the above url’
    • For Windows, open a Powershell window and run: Invoke-WebRequest ‘the above url’  -Method Get

If everything was successful, you should see the message “Thank you for granting access for SumoLogic BoxCollector” somewhere in the return value. If you see an error regarding an expired authorization code instead, make sure you finish this step within 30 seconds of the previous step as noted above.

  1. 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 was created. If not, repeat the authentication steps. 

    On some Windows machines, the SumoJanus folder has “Read only” permission by default. Make sure you allow Write permission.
  1. (Optional) Test the script manually by going to the sumojanus-box folder and running one of the following commands:

For Linux systems, run this command: 

bin/SumoJanus_Box.bash

For Windows systems, run this command:

bin\SumoJanus_Box.bat 

You should now see a list of results of collected Box events. 

  1. Close the CLI (Windows) or shell (Linux) window to kill the running script. By default it runs for 30 minutes.

Step 6: Configure a Source

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

To configure a source, do the following:

  1. Configure a Script Source. New Collectors using version 19.245-4 and later do not allow the creation of Script Sources by default. To allow Script Sources you need to set the Collector parameter enableScriptSource in user.properties to true.

    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, such as: /home/ubuntu/sumojanus-box/bin/SumoJanus_Box.bash 
      (Do not select “Type the script to execute.”)
    7. Working Directory. /home/ubuntu/sumojanus-box
  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