Troubleshoot the Splunk Add-on for Box

For troubleshooting tips that you can apply to all add-ons, see Troubleshoot add-ons in Splunk Add-ons. For additional resources, see Support and resource links for add-ons in Splunk Add-ons.

Extract the precise location(dest) for the file, folders, and events of the box:Events sourcetype

Some logs do not provide the location of the files and folder, e.g. a file path or a shared URL. Specifically, the logs of the Box:Events sourcetype do not provide such information, by the vendor. That is why the TA assigns the generic value of box.com to the CIM field "dest" for this sourcetype. In this case, if you need the actual, more precise, location (the "dest" CIM field value) for the files and folders, you may run the additional search for the box:file or box:folder sourcetypes, where the precise location of the files and folders can be retrieved, since it is provided by the vendor.

Perform the following search to find the exact location ("dest" field) for the actual location of a particular file/folder. If you don't want to override the existing "dest" field, then provide another field name in the last eval command in the search query.

sourcetype="box:events" (source_item_id=* OR source_folder_id=*) | eval unique_id = coalesce(source_item_id,source_folder_id) | join unique_id [ search (sourcetype="box:fi*" OR sourcetype="box:fo*") | rename id AS unique_id] | eval dest = coalesce(shared_link_url, location) | table unique_id, dest

Configuration troubleshooting

If you think there is something wrong with the configuration, run the following search:

eventtype=box_setup_error

403 or Permission denied errors

If you are seeing 403 Forbidden or "permission denied" errors, first verify that you are using a Box account with sufficient permissions. See step 1 in Configure credentials on Box for the Splunk Add-on for Box for details.

Once you have verified the account permissions are correct, try using a different browser than you usually use to get the developer token. Your browser may be caching the credentials of a different Box account, causing your Box Add-on's token to be granted the permissions of that other account.

Logging verbosity

You can configure the logging verbosity on the setup page for the add-on, or in $SPLUNK_HOME/etc/apps/Splunk_TA_box/local/box.conf. Supported log levels are DEBUG, INFO, and ERROR.

Slow data gathering

By default, the Splunk Add-on for Box collects all folder and file data concurrently. If there are millions of files and folders in your organization's Box account, it may take a long time to finish all of the information gathering. The add-on includes checkpoint functionality which allows the add-on to pick up from where it left off in case Splunk platform restarts during the data collection.

The Box API has rate limiting. Concurrent folder scanning may hit the API's rate limit and throw "rate_limit_exceeded" errors. If this occurs, the add-on throttles the data gathering, which slows the scanning speed.

Rate limit errors

If you see 429 Too Many Requests errors, you are hitting the rate limit imposed by the Box API. For more information, see https://box-content.readme.io/reference#rate-limiting.

Increase your polling interval to 120 seconds or more to avoid this error.

Concurrent vs sequential folder scanning

If you want to do sequential folder scanning instead of concurrent scanning, copy $SPLUNK_HOME/etc/apps/Splunk_TA_box/default/box.conf to your $SPLUNK_HOME/etc/apps/Splunk_TA_box/local folder, then change use_thread_pool = 1 to use_thread_pool = 0. This setting is not exposed in Splunk Web. Sequential scanning is much slower than cocurrent scanning.

Reset checkpoint for historical event data collection

When you enable the Events input for the first time, the add-on collects historical enterprise event data for the past 90 days by default, unless you have configured a different value on the setup page. The add-on collects this data at a maximum rate of 500 records at a time using a collection interval of 120 seconds until it catches up to the present. The historical event collection occurs only the first time that you enable the input. After that, the add-on uses a checkpoint to collect only new events.

You can reset the checkpoint and index historical data again.

1. Stop your Splunk platform instance.
2. Navigate to $SPLUNK_HOME/var/lib/splunk/modinputs/box_service.
3. Remove the events checkpoint file.
4. Modify the created_after in local/inputs.conf to the new historical collection start date that you prefer.
5. Start your Splunk platform instance.

HTTP 400 Bad request: "created_after is invalid since it is in the future"

Because the original timezone is not available in the event metadata, Box events are timestamped using the local timezone of your data collection endpoint. When this local time is not consistent with UTC time, this error may occur. Check that your machine's clock is synced with the world clock.

HTTP 400 Bad request: "created_after is beyond one year in the past"

The Box API currently limits historical event data collection to one year. If you set a date farther in the past than one year ago when you set up the add-on, you encounter this error. The add-on does not collect event data or set a checkpoint, so you can correct the start date to one within one year and restart data collection to recover.

404 errors for file metadata

404 errors are expected because files are frequently created, updated, and deleted in Box, so the resources are not persistent. If you try to access metadata about a file that is no longer there, you receive a 404 error.

OAuth access token and refresh token expiration behavior

The Box OAuth2 access token expires every two hours, so the add-on uses the OAuth2 refresh token to renew the access token automatically when it detects access token expiration. In some cases, the refresh token can itself expire. If this happens, you need to go to the setup page to re-perform the authentication and authorization. This recreates the access token and the refresh token. Search eventtype=box_ta_log_error "Refresh token has expired" to check if the refresh token has expired.

Files with extensions including .boxnote and .zip are not supported for preview mode. Fields such as expiring_embed_link require preview support, and will result in the following error: Box API error returned: Previews for <FileExtension> files are not yet supported. File id <FileID> skipped. Consider adjusting your API field parameters. If you added this field to your box.conf file, remove it. Otherwise, events for these files are not indexed.

Box account configuration error

If you see the following error in the splunkd.log file, an enabled data input is missing Box Account configuration details:
ERROR ExecProcessor - message from "python <SPLUNK_HOME>/etc/apps/Splunk_TA_box/bin/box_service.py" ERRORaccount.

To resolve this error and to resume data collection, correct or complete your Box Account configuration details for your enabled data inputs.

Box events are missed during data collection

If you encounter data gaps while collecting events from your Box account, perform the following troubleshooting steps:

1. Upgrade to the latest version of the Splunk add-on for Box 3.7.0 add-on using the Upgrade the Splunk Add-on for Box topic in this manual.
2. In Splunk Web, navigate to the Inputs tab in the Splunk add-on for Box.
3. Disable the input with "events" endpoint you want to edit.
4. Edit your input with "events" endpoint.
5. Increase the "Interval" time and enter/increase the "Delay" and keep it in the range of 75%-90% of the Interval set.
6. Save the changes.
7. Enable the input.

Delay is getting deducted from "Collect Since Timestamp"

The seconds entered in the Delay field will be deducted from Collect Since Timestamp for the Events endpoint input. This is expected behavior. To resolve this, add the delay you want to Collect Since Timestamp, and configure your input.

For example:

The date you want to enter for Collect Since Timestamp is 2020-08-01T00:00:00 and the Delay you want to enter is 300 seconds. In this case, add the "Delay" to Collect Since Timestamp. For example, enter the date as 2020-08-01T00:05:00 with 300 seconds as Delay. Enter any other values you want, and save the input.
This will get the data from your expected Collect Since Timestamp.

KV Store error when collecting data

If you encounter this error: Error occurred while updating the start_timestamp for the input: xyz:HTTP 503 Service Unavailable -- KV Store is disabled.

You must enable your KV Store service to resume data collection in your ta_box.log.

UI is not loading

UI pages of the add-on are not loading with the following error in the splunkd.log file.

Traceback (most recent call last): File "/opt/splunk/etc/apps/Splunk_TA_box/bin/Splunk_TA_box_rh_box_service.py", line 7, in <module> import import_declare_test File "/opt/splunk/etc/apps/Splunk_TA_box/bin/import_declare_test.py", line 13, in <module> import queue File "/opt/splunk/lib/python3.7/queue.py", line 3, in <module> import threading File "/opt/splunk/lib/python3.7/threading.py", line 8, in <module> from traceback import format_exc as _format_exc File "/opt/splunk/lib/python3.7/traceback.py", line 5, in <module> import linecache File "/opt/splunk/lib/python3.7/linecache.py", line 11, in <module> import tokenize File "/opt/splunk/lib/python3.7/tokenize.py", line 33, in <module> import re File "/opt/splunk/lib/python3.7/re.py", line 145, in <module> class RegexFlag(enum.IntFlag): AttributeError: module 'enum' has no attribute 'IntFlag'

The issue is because of the incorrect library structure due to python2/python3 compatibility. To resolve this issue perform the following steps:

1. Remove the local folder from the add-on directory and place it somewhere accessible.
2. Uninstall the existing add-on and install the latest version of the add-on.
3. Add the local folder back to the add-on directory.
4. Restart the Splunk platform.