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 change and context (sharing) change, Secure Access assesses the file against this rule’s criteria. If a match is made, this rule’s action is immediately enforced. If Secure Access detects a violation, the offending file is listed in the Data Loss Prevention Report.

  1. Navigate to Secure > Policy > 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.
1576
  1. 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.)
2154
  1. 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.

  1. 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 Secure Access. (See Manage Data Classifications and Built-In Data Classification Templates.) Hover over PREVIEW to view data identifiers associated with each data classification.
1542
  1. 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 Sensitive Labels

Secure Access 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.

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

  1. 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.
  1. 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:

Shared PubliclyDomain-wide shareShared with internal usersShared with external usersShared with specific users
Microsoft Office 365
Dropbox
Box
Google
Webex Teams
Slack
Service Now

🚧

  • 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.
  1. 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:

MonitorQuarantineDeleteRevoke
Access
Microsoft Office 365
Dropbox
Box
Google
Webex Teams
Slack
Service Now
1394

🚧

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 Secure Access 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 Secure Access 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: 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.”
  1. 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.
1412
  • 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.
950
  • 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.
  1. 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.
  1. 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
  1. 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.
  1. (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.)
  2. 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.
  1. 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.

  1. 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