BOX Integration Setup Guide

This guide will walk you through setting up BOX audit logs integration with RunReveal. The BOX source collects audit logs from your BOX Enterprise account, including user access, file operations, administrative changes, and security events.

Overview

• Source Type: box
• Ingest Method: API Polling (every 60 seconds)
• Data Collected: BOX admin logs and audit events

Prerequisites

• BOX Enterprise account with admin access
• BOX Developer Console access

Step 1: Create a BOX Application

1.1 Access BOX Developer Console

1. Go to the BOX Developer Console
2. Sign in with your BOX Enterprise admin account
3. Click “Create New App”

1.2 Configure Application Settings

1. Choose App Type: Select “Custom App”
2. Authentication Method: Select “OAuth 2.0 with JWT (Server Authentication)”
3. App Name: Enter a descriptive name (e.g., “RunReveal Audit Logs”)
4. Description: Add a description for your app

1.3 Configure OAuth Settings

1. In the “OAuth 2.0 Credentials” section:
   • Redirect URI: Add https://your-runreveal-domain.com/oauth/box/callback (replace with your actual RunReveal domain)
   • Scopes: Select the following scopes:
     • admin_logs - Read admin logs
     • manage_enterprise - Manage enterprise settings (if needed)

1.4 Generate Application Keys

1. Go to the “Configuration” tab

2. In the “Application Access” section:

   • Select “Enterprise” (for enterprise-wide access)

3. In the “Advanced Features” section:

   • Enable “Perform Actions as Users” (if needed)
   • Enable “Generate User Access Tokens” (if needed)

4. Save your configuration

1.5 Get Application Credentials

1. Go to the “General” tab
2. Copy the following values:
   • Client ID (you’ll need this for RunReveal configuration)
   • Client Secret (you’ll need this for RunReveal configuration)

Step 2: Authorize the Application

2.1 Enterprise Authorization

1. In your BOX Developer Console, go to your app
2. Click “Authorize” in the top right
3. Sign in with your BOX Enterprise admin account
4. Grant the requested permissions
5. Important: Copy the Refresh Token that appears after authorization (you’ll need this for RunReveal)

2.2 Alternative: Manual Authorization

If the automatic authorization doesn’t work, you can manually authorize:

1. Construct the authorization URL:

   https://app.box.com/api/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&state=random_string

2. Replace:

   • YOUR_CLIENT_ID with your actual Client ID
   • YOUR_REDIRECT_URI with your configured redirect URI
   • random_string with a random string for security

3. Visit the URL in your browser

4. Sign in and authorize the application

5. You’ll be redirected to your redirect URI with an authorization code

6. Exchange the code for tokens using the BOX API

Step 3: Configure RunReveal

3.1 Create BOX Source in RunReveal

1. Log into your RunReveal dashboard
2. Navigate to Sources → Add Source
3. Select “BOX” from the source list
4. Choose “Polling” as the ingest type

3.2 Configure Source Settings

Fill in the following fields:

Settings:

• Unique ID: Enter a unique identifier for this source (e.g., box-enterprise-001)
• Client ID: Enter the Client ID from your BOX application

Secrets:

• Client Secret: Enter the Client Secret from your BOX application
• Refresh Token: Enter the Refresh Token obtained during authorization

3.3 Test the Configuration

1. Click “Verify Settings” to test the connection
2. If successful, you should see a green checkmark
3. If there are errors, check:
   • Client ID and Client Secret are correct
   • Refresh Token is valid and not expired
   • Your BOX application has the correct permissions
   • Your BOX Enterprise account has admin logs enabled

Step 4: Enable Admin Logs in BOX

4.1 Verify Admin Logs are Enabled

1. Log into your BOX Enterprise admin console
2. Go to Admin Console → Reports → Audit Logs
3. Ensure “Admin Logs” are enabled for your enterprise
4. If not enabled, contact your BOX administrator to enable them

4.2 Configure Log Retention

1. In the BOX Admin Console, go to Admin Console → Reports → Audit Logs
2. Set the appropriate retention period for your compliance needs
3. Ensure logs are being generated (you should see recent activity)

Step 5: Monitor and Verify

5.1 Check Data Ingestion

1. After saving your BOX source, wait 5-10 minutes
2. Go to Logs in your RunReveal dashboard
3. Filter by Source Type: box
4. You should see BOX audit events appearing

5.2 Verify Event Types

The BOX integration collects the following types of events:

• User login/logout events
• File access and sharing events
• Administrative changes
• Security events
• Application access events

5.3 Check for Errors

1. Go to Sources → Errors in RunReveal
2. Look for any BOX-related errors
3. Common issues:
   • Invalid credentials
   • Expired refresh token
   • Insufficient permissions
   • Rate limiting

Troubleshooting

Common Issues

”Invalid Client ID or Secret”

• Verify the Client ID and Client Secret are correct
• Ensure there are no extra spaces or characters
• Check that the application is properly configured in BOX

”Invalid Refresh Token”

• The refresh token may have expired
• Re-authorize the application in BOX Developer Console
• Generate a new refresh token

”Insufficient Permissions”

• Ensure your BOX application has the admin_logs scope
• Verify your BOX account has admin access
• Check that admin logs are enabled in your BOX Enterprise

”No Events Found”

• Verify admin logs are enabled in BOX
• Check that there’s recent activity in your BOX account
• Ensure the source has been running for at least 10-15 minutes

Rate Limiting

• BOX API has rate limits (typically 100 requests per minute)
• RunReveal polls every 60 seconds, which should be within limits
• If you hit rate limits, contact BOX support to increase your limits

Support and Resources

BOX Documentation

• BOX Developer Documentation
• BOX Events API Reference
• BOX OAuth 2.0 Guide

BOX Support

• BOX Developer Support
• BOX Enterprise Support

This guide covers the complete setup process for BOX integration with RunReveal. For additional support or questions, please contact RunReveal support or refer to the official documentation.