Box Shield is an add-on product in Box that is widely adopted by some of our biggest and most security conscious customers. This article will focus on Shield’s unique capabilities and information on how to integrate with the product.
At a high level, Box Shield provides a number of controls within the Box Web Application that prevents sensitive information exposure and threats before they have a chance to happen. With some user or automation driven flows that are based on document classification as well as smart threat detection based on user actions and monitoring, it can help strengthen the security posture of an enterprise.
Box Shield Capabilities
Shield offers many capabilities to our customers, from Classification-driven restrictions, to automatic malware scanning as content is ingested into Box. All of these capabilities can be configured by the Admin of the enterprise to make sure that the policies align with the security posture you are looking to achieve in Box. You can read about the parts of Shield further in our articles on Smart Access, Classification Policies and Shield Lists.
Integrating with Box Shield
Whether you’re a partner that is looking to help with remediation of Shield alerts, scanning and classification of content, or are looking to ingest Shield events and provide a single pane view across applications, Box delivers events that your application can read and act upon.
Classification Integrations
Shield Classification Policies and Smart Access provide a more secure approach to content, where based on the classification of a document, Box can prevent it from being accidentally shared with external parties, prevent users from outside of the company from being invited into the content, and prevent content from being downloaded. While Box provides some Classification capabilities through Classification Policies, many of our customers will choose to use a partner to scan and classify content across their vendors.
In most cases, Classification Settings will be configured by the Admin or relevant teams in the enterprise, but we also provide a number of API based ways to retrieve or add classifications.
As a Classification Partner, you can have our mutual customer connect your application into their Box enterprise through an OAuth flow or through JWT, providing you access to make API calls to retrieve both existing classifications as well as download content for scanning. For creating a Box application basics, please refer to our section on Integrating with Box.
There are a few considerations when looking to integrate classifications and content scanning that relate both to the application permissions as well as the user permissions.
Application Permissions
-
If you are using a JWT based authentication mechanism, you will need to make sure that your application is set up with the following settings:
-
App Access Level: App + Enterprise Access. As you will be performing actions such as downloading content and adding classifications on behalf of enterprise users, you will need to be able to access the named users in the enterprise.
-
Application Scopes: these are the minimum permissions required to be able to get user information, download files, apply classifications, and utilize the Enterprise Event stream to capture user actions.
-
Read all files and folders stored in Box
-
Write all files and folders stored in Box
-
Manage Users
-
Manage Enterprise Properties
-
Advanced Features
-
Issuing the API Call: select either, “Making API calls using the as-user header” or, “Generate user access tokens.” As Box checks permissions based on the user issuing the API call, you will need to impersonate a Box user when downloading content. These settings are the two ways to accomplish this requirement.
-
For OAuth 2.0 based authentication you will need to have the following settings:
-
Application Scopes: these are the minimum permissions required to be able to get user information, download files, apply classifications, and utilize the Enterprise Event stream to capture user actions.
-
Read all files and folders stored in Box
-
Write all files and folders stored in Box
-
Manage Users
-
Manage Enterprise Properties
-
Advanced Features
-
Making API calls using the as-user header
User Permissions
-
For JWT based applications, there is a user that is automatically created during authentication that will mirror your application scopes, so no further work is required.
-
For OAuth 2.0 based application, you need to make sure that the main Admin of the Box enterprise authenticates into the application, or in some cases you may want to have a dedicated Co-Admin level service account for your application. Since Box will take the lower of the permission sets between the Application Scopes and the Co-Admin scopes, the following permissions would need to be enabled
-
Users and Groups: Manage users
-
Files and Folders: View users’ content, Edit users’ content, Log into users’ accounts
-
Reports and Settings: Run new reports and access existing reports
-
Metadata: Create and edit metadata templates for your company
-
Shield: Edit Shield configuration for your company
Note that these are the minimum permissions for a download, scan, classify use case.
Once the connection is established, customers will likely want to have a choice of whether they want to scan and classify existing content, or in some cases they may only want to do this to content moving forward.
In the case of scanning existing content, the application flow will generally follow the following steps:
-
Connection is established between your application and the Box enterprise either through an OAuth process or the Admin adding your JWT application API key in the Apps section
-
Retrieve Current Classifications: Customers will likely want to map Box classifications to policies in your application for classifying content.
-
(Optional) Retrieve Enterprise Users: Customers may want to include or exclude specific users from scanning and classification
-
With the scanning and classification policies set up in your application, and relevant users selected, your application will begin scanning
-
Get List of Users : Retrieve users in the enterprise or defer to the selective list from the customer. Note that you will need the user ids for all of these users.
-
Use the As-User header or User Token to impersonate each user : since you will be walking through the list of users and their content, you will need to impersonate them.
-
Get the Items in the Root Folder for each user: note that each user’s root folder has a special folder id of “0”
-
For each file, Download to Scan: this may be all files, or only some files types, will depend on policies in your application
-
For each folder, Get Items: this will be a full walkthrough of the file and folder structure for each user, so you will need to continue getting items for each subfolder that is found in the scan.
-
(Strongly Suggested) Deduplicate : a single folder may have many collaborators, so you will see the same files for each user that is a collaborator. One strongly suggested method is to only scan files where the user’s collaboration level is “Owner” as there is only one main owner for each folder structure, and that collaboration level will trickle down through the full subfolder structure.
-
Classify Files: once the scan on your side is complete, you will want to classify the files based on the policies the customer established in your app.
To only classify content moving forward, we highly suggest utilizing the Enterprise Event stream, which captures all events in the enterprise. You can scan through the event stream looking for relevant events such as file uploads or new versions of files to see if they need to be classified or reclassified. The “admin_logs_streaming” stream type is most useful for these types of approaches as described here and you can find the API endpoint here. Note that there are a number of useful parameters that you can pass in, such as the “event_type” parameter to only capture relevant event types such as classification changes or file uploads.
Once you are subscribed to the event stream, the rest of the scanning process looks very similar to the steps outlined above. Simply take the file id from the event that you capture, and go through the scanning and classification process.
Logging, Remediation, Event Capture Integrations
Shield can publish a number of Shield Alerts to the Box Enterprise Event Stream that can be of interest to a number of different teams such as security and compliance. These teams often do not work directly form the Box admin interface to monitor these events, but instead rely on systems that automatically ingest events from many sources, and alert on any anomalies. Having a unified view of any potential threat vectors across their application stack in invaluable to be able to act on any threats in a short manner.
For partners looking to integrate with our event stream to monitor for things like Classification changes, or any Shield Alerts, the Box Enterprise Event Stream is the easiest way to ingest this information at scale, as it captures enterprise wide events with a single token.
When looking to integrate with this endpoint note that you will need a minimum set of permissions from both your application perspective and potentially from the user perspective based on the authentication type that your application uses.
Application Permissions
-
If you are using a JWT based authentication mechanism, you will need to make sure that your application is set up with at least the following settings:
-
App Access Level: App + Enterprise Access - you will be capturing events across the whole enterprise.
-
Application Scopes: these are the minimum permissions required to utilize the Enterprise Event stream to capture user actions.
-
Manage Enterprise Properties
-
For OAuth 2.0 based authentication you will need to have the following settings:
-
Application Scopes - these are the minimum permissions required to utilize the Enterprise Event stream to capture user actions.
-
Manage Enterprise Properties
User Permissions
-
For JWT based applications, there is a user that is automatically created during authentication that will mirror your application scopes, so no further work is required.
-
For OAuth 2.0 based application, you need to make sure that the main Admin of the Box enterprise authenticates into the application, or in some cases you may want to have a dedicated Co-Admin level service account for your application. Since Box will take the lower of the permission sets between the Application Scopes and the Co-Admin scopes, the following permissions would need to be enabled
-
Reports and Settings: Run new reports and access existing reports
Note that these are the very minimum permissions needed to capture events from the Enterprise Event stream, if your application plans on doing any remediation steps, capture user information, etc. you may need to include additional scopes. You can learn more about the different scopes here
Integration flow will generally look like the following:
-
Connection is established between your application and the Box enterprise either through an OAuth process or the Admin adding your JWT application API key in the Apps section
-
Get Enterprise Events: depending on whether you are doing a historical scan or like to have the most up to date information delivered as quickly as possible, you may want to use either the “admin_logs” or “admin_logs_streaming” event type.
-
Repeat: If you’re doing a historical scan, you can keep paginating through events until you are at the current date.
At this point, you can choose an interval at which you would like to scan for new events in these endpoints after you’re caught up to real time, and ingesting the event information into your systems. Depending if you’re looking for specific event types for alerting purposes, using the “event_type” filter in your queries to only capture Shield events may be useful to focus on any actionable event types.