BOX Audit Logs

RunReveal can pull audit events from the Box Events API every 60 seconds for real-time detection.

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

To read events from the entire enterprise account, the Box user performing the following steps must have full admin privileges on the account (not co-admin).

For security and availability reasons, we recommend creating a new Box App solely for RunReveal.

Step 1: Create a Box Source in RunReveal

1.1 Start Source Creation

1. Log into your RunReveal dashboard
2. Navigate to Sources → Add Source
3. Search for “Box”, then click its tile
4. On the slide-out panel, click Start Setup
5. On the next screen, enter a memorable name for the source (e.g., “My Box logs”)
6. Click Setup

1.2 Get Redirect URL

On the Credentials page, there are two steps:

1. Use the redirect URL below in your Box App settings (there is a URL displayed on this page)
2. Fill in the credentials below (Client ID and Client Secret)

Important: Before you continue the setup process in your RunReveal dashboard, you must create a new app in your Box Developer Console and retrieve the Client ID and Client Secret. Click Copy under Step 1 to copy your redirect URL - you’ll need this in the next step.

Step 2: Create a Box Application

2.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”

2.2 Configure Application Settings

1. Choose App Type: Select “Custom App”
2. Authentication Method: Select “User Authentication (OAuth 2.0)”
3. App Name: Enter a memorable name for your app (e.g., “RunReveal”)
4. Click “Create App”

2.3 Configure OAuth Settings

1. In your new app’s Configuration tab, scroll down to the OAuth 2.0 Redirect URI section
2. Paste the redirect URL you copied from your RunReveal dashboard
3. In the Application Scopes section, make sure Manage enterprise properties is selected (it is not selected by default)
4. Click Save Changes

2.4 Get Application Credentials

1. In the Configuration tab, scroll down to the OAuth 2.0 Credentials section
2. Copy the following values:
   • Client ID (you’ll need this for RunReveal configuration)
   • Client Secret (you’ll need this for RunReveal configuration)

Step 3: Configure Box Source in RunReveal

3.1 Enter Credentials

1. Return to the Credentials page in your RunReveal dashboard
2. Paste the Client ID and Client Secret credentials you copied from the Box Developer Console
3. Click Setup

3.2 Complete OAuth Authorization

1. Click Grant Access
2. You will be redirected to Box
3. Click Grant Access to Box
4. You will be redirected back to RunReveal

You will be directed to a success screen confirming that RunReveal will now automatically pull and process logs from your account.

You can optionally enable one or more Detection Packs.

The Trigger an alert when no events are processed setting defaults to YES. We recommend leaving this enabled, as you will be alerted if data stops flowing from the log source after a certain period of time. The timeframe is configurable, with a default of 24 hours.

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

1. “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
• Verify you’re using the credentials from the correct Box app

2. “Invalid Refresh Token”

• The refresh token may have expired
• Re-authorize the application by completing the OAuth flow again
• If issues persist, try creating a new Box app and starting the setup process again

3. “Insufficient Permissions”

• Ensure your Box application has Manage enterprise properties scope selected
• Verify your Box account has full admin privileges (not co-admin)
• Check that admin logs are enabled in your Box Enterprise account

4. “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
• Wait a few minutes after setup for the first events to appear

5. OAuth Authorization Issues

• Ensure the redirect URL in Box matches exactly what RunReveal provided
• Verify you completed the OAuth flow by clicking “Grant Access to Box”
• Check that the redirect URL was copied correctly without any extra characters

Support and Resources

Box Documentation

• Box Developer Documentation
• Box Events API Reference
• Box OAuth 2.0 Guide
• Box Admin Logs 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.