Add a SaaS API Rule to the Data Loss Prevention Policy

Configure a SaaS API Rule to set the criteria as to what triggers the scanning. As files in the selected tenant are scanned upon content and/or context (sharing) change, Umbrella assesses the file against this rule’s criteria. In case of a rule violation, the rule's action automatically triggers. You may also trigger a manual response action from the Data Loss Prevention Report.

1. Navigate to Policies > Management > Data Loss Prevention Policy. The page displays a list of all Real Time and SaaS API Rules created.
2. From the Add Rule drop-down, select SaaS API Rule.

3. In the Add New SaaS API Rule page, enter a meaningful Rule Name and Description. Select a Severity value from the drop-down based on the risk involved or importance within the ruleset. (Assigning severity values can help later on when you need to filter events in the Data Loss Prevention report.)

4. Select where in scanned files you would like this rule to search for the data classifications that you choose

Content—(Default) Scans only the content of files for the selected data classifications.
File Name—Scans only file names for the selected data classifications.
Content and File Name—Scans content and file names for the selected data classifications. Both content and file name do not need to match for the rule to apply, only one or the other.

Note: Choosing Content, File Name, or Content and File Name refers to scanning file uploads for the selected data classifications and configured file labels.

5. Select Data Classifications to apply this rule; you can choose a data classification of your own making or a built-in data classification provided by Umbrella. (See Manage Data Classifications and Built-In Data Classifications.) Hover over PREVIEW to view data identifiers associated with each data classification.

6. Add up to 10 case-sensitive file label names to apply to this rule. The rule will search for any of the configured file label names in the value of the files' document properties. This includes:
   Microsoft Office Document Properties
   Microsoft Office Sensitivity Labels
   Adobe PDF Document Properties
   File uploads to Confluence and Jira are not scanned for file labels.

👍

Microsoft Sensitivity Labels

Umbrella currently supports the detection of Microsoft sensitivity labels in the file properties’ values of the inspected file for Microsoft Word, Excel, PowerPoint, and .pdf files. Ensure you configure the rule with the name of the sensitivity labels, not the Display Names.

7. Under Platform, select one platform and tenant for this rule.

8. Under Include and Exclude make selections to define users to include or exclude from being matched:

• Select Include all users, including external collaborators.

• Select Include specific users . You can specify the users in two ways:

• Choose Select file users

Select entire identity categories to include, or expand categories to select individual identities. Search for AD user name or AD group name. Selected identities will appear in the box on the right.

Note: Identities added to a category after the category has been included or excluded from a rule will be included or excluded from the rule as if they were members of the category at the time the rule was created.

• Choose Manually add user email addresses

Enter the users' email addresses in the text box.

• Select Exclude specific file users to exclude the selected users from matching by this rule. Similarly to selecting identities for inclusion, you can select the entire AD group. Search for identities by AD user name or by AD Group. Selected identities will appear in the box on the right.

9. Resource Labels appears only if you have selected AWS or Azure for platform. Under Resource Labels, enter key/value pairs you have applied as tags to objects in AWS S3 buckets or Azure storage accounts or containers. Each resource label you enter here identifies the data Umbrella will monitor within your buckets (for AWS) or storage accounts or containers (for Azure). It may take a few minutes for resource labels you enter here to propagate to the policy page, depending on how many there are and the state of the discovery process.

10. Resources appears only if you have selected AWS S3 or Azure Storage for Platform.
    Under Resources make selections to define S3 buckets (for AWS) or containers (for Azure) to include or exclude from being matched by this rule:

• Select Include all resources for all the S3 buckets (for AWS) or storage accounts or containers (for Azure) associated with your account (including non-admin resources).

• Select Include specific resources to display a list of resources available and select the ones you want to include for matching.

11. Under Exposure, optionally select the file sharing permissions to consider when processing files to search for data violations:

• Shared Publicly- Accessible to all users with the link to the file.
• Domain-wide Share- Shared with all users in a domain.
• Shared with Internal Users- Shared with users who belong to the authorized domains.
• Shared with External Users- Shared with users who do not belong to the authorized domains.
• Shared with Specific Users- Shared with specific users by their email addresses.

The table below indicates which Exposure settings are available for each platform:

🚧

• A DLP rule can be configured with either Data Classifications, File Labels or both. Exposure is an optional criterion.
• When a DLP rule is configured with all 3 criteria, then a DLP event is raised when any of the selected Data Classifications and when any of the configured file labels are detected in the inspected file and when the file’s permissions match any of the selected exposure settings.

12. From the Action drop-down list, choose Monitor, Quarantine, Delete or Revoke Access.

• Monitor- Detects and logs a DLP event for every modified file violating this rule’s criteria
• Quarantine- Isolates a file that violates the rule criteria to the quarantine folder and revokes all shares
• Delete- Permanently deletes when a change is detected that violates the rule criteria (This option is available only for Webex Teams, and applies for a violation within a post, as well as a violation within a file attached to a post.)
• Revoke Access- Removes public link, all external or internal users, and any share permission within the entire organization. This action also removes the file owner and transfers the ownership to the selected user.

The table below indicates which Actions settings are available for each platform:

🚧

If you choose Quarantine for Microsoft OneDrive, Sharepoint Online, Box, Dropbox, or Google Drive:

• The file identified as exposing sensitive data is moved to the Cisco_Quarantine/DLP folder Umbrella created in the root path of the Global Admin who authorized the tenant.
• In lieu of the quarantined file, a text file is left in the original location with the name filename.ppt_Unique-Event-ID_Cisco_Quarantined.txt explaining to the original File Owner that the file is identified as exposing sensitive data and for more information to contact their organization administrator.
• The user who authorizes access to Umbrella will have access to the quarantine folder. All other accesses and collaborators are removed.
• Thus, we recommend that the admin add the relevant DLP Admins as additional collaborators to the folder.

If you choose Quarantine for ServiceNow:

• The file identified as exposing sensitive data is moved to a table named Cisco_Quarantine_Malware which can be access only by the admin user who authorized the ServiceNow tenant.
• A footprint is attached to the notes\activities area of the table the file is attached to. This footprint will notify users that the file has been identified as malware, and for more information they should contact their administrator.

• Note: Quarantine attempts may fail if the files have been locked or blocked by settings within their native platforms. Settings local to the platform where a file resides take precedence over Umbrella’s ability to detect or remediate DLP violations or malware.
• Note: If your DLP rules process files from Microsoft OneDrive, SharePoint Online, Box, Dropbox, ServiceNow, or Google Drive and you restore a quarantined file that still violates rule criteria, the system will quarantine that file again. To prevent the system from quarantining the file again, remove the file's violation, or update the rule's criteria.”

13. If you chose Revoke Access:

• If you chose Google Drive for the Platform, choose from the following options:

• Remove public link: Removes any file link that has public exposure.
• Remove share exclusively with internal users: Removes all internal users of files that were shared with few specific internal users.
• Remove share with any external user: Removes all external users. (External users are not part of the organization domain)
• Remove specific shares: Entered email addresses or group email addresses are removed.
• Remove org-wide share link: Removes any share permission with the entire organization.
• Remove owner: Removes the file owner and transfers ownership to a new email address.

• If you chose Microsoft 365 for the platform, choose from the following options:

• Remove public link: Removes any file link that has public exposure.
• Remove org-wide share link: Removes any share permission with the entire organization.

• If you chose Box for the platform, you may choose the following option:

• Remove public link: Removes any file link that has public exposure.

• If you chose Dropbox for the platform, you may choose from the following options:

• Remove public link: Removes any file link that has public exposure.
• Remove org-wide share link: Removes any share permission with the entire organization.

14. Under User Notifications you can enable and configure an email notification to be sent to one or both of the following users:

• The owner of the file associated with a rule violation
• The user who performs an action that triggers a rule violation

You can use a default email template provided by the system, or create your own custom template.

1. Enable user notifications.

2. Select one or both of the following email recipients:

• File owner - The owner of the file associated with the rule violation
• Event actor - The user who performs an action that triggers the rule violation

3. Choose the email template:

To Use the Default Email Template:

1. Click Default Email.
2. To preview the content of the email that will be send to users, click on Preview Default Email. You can review the email subject line and text, but you cannot change it.

3. (Optional) To send a test copy of the email to an address of your choosing, enter an address in Preview Test Email and click SEND PREVIEW to send the message. (By default the system uses the email address of the logged in user.)
4. Click CLOSE to return to the Data Loss Prevention Policy page.

To Use a Custom Email Template:

1. Click Custom Email.
2. From the drop down menu, select an existing custom template, or choose CREATE CUSTOM TEMPLATE. If you select an existing custom template, you can click Preview and Edit Custom Email to review and change the template.

3. When you choose to create or edit a custom template for email notifications of policy violations you will see one of these two dialogs, which are almost identical:

The Edit Custom Email Template includes a DELETE link which you can use to delete a custom template that is no longer needed. You may not delete a template that is in use by any rule.

To create a new template or change an existing template:

A. Enter a unique Custom Email Template Name.

B. Enter an Email Subject Line.

C. Enter the text of the email in the Email Body text box.

The email text can include the following variables, which you must enclose in braces ( {} ):

• {eventId} - The unique identifier the system generates for the policy violation event.
• (detectedTimestamp} - The date and time the violation was detected, formatted as shown in this example: "Oct 1, 2023 at 14:04 UTC"
• (actorName} - Name of the user whose action triggered the violation. (The system gets this from the tenant associated with the violation. Depending on application and file settings, this information may not be available, in which case the the system replaces this variable with blank text.)
• {actorEmail} - Email address of the user whose action triggered the violation. (The system gets this from the tenant associated with the violation. Depending on application and file settings, this information may not be available, in which case the the system replaces this variable with blank text.)
• {fileName} - Name of the data file that triggered the violation.
• {ruleName} - Name of the rule that was triggered.
• {matchedClassifications} - The data classifications associated with the violation. (See Manage Data Classifications.)
• {destination} - The application or platform type of the tenant associated with the violation. (E.g., Google Drive or One Drive; see Manage Tenant Controls.)
• {fileOwnerName} - Name of the file owner. (The system gets this from the tenant associated with the violation. Depending on application and file settings, this information may not be available, in which case the the system replaces this variable with blank text.)
• {fileOwnerEmail} - Email address of the file owner. (The system gets this from the tenant associated with the violation. Depending on application and file settings, this information may not be available, in which case the the system replaces this variable with blank text.)
• {fileLocation} - The file URL.

Note: The system replaces a variable with blank text if there is no value assigned to the variable or if an invalid variable name appears within the braces.

D. (Optional) To send a test copy of the email to an address of your choosing, enter an address in Preview Test Email and click SEND PREVIEW to send the message. (By default the system uses the email address of the logged in user.)
E. Click SAVE to return to return to the Data Loss Prevention Policy page.

15. Click Save. All fields must have options selected to save.

---

Supported Applications < Add a SaaS API Rule to the Data Loss Prevention Policy > Discovery Scan