Skip to main content
Box Shield must be purchased and enabled on a Box enterprise to take advantage of the advanced security offerings outlined below.

​
Threat detection alerts

Shield threat detection delivers context-rich alerts on potential threats, such as compromised accounts and data theft, based on anomalous user behavior. The possible alerts produced by Shield are for:
  1. Suspicious locations
  2. Suspicious sessions
  3. Anomalous downloads
  4. Malicious content
  5. Ransomware activity (part of Shield Pro)
All Shield threat detection alert events are produced within the stream. These events follow the standard event object schema and the event_type value is set to SHIELD_ALERT.
The additional_details object provides information about the specific type of shield alert that triggered the event.

​
Alert severity and identifiers

Every shield_alert object includes the following fields that describe the strength of the detected threat and identify the alert:
The priority field is no longer included in Shield alert events. Use severity instead. Alert IDs are unique random alphanumeric strings. Store them as strings, not numbers, and don’t rely on alert IDs being sequential.

​
Suspicious locations alert

A suspicious locations alert is produced when Shield detects a user accessing content from an unusual, excluded geographic location, or ‘host’ IP address. It can be identified by the Suspicious Locations value within additional_details.shield_alert.rule_category. The additional_details payload will provide the following details:

​
Suspicious sessions alert

A suspicious sessions alert is produced when Shield detects a user accessing content in a session characterized by unusual user-agent strings, unusual IDs, uncommon types of applications, new IP addresses, and an improbably rapid change in the person’s log-in location. It can be identified by the Suspicious Sessions value within additional_details.shield_alert.rule_category. The additional_details payload will provide the following details:

​
Anomalous download alert

An anomalous download alert is produced when Shield detects an account holder who may be stealing sensitive content. It can be identified by the Anomalous Download value within additional_details.shield_alert.rule_category. The Anomalous Download rule can trigger an alert in two ways. The contents of alert_summary depend on which one triggered the alert:
  • Anomaly detection: Shield machine learning detects download behavior that is unusual compared to the user’s history.
  • Threshold breach: download activity exceeds a threshold limit configured in the rule, such as a number of files or a download volume within a time window.

​
Anomaly detection

For alerts triggered by anomaly detection, the additional_details payload provides the following details:

​
Threshold breach

For alerts triggered by a threshold breach, alert_summary contains a threshold_breach object instead of the anomaly detection fields. It doesn’t include description, download_delta_size, download_delta_percent, historical_period, or anomaly_period.
The alert_summary object for a threshold breach contains the following fields:
  • threshold_breach.metric: the threshold type that was exceeded, for example DOWNLOAD_BYTES for download volume.
  • threshold_breach.threshold: the threshold limit configured in the rule.
  • threshold_breach.observed_value: the download activity that exceeded the limit.
  • threshold_breach.window_hours: the rule’s time window, in hours.
  • activity_period: the start and end of the download activity, with the total download size and number of files downloaded.
  • download_ips: the IP addresses the downloads came from.
  • download_services: the services used for the downloads, for example Box Web App.

​
Malicious content alert

A malicious content alert is produced when Shield detects potential malware in content uploading to an account. It can be identified by the Malicious Content value within additional_details.shield_alert.rule_category. The additional_details payload will provide the following details:

​
Ransomware activity alert

A ransomware activity alert is produced when Box Shield identifies suspicious file extensions that may be indicative of a ransomware attack. It can be identified by the Ransomware Activity value within additional_details.shield_alert.rule_category. The additional_details payload will provide the following details:
For the Ransomware Activity alert, the rule_response_action object reflects the automated response action taken by Box Shield when the alert was created. The terminate_sessions field indicates whether Box Shield initiated a request to terminate all active sessions of a managed user:
  • true — the Terminate Target User Sessions rule setting was enabled, so Box Shield initiated a request to terminate all active sessions of a managed user when the alert was created.
  • false — the Terminate Target User Sessions rule setting was disabled, so no automated session termination was taken.
The value of terminate_sessions depends on the Terminate Target User Sessions setting in the rule configuration, which is off by default.
Last modified on October 29, 2026