Box.com
Copy link

ℹ️

Page updated for EA release

We’re introducing cloud collection for the Box.com event source, now available in Early Access (EA).

Box.com is a cloud storage service for enterprises. You can configure a Box.com event source for an enterprise subscription only, not for an individual or business subscription.

Box.com uses Open Authentication (OAuth) to authorize SIEM (InsightIDR) to collect activity logs from their servers. In order to read Box.com logs, the collector needs to be able to connect to https://api.box.com .

In the Box.com integration, SIEM (InsightIDR) polls on a regular basis for the following information:

  • Box.com “users” to map them back to domain users and tie ActiveDirectory and Box.com activity together
  • Recent Box.com “events” to pull authentication and administrative activity

In SIEM (InsightIDR), you will see:

  • Ingress activity to Box.com on your “Locations” map as if the users were logging into your internal network
  • Admin activity on your “Administrators” page (typically account change activity—new account created, account deleted, etc)
  • Users who are seen doing Admin activity get a “Box admin” tag in SIEM (InsightIDR)
  • Several incidents might get generated:
  • Ingress from disabled account (the user is no longer part of the company but still logging into Box.com)
  • Harvested credentials
  • Multiple country authentications
  • Ingress from threat
  • Third-party alert activity from Box Shield alerts

If you are running SIEM (InsightIDR) in Firefox, be sure to enable pop-up windows before configuring a Box.com event source.

To set up Box.com:

  1. Read the requirements and complete ant prerequisite steps.
  2. Configure the event source to send data to SIEM (InsightIDR).
  3. Configure SIEM (InsightIDR) to collect data from the event source.

You can also:

Requirements
Copy link

Before you configure the Box.com event source, you must have:

  • Access to the Box Developer Console
  • A Box administrator available to approve the application

Configure the event source to send data to SIEM (InsightIDR)
Copy link

To configure Box.com to send data to SIEM (InsightIDR) you must create and authorize a Box platform app and enable alert publishing to successfully ingest Box Shield alerts.

ℹ️

Visit the third-party vendor's documentation

For the most accurate information on configuring this event source, we recommend that you visit Box’s documentation on creating a platform app , platform app approval , and enabling alert publishing .

Create a Box platform app
Copy link

Set up a Box platform app and authorize it to access your enterprise data. This process generates the credentials required for log ingestion.

To create a Box platform app:

  1. In Box, go to the Developer Console.
  2. Click Create Platform App.
  3. Provide a name for your app.
  4. Select Client Credentials Grant as the App Type.
  5. Click Create App.
  6. Open the Configuration tab.
  7. Set App Access Level to App + Enterprise Access.
  8. Configure the following permissions:
    • Content Actions
      • Read all files and folders stored in Box
    • Administrative Actions
      • Manage users
      • Manage enterprise properties
    • Developer Actions
      • Manage webhooks
  9. Click Save changes.

To obtain the client ID, client secret and Enterprise ID:

  1. In the Configuration tab, record:
    • Client ID
    • Client Secret
  2. In the General Settings tab, record:
    • Enterprise ID

You will need these values when configuring the event source in SIEM (InsightIDR). Store these credentials securely.

To submit the authorization request:

  1. Go to the Authorization tab.
  2. Click Review and Submit.

This will send a notification and email to your company’s Box Admin.

A Box administrator must approve and enable the app before it can send data to SIEM (InsightIDR).

Option 1: Approve from email:

  1. Open the approval email from Box.
  2. Click Review App Details.
  3. Review the requested permissions.
  4. Select the appropriate enablement options.
  5. Click Apply.

Option 2: Approve from the Box Admin Console:

  1. Open the Admin Console in Box.
  2. Go to Integrations.
  3. Select Platform Apps Manager.
  4. Click Server Authentication Apps.
  5. Locate the application and click View.
  6. Review the authorization and enablement settings.
  7. Click Apply.

Enable alert publishing
Copy link

If you are configuring the Box.com event source in SIEM (insightIDR), you must enable alert publishing  in Box.com to successfully ingest Box Shield alerts into SIEM (InsightIDR).

To do this, you must select Publish Alert to Box Event Stream when you create or edit a Shield detection rule in Box.com. Read Box.com’s documentation on how to create, edit and delete a Threat Detection Rule  to learn how to navigate to Detection Rules in the Box.com admin console and enable Publish Alert to Box Event Stream for new and existing rules.

If you already have Shield detection rules configured, review each rule and confirm that Publish Alert to Box Event Stream is enabled. You may need to recreate rules that were originally created without this option selected. SIEM (InsightIDR) cannot retroactively collect Shield alerts that were not published to the Event Stream.

Configure SIEM (InsightIDR) to collect data from the event source
Copy link

After you complete the prerequisite steps and configure the event source to send data, you must add the event source in SIEM (InsightIDR).

Task 1: Select Box.com
Copy link

  1. From the left menu, go to Data Collection and click Setup Event Source > Add Event Source.
  2. Do one of the following:
    • Search for Box.com in the event sources search bar.
    • In the Product Type filter, select Cloud Service.
  3. Select the Box.com event source tile.

Task 2: Set up your collection method
Copy link

There are two methods of collecting data from Box.com: through a cloud connection or through a collector.

Use the Cloud Connection method

  1. In the Add Event Source panel, select Run On Cloud.
  2. Name the event source. This will be the name of the log that contains the event data in Log Search.
  3. Click Add a New Connection.
  4. In the Create a Cloud Connection screen, enter a name for the new connection.
  5. In the Enterprise ID field, enter the enterprise ID that you obtained in the requirements.
  6. In the Client ID field, enter the client ID that you obtained in the requirements.
  7. In the Client Secret field, enter the client secret that you obtained in the requirements.
  8. Click Save & Test Connection.
  9. Optionally, select the option to send unparsed data.
  10. Select your Account Attribution preference:
    • Use short name attribution: The system first attempts to attribute data by email address, for example, jsmith@myorg.example.com. If the first attempt is unsuccessful, attribution is attempted by short name, for example, jsmith. If the short name is unsuccessful, attribution is attempted by a user’s first and last name, for example, John Smith.
    • Use fully qualified domain name attribution: The system first attempts to attribute data by email address, for example, jsmith@myorg.example.com. If the first attempt is unsuccessful, attribution is attempted by a user’s first and last name, for example, John Smith. This option is best if your environment has collisions with short names.
  11. Optionally, specify the Active Directory Domain for Multi-domain Environments.
  12. Select an attribution source.
  13. Click Save.

Use the Collector method

  1. In the Add Event Source panel, select Run On Collector.
  2. Enter the name of your event source.
  3. Select your collector.
  4. Select Box.com API from the Collection Method dropdown.
  5. Click Begin to set up OAUTH and start the authorization process.
  6. A new window or tab will open for you to perform an authorization grant with Box.
  7. Login to Box.com and click Allow.
  8. Close the window/tab to return to SIEM (InsightIDR).
  9. Optionally choose to send unparsed logs.
  10. Select an attribution source.
  11. Configure your default domain and any Advanced Event Source Settings.
  12. Click Save.

Connect apps to Box.com
Copy link

Applications use OAuth, an open source authentication standard, to connect to Box. There are also Box SDKs that include implementations of the OAuth2 grants used by Box, or client libraries available in a number of languages that you might find useful.

Read this link for more information: https://developer.box.com/reference#oauth-2-overview .

Troubleshooting
Copy link

If you experience issues with Box.com, refer to these steps to troubleshoot.

Error: App Disabled by Administrator
Copy link

If you attempt to connect SIEM (InsightIDR) to Box.com but encounter an error message, you may need to allowlist SIEM (InsightIDR) as an application.

How to allowlist SIEM (InsightIDR) in Box.com
Copy link

Follow these instructions to allowlist SIEM (InsightIDR) in Box.com: https://support.box.com/hc/en-us/articles/360044195053-Disabled-by-Administrator-Cannot-Use-Application#:~:text=access%20the%20integration.-,Platform%20Apps,-If%20the%20app 

You will be asked to enter a Client ID that is specific to your AWS region. Use the following table to identify the correct Client ID based on the AWS region your environment is hosted in.

To find your AWS region:

  • Multi-org users: Open the Org Switcher in the top-left corner of the Command Platform navigation bar. From the dropdown, locate your current organization. The AWS region for that organization is displayed next to the organization name.

  • Single-org users: Ask your Platform Administrator to provide your AWS region.

AWS RegionClient ID
ap-northeast-1jagp21q41s40x5bvo5larljhnjwphdj6
ap-southeast-2y0bdup7juwzqtoyda0axbmhsnt087m32
ca-central-1esik4v7swbos3c19zyydw9o7rgzaz79q
eu-central-1crtn5kpjd9zc2vl28avyptne9oif42r5
us-east-1uqsuj6rhwxz7ia3ucjrn8xb0px4l84i8
us-east-2agws64mbmu46mme9kymvcmkdivwqvk18
us-west-2234xyq68h81iinhxpise7ccyuhmb7cks