> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shield Alert Events

export const MultiRelatedLinks = ({sections = []}) => {
  if (!sections || sections.length === 0) {
    return null;
  }
  return <div className="space-y-8">
      {sections.map((section, index) => <RelatedLinks key={index} title={section.title} items={section.items} />)}
    </div>;
};

export const RelatedLinks = ({title, items = []}) => {
  const getBadgeClass = badge => {
    if (!badge) return "badge-default";
    const badgeType = badge.toLowerCase().replace(/\s+/g, "-");
    return `badge-${badge === "ガイド" ? "guide" : badgeType}`;
  };
  if (!items || items.length === 0) {
    return null;
  }
  return <div className="my-8">
      {}
      <h3 className="text-sm font-bold uppercase tracking-wider mb-4">{title}</h3>

      {}
      <div className="flex flex-col gap-3">
        {items.map((item, index) => <a key={index} href={item.href} className="py-2 px-3 rounded related_link hover:bg-[#f2f2f2] dark:hover:bg-[#111827] flex items-center gap-3 group no-underline hover:no-underline border-b-0">
            {}
            <span className={`px-2 py-1 rounded-full text-xs font-semibold uppercase tracking-wide flex-shrink-0 ${getBadgeClass(item.badge)}`}>
              {item.badge}
            </span>

            {}
            <span className="text-base">{item.label}</span>
          </a>)}
      </div>
    </div>;
};

export const Link = ({href, children, className, ...props}) => {
  const localizedHref = localizeLink(href);
  return <a href={localizedHref} className={className} {...props}>
      {children}
    </a>;
};

[Box Shield][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][threatdetect] 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
<Link href="/guides/events/enterprise-events/for-enterprise">enterprise event</Link> stream. These events follow the
standard event object schema and the `event_type` value is set to
`SHIELD_ALERT`.

```json theme={null}
{
  "source": null,
  "created_by": {
    "type": "user",
    "id": "2",
    "name": "Unknown User",
    "login": ""
  },
  "action_by": null,
  "created_at": "2019-12-20T11:38:56-08:00",
  "event_id": "97f1b31f-f143-4777-81f8-1b557b39ca33",
  "event_type": "SHIELD_ALERT",
  "ip_address": "10.1.2.3",
  "type": "event",
  "session_id": null,
  "additional_details": {
    "..."
  }
}
```

The `additional_details` object provides information
about the specific type of shield alert that triggered the event.

### 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:

```json theme={null}
"additional_details": {
  "shield_alert": {
    "rule_category": "Suspicious Locations",
    "rule_id": 123,
    "rule_name": "Suspicious Location",
    "rule_response_action": {
      "restrict_user": true
        },
    "risk_score": 60,
    "alert_summary": {
      "alert_activities": [
        {
          "occurred_at": "2019-12-20T11:37:05-08:00",
          "event_type": "Download",
          "item_name": "xyz.txt",
          "item_type": "file",
          "item_id": "127",
          "item_path": "ABC/DEF",
          "ip_info": {
            "ip": "1.2.3.4",
            "latitude": "37.5555",
            "longitude": "-120.6789",
            "registrant": "Microsoft Corporation",
            "country_code": "US",
            "city_name": "San Jose",
            "region_name": "California"
          },
          "service_name": "Box Excel Online Previewer"
        }
      ]
    },
    "alert_id": 2398,
    "priority": "medium",
    "user": {
      "id": 2320,
      "name": "Some name",
      "email": "some@email.com"
    },
    "link": "https://app.box.com/master/shield/alerts/2398",
    "created_at": "2019-12-20T11:37:15-08:00"
  }
}
```

### 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:

```json theme={null}
"additional_details": {
  "shield_alert": {
    "rule_category": "Suspicious Sessions",
    "rule_id": 123,
    "rule_name": "Suspicious Session",
    "rule_response_action": null,
    "risk_score": 77,
    "alert_summary": {
      "description": "First time in prior month user connected from ip 2.3.4.5 First time user agent Some User Agent (Some UA 4.5.6) appeared for user within prior month Apparent distance 9580.0 km between events 59 seconds apart is faster than possible",
      "sessions": [
        {
          "session_type": "suspicious",
          "activities": [
            {
              "occurred_at": "2019-12-19T11:37:00-08:00",
              "event_type": "Set shared link expiration",
              "item_name": "xyz.txt",
              "item_type": "file",
              "item_id": "123456",
              "item_path": "ABC/DEF",
              "ip_info": {
                "ip": "2.3.4.5",
                "latitude": "37.5555",
                "longitude": "-120.6789",
                "registrant": "Microsoft Corporation",
                "country_code": "US",
                "city_name": "San Jose",
                "region_name": "California"
              },
              "service_name": "ServiceName"
            }
          ]
        },
        {
          "session_type": "typical",
          "activities": [
            {
              "occurred_at": "2019-12-19T11:37:59-08:00",
              "event_type": "Item Modified",
              "item_name": "abc.boxnote",
              "item_type": "file",
              "item_id": "123123",
              "item_path": "folder/sub folder",
              "ip_info": {
                "ip": "4.5.6.7",
                "latitude": "37.5555",
                "longitude": "-20.6789",
                "country_code": "US",
                "city_name": "Some City",
                "region_name": "XYZ"
              },
              "service_name": "Box Notes"
            }
          ]
        }
      ]
    },
    "alert_id": 500,
    "priority": "medium",
    "user": {
      "id": 50500,
      "name": "A b c",
      "email": "a@b.c"
    },
    "link": "https://cloud.app.box.com/master/shield/alerts/500",
    "created_at": "2019-12-20T11:38:16-08:00"
  }
}
```

### 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 `additional_details` payload will provide the following details:

```json theme={null}
"additional_details": {
  "shield_alert": {
    "rule_category": "Anomalous Download",
    "rule_id": 123,
    "rule_name": "Anomalous Download Rule",
    "rule_response_action": null,
    "risk_score": 77,
    "alert_summary": {
      "description": "Significant increase in download content week over week, 9200% (25.04 MB) more than last week 12 additional files downloaded week over week)",
      "download_delta_size": "25 Mb",
      "download_delta_percent": 9200,
      "historical_period": {
        "date_range": {
          "start_date": "2019-12-01T01:01:00-08:00",
          "end_date": "2019-12-08T01:01:00-08:00"
        },
        "download_size": "0 Mb",
        "downloaded_files_count": 1
      },
      "anomaly_period": {
        "date_range": {
          "start_date": "2019-12-08T01:01:00-08:00",
          "end_date": "2019-12-15T01:01:00-08:00"
        },
        "download_size": "25 Mb",
        "downloaded_files_count": 13
      },
      "download_ips": [
        {
          "ip": "1.2.3.4"
        }
      ]
    },
    "alert_id": 444,
    "priority": "medium",
    "user": {
      "id": 567,
      "name": "Some user",
      "email": "some@user.com"
    },
    "link": "https://cloud.app.box.com/master/shield/alerts/444",
    "created_at": "2019-12-20T11:38:16-08:00"
  }
}
```

### 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:

```json theme={null}
"additional_details": {
  "shield_alert": {
    "rule_category": "Malicious Content",
    "rule_id": 123,
    "rule_name": "Viruses and stuff",
    "rule_response_action": null,
    "risk_score": 100,
    "alert_summary": {
      "upload_activity": {
        "occurred_at": "2019-12-20T11:37:05-08:00",
        "event_type": "Upload",
        "item_name": "virus.exe",
        "item_type": "file",
        "item_id": "127",
        "item_path": "ABC/DEF",
        "sha1_hash": "",
        "ip_info": {
          "ip": "1.2.3.4",
          "latitude": "37.5555",
          "longitude": "-120.6789",
          "registrant": "Microsoft Corporation",
          "country_code": "US",
          "city_name": "San Jose",
          "region_name": "California"
        },
        "service_name": "Service name"
      }
    },
    "malware_info": {
       "file_id": 127,
       "file_name": "malware.exe",
       "file_version": 4239023,
       "file_created": "2019-12-20T11:37:05-08:00",
       "file_created_by": {
         "id": 1010,
         "name": "Bob",
         "email": "bob@enterprise.com"
      },
      "file_hash": "d869db7fe62fb07c25a0403ecaea55031744b5fb",
      "file_hash_type": "SHA-1",
      "file_size_bytes": 51345,
      "file_version_uploaded": "2019-12-20T11:37:05-08:00",
      "file_version_uploaded_by": {
        "id": 1011,
        "name": "Jane",
        "email": "jane@enterprise.com"
      },
      "status": "Malicious",
      "categories": [
        "Adware",
        "SpyWare"
      ],
      "tags": [
        "FILE_MALICIOUS_EXECUTION",
        "FILE_OTHER_TAG"
      ],
      "description": "This is a really bad file",
      "detail_link": "https://some.link/xyz",
      "malware_name": "BadMalware",
      "first_seen": "2019-12-19T11:37:05-08:00",
      "last_seen": "2019-12-20T11:37:05-08:00",
      "family": "MalwareBot4000"
    },
    "alert_id": 2398,
    "priority": "medium",
    "user": {
      "id": 2320,
      "name": "Some Name",
      "email": "some@email.com"
    },
    "link": "https://app.box.com/master/shield/alerts/2398",
    "created_at": "2019-12-20T11:37:15-08:00"
  }
}
```

### 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:

```json theme={null}
{
  "source": null,
  "created_by": {
    "type": "user",
    "id": "2",
    "name": "Unknown User",
    "login": ""
    },
    "action_by": null,
    "created_at": "2025-08-19T10:44:26-07:00",
    "event_id": "5b508973-0e48-4bc1-80b2-a05b5382eb37",
    "event_type": "SHIELD_ALERT",
    "ip_address": "1.2.3.4",
    "type": "event",
    "session_id": null,
    "additional_details": {
      "shield_alert": {
        "rule_category": "Ransomware Activity",
        "rule_id": "1234",
        "rule_name": "Ransomware Detection",
        "rule_response_action": null,
          "risk_score": 100,
          "alert_summary": {
          "total_files_affected": 42,
          "ip_details": [
            {
             "ip": "1.2.3.4",
             "registrant": "Microsoft Corporation",
             "latitude": "37.5555",
             "longitude": "-120.6789",
             "city_name": "San Jose",
             "region_name": "California",
             "country_code": "US"
            }
           ],
           "suspicious_file_extensions": [
            "lockbit"
           ],
           "anomaly_period": {
            "date_range": {
             "start_date": "2009-02-13T23:31:30Z",
             "end_date": "2009-02-13T23:31:30Z"
            }
          }
        },
        "alert_id": 1234,
        "priority": "medium",
        "user": {
         "id": 8167630149,
         "name": "Some user",
         "email": "Some@user.com"
        },
        "link": "https://app.box.com/master/shield/alerts/1234",
        "created_at": "2025-08-19T10:44:26-07:00"
     }
   }
}
```

[box-shield]: https://www.box.com/shield

[threatdetect]: https://support.box.com/hc/en-us/articles/360044196113-Using-Threat-Detection

[smartaccess]: https://docs.box.com/en/box-shield/shield-smart-access-policies/about-smart-access

[monitoringmode]: https://docs.box.com/en/box-shield/shield-smart-access-policies/about-smart-access

<RelatedLinks
  title="RELATED APIS"
  items={[
{ label: translate("List user and enterprise events"), href: "/reference/get-events", badge: "GET" },
{ label: translate("Get events long poll endpoint"), href: "/reference/options-events", badge: "OPTIONS" }
]}
/>

<RelatedLinks
  title="RELATED GUIDES"
  items={[
{ label: translate("Get Enterprise Events"), href: "/guides/events/enterprise-events/for-enterprise", badge: "GUIDE" }
]}
/>
