Symantec
™
Data Loss Prevention Detection REST API 2.0
Reference Guide
15.8
Last updated: June 1, 2022
Table of Contents
Introducing the Symantec Data Loss Prevention Detection REST API 2.0....................................4
About the Symantec Data Loss Prevention Detection REST API...............................................................................4
About the Detection REST API 2.0 Topics.................................................................................................................... 4
Overview of the Symantec Data Loss Prevention Detection REST API 2.0...............................................................4
Symantec DLP Detection REST API 2.0 Reference..........................................................................6
Detection Requests for the DLP Detection REST API 2.0........................................................................................... 6
URL..............................................................................................................................................................................6
HTTP Method.............................................................................................................................................................. 6
HTTP Request Headers..............................................................................................................................................6
HTTP Body..................................................................................................................................................................7
Detection request format and definitions.................................................................................................................... 7
Context Entries.....................................................................................................................................................7
Content Blocks................................................................................................................................................... 12
Option entry........................................................................................................................................................13
Sample request......................................................................................................................................................... 13
Input Validation...............................................................................................................................................................14
Detection Results........................................................................................................................................................... 15
HTTP Response Headers.........................................................................................................................................16
HTTP Response Codes............................................................................................................................................ 16
Detection result format and definitions..................................................................................................................... 16
Policy.................................................................................................................................................................. 17
Response Action................................................................................................................................................ 17
Response Action Parameters............................................................................................................................ 18
Warning......................................................................................................................................................................19
Content Detail............................................................................................................................................................19
Error Messages......................................................................................................................................................... 20
Sample response...................................................................................................................................................... 20
Action Acknowledgment Requests.............................................................................................................................. 21
URL............................................................................................................................................................................21
HTTP Method............................................................................................................................................................ 21
HTTP Body................................................................................................................................................................21
Action Acknowledgment Request Format and Descriptions.....................................................................................21
Actions Taken.....................................................................................................................................................22
Sample Action Acknowledgment Request................................................................................................................22
Supported File Types for DLP REST API 2.0 Detection.................................................................24
Word Processing File Types Supported for REST API 2.0 Detection.......................................................................25
2
Multimedia File Types Supported for REST API 2.0 Detection................................................................................. 26
Spreadsheet File Types Supported for REST API 2.0 Detection...............................................................................26
Presentation File Types Supported for REST API 2.0 Detection.............................................................................. 26
Image File Types Supported for REST API 2.0 Detection..........................................................................................27
Encapsulation File Types Supported for REST API 2.0 Detection............................................................................28
Encryption File Types Supported for REST API 2.0 Detection................................................................................. 28
Other File Types Supported for REST API 2.0 Detection.......................................................................................... 29
Documentation Legal Notice............................................................................................................ 30
3
Introducing the Symantec Data Loss Prevention Detection
REST API 2.0
About the Symantec Data Loss Prevention Detection REST API
The Symantec Data Loss Prevention Detection REST API enables you to develop REST clients. These clients can
connect to, and can inspect the content of, specific applications that you identify for security monitoring with:
•
Symantec Data Loss Prevention Cloud Detection Service or
•
Symantec Data Loss Prevention API Detection for Developer Apps virtual appliance
Your REST API client sends sensitive data to Symantec Data Loss Prevention. The data is inspected by the Cloud
Detection Service or the API Detection for Developer Apps virtual appliance. Symantec Data Loss Prevention inspects
the data and creates incidents. Symantec Data Loss Prevention also returns response action recommendations in
the REST detection request response.
The Symantec Data Loss Prevention API Detection for Developer Apps virtual appliance provides detection capabilities
that are deployed on-premises. You can monitor content and you can identify information policy violations in applications
using a custom REST client.
NOTE
The "API Detection for Developer Apps virtual appliance" is often referred to as the "REST API Appliance."
The Symantec Data Loss Prevention Cloud Detection Service is a Symantec Data Loss Prevention
detection service. Deployed in the cloud, it enables you to monitor content and identify information policy violations in
cloud applications. The Cloud Detection Service can inspect both network traffic ("data in motion," or DIM) and data
stored in a repository ("data at rest," or DAR). You can specify which type of data you are posting for inspection using the
common.dataType context entry in your detection request.
About the Detection REST API 2.0 Topics
The REST API 2.0 topics are a reference intended for software developers creating REST clients for in-house or third-
party cloud applications for use with Symantec Data Loss Prevention. We do not assume deep knowledge of Symantec
Data Loss Prevention, though familiarity with the concepts of Symantec Data Loss Prevention may be helpful. Consult
with your Symantec Data Loss Prevention administrator to learn more about Symantec Data Loss Prevention and how it
processes the data you post.
Overview of the Symantec Data Loss Prevention Detection REST API
2.0
The following table describes some general features of the REST API 2.0.
Table 1: General features of the Symantec Data Loss Prevention Detection REST API 2.0
Feature Description
Version You specify the API version using the path prefix in the base URL. The base URL path for this
version is /v2.0/.
HTTP methods Version 2.0 supports the POST method only.
Message serialization Version 2.0 supports JSON-formatted messages only.
4
Feature Description
Transport security Version 2.0 uses SSL/TLS to secure all connections.
Authentication Version 2.0 uses client certificate authentication. Symantec provides you with a certificate to use
with your REST client.
Connection longevity The Cloud Detection Service maintains long-lasting connections to REST clients, letting you submit
multiple detection requests using the same connection.
Caching Version 2.0 uses standard HTTP caching for detection responses. You cannot cache detection
requests.
Internationalization Some response rules include user messages, such as the Bounce Message to Sender option of
the Network Prevent: Block SMTP Message response rule action. The policy author configures
these messages. They cannot be localized for each detection request. The policy author is
responsible for providing a localized message in such cases.
Throttling When your Cloud Detection Service is overloaded, it returns the HTTP error status code 503
Service Unavailable.
Detection limits When you exceed the detection request size limit, Symantec Data Loss Prevention returns the
appropriate error in the response. The Symantec Data Loss Prevention administrator is responsible
for specifying detection size limits in the Enforce Server administrative console.
Batch requests Version 2.0 does not support batch requests.
Asynchronous requests Version 2.0 does not support asynchronous requests.
Results paging Version 2.0 does not support results paging.
5
Symantec DLP Detection REST API 2.0 Reference
Detection Requests for the DLP Detection REST API 2.0
The following topics describe the structure and usage of detection requests in the Symantec Data Loss Prevention
Detection REST API 2.0.
•
URL
•
HTTP Method
•
HTTP Request Headers
•
HTTP Body
•
Detection request format and definitions
•
Context Entries
•
Content Blocks
•
Option entry for REST API 2.0
•
Sample request
URL
The detection request URL is /v2.0/DetectionRequests.
HTTP Method
The detection request HTTP method is POST.
HTTP Request Headers
HTTP request headers describe the HTTP request headers for detection requests.
Table 2: HTTP request headers
HTTP Header Required? Description
Accept No Specifies the accepted request format:
application/json
X-SYMC-DLP-CustomerID No Specifies the Symantec Data Loss
Prevention customer. This header is
used when third parties post detection
requests on behalf of a Symantec Data
Loss Prevention customer.
X-SYMC-DLP-DetectorID Yes Specifies the target Cloud Detection
Service cloud detector or a REST API
Appliance. You may have several Cloud
Detection Services deployed, each with
different policies applied to them. This
header lets you direct your detection
request to the Cloud Detection Service with
the appropriate policy.
6
HTTP Body
The HTTP body consists of a single detection request.
Detection request format and definitions
This section describes and defines the parameters of a single detection request. The detection request specifies one field
of the ContextEntry type and multiple fields of the ContentBlock type.
Context entries send attribute information to Symantec Data Loss Prevention. These attributes may affect which policies
or response rules apply to the data you submit for inspection.
Content blocks send the data that you want to inspect in a format appropriate for Symantec Data Loss Prevention policy
detection. Each Symantec Data Loss Prevention policy may treat these content blocks differently. Your REST client must
distinguish where the content appeared in the network traffic you send for inspection. For general document inspection,
use the attachments content block.
DetectionRequest ::= SEQUENCE {
context SEQUENCE OF ContextEntry OPTIONAL,
subject ContentBlock OPTIONAL,
body ContentBlock OPTIONAL,
attachments SEQUENCE of ContentBlock OPTIONAL,
options SEQUENCE of Option Entry OPTIONAL,
}
Table 3: Detection request fields
Field Required or optional? Description
context Optional A list of context attributes submitted with
the detection request.
Context entries
subject Required (at least one of subject, body,
or attachments)
A content block submitted with the
detection request.
Content blocks
body Optional (at least one of subject, body,
or attachments)
A content block submitted with the
detection request.
Content blocks
attachments Optional (at least one of subject, body,
or attachments)
A series of content blocks submitted with
the detection request.
Content blocks
options Optional Other parameters that may impact the
response that is given.
Option Entry
Context Entries
This section describes the context attributes that you can submit with your detection request.
ContextEntry ::= SEQUENCE {
name ENUMERATED UTF8String,
value SEQUENCE OF UTF8String
}
7
Table 4: Context entry fields
Field Required or optional? Description
name Required The name of the context parameter.
For a list of the currently defined context
parameter names, see Context entry
parameter names.
value Required The value of the context parameter.
Values with known mappings to Symantec
Data Loss Prevention message attributes
are automatically mapped to those
attributes. Values for which no known
mapping exists are added to the message
envelope as key/value pairs. Standard text-
based detection rules can then be used to
match on those keys and their values.
Table 5: Context entry parameter names
Name Description
client.domain A string representing the domain of the REST client making a
detection request.
client.user.id A string representing the identifier for the user within the client
domain making the detection request.
common.application Required. A string representing the application name that is
specific to Gatelets and Securlets. For example, "securlet.box' or
"gatelet.box."
common.application.reportName A string representing the application name as it appears in reports,
such as "Box."
common.authrecipient A string representing the authenticated recipient of the message, if
known.
common.authsender A string representing the authenticated sender of the message.
For example,
•
an endpoint user
•
an authenticated HTTP proxy user
•
an authenticated SMTP user
common.created A string representing the ISO 8601 timestamp when the file was
created. For example, 2015-10-13T10:11:06.419Z. Used in DAR
requests only.
common.dataType Required. Specifies the type of data in the data request. The type
must be one of two values: DAR ("data at rest") or DIM ("data in
motion").
common.description A string representing the description field of the file. Used in DAR
requests only.
common.doc.activityCount A long integer representing the number of user actions on the
document.
common.doc.creatorId A string representing the unique identifier of the document creator.
8
Name Description
common.doc.exposed A Boolean value indicating if the document is shared or
accessible. The document is considered exposed if it is shared
with or accessible to everyone within your organization, or
shared with or accessible to anyone outside of your organization.
If the document is only shared with certain members of your
organization, it is not considered an exposed document.
common.doc.exposures.allInternal A Boolean value indicating if the document is shared with or
accessible to everyone within your organization.
common.doc.exposures.externalCollaborators A list of email addresses of people outside your organization that
have access to the document.
common.doc.exposures.internalCollaborators A list of email addresses of people inside your organization that
have access to the document.
common.doc.exposures.public A Boolean value indicating if the document is shared with
or accessible to everyone outside your organization. Such
documents are available to everyone on the Internet.
common.doc.id A string representing the unique identifier for the document in the
SaaS application.
common.doc.isInternal A Boolean value indicating if the document is "internal." A
document is considered internal if it was created by a member of
your organization.
common.doc.parentFolderId A string representing the unique identifier of the parent folder
containing the document.
common.doc.type A string representing the type of document, such as "file" or
"folder."
common.expectActionsAck A Boolean value indicating if the Enforce server should expect an
action acknowledgment for any responses.
common.filter Required. A list of filter identifiers that are associated with a given
scan.
common.folder A string representing the name of the folder containing the files or
attachments.
common.job.id A string representing the identifier of an on-demand scan.
common.lastAccessed A string representing the ISO 8601 timestamp when the file was
last accessed. For example, 2015-10-13T10:11:06.419Z. Used in
DAR requests only.
common.lastModified A string representing the ISO 8601 timestamp when the file was
last modified. For example, 2015-10-13T10:11:06.419Z. Used in
DAR requests only.
common.log.id A string representing the unique identifier for the log.
common.messageSource A string that specifies the source of a message when application
names overlap. For example, this parameter would specify
whether a Box incident came from the Box Gatelet or Box
Securlet.
common.owner A string representing the user identification of the data owner.
Used in DAR requests only.
common.service.classification A string representing the Shadow IT service classification, such as
"Sanctioned."
common.service.score An integer representing the Shadow IT score for the service
associated with the detection request. For example, Box has a
Shadow IT service score of 80.
9
Name Description
common.sharedWith An array of user IDs for all users the file is shared with. Used in
DAR requests only.
common.sharepoint A string representing the SharePoint site name.
common.sharingUrl A string representing the URL used to share the document. Used
in DAR requests only.
common.tag A string representing the tag field of the file. Used in DAR requests
only.
common.transactionId The transaction identifier used to link back to the incident on an
external console, such as CloudSOC.
common.user.activityType A string representing the activity performed by the user, such as
"add" or "delete."
common.user.docsExposedCount A long integer representing the number of documents that are
exposed to the user.
common.user.groupMembership A list of groups in the SaaS application that include the user.
common.user.id A string representing the unique identifier of the user.
common.user.isInternal A Boolean value indicating if the user is a member of your
organization.
common.user.name A string representing the name of the user as displayed in reports.
common.user.threatScore A long integer representing the threat score that is associated with
the user or event.
custom A custom context attribute.
device.isCompliant A Boolean value indicating if the device is compliant with your
mobile device management policy.
device.isPersonal A Boolean value indicating if the device is owned and managed by
the user.
device.isTrustedDevice A Boolean value indicating if the detection request came from a
trusted device.
device.isUnmanaged A Boolean value indicating if the device is not managed by your
mobile device management system.
device.os A string specifying the operating system of the device.
device.type A string specifying the type of device.
email.envelope.recipient The envelope recipient for an email message.
email.envelope.sender The envelope sender for an email message.
email.header.recipient The header recipient for an email message.
email.header.sender The header sender for an email message.
http.browser A string representing the name of the web browser, as determined
by the user agent.
http.cookies HTTP request cookies.
http.method Specifies the method that is used in the HTTP traffic that is
submitted for inspection.
http.siteClassification Specifies the classification of the site, such as "Social Media."
http.siteRiskScore A numerical value indicating the risk level of the target site.
http.url The target URL of the HTTP traffic submitted for inspection.
10
Name Description
http.userAgent The user agent that is supplied by the device of the user or
browser for the HTTP traffic that is submitted for inspection.
link.doc.exposure A string representing a link to the CloudSOC console Exposures
panel for the document.
link.incident A string representing a link to the CloudSOC Policy Alert
corresponding to the incident.
link.service.application A string representing a link to the CloudSOC Service Visibility
panel for that user.
link.service.file.activity A string representing a link to the application-specific activities list
in CloudSOC, filtered by the document name.
link.uba A string representing a link to the CloudSOC Investigate panel.
The Investigate panel displays a list of the activities that are
performed by the user for the last seven days, which are filtered
by application and username.
link.user.exposures A string representing a link to the CloudSOC Securlets console.
The Securlets console displays the Exposures panel for the user.
link.user.threatTree A string representing a link to the CloudSOC Threat Tree for the
user.
location.coords.latitude The geographic latitude of the device.
location.coords.longitude The geographic longitude of the device.
location.isInsideOffice Boolean value indicating if the data originated from or resides on a
device inside your office.
location.region A string representing the location from which the action was
performed, in the format "City(Country)."
location.region.country A string representing the country where the activity was
performed.
network.direction Specifies if the DIM detection request is for content upload or
download. Must be one of two values: Upload or Download.
Used in DIM requests only.
network.protocol Specifies the OSI Level 7 network protocol for the detection
request. For example, SMTP, HTTP, FTP, and so on. Used in DIM
requests only.
network.recipient.ip The IP address of the message recipient.
network.recipient.port The network port of the message recipient.
network.sender.ip The IP address of the message sender.
network.sender.port The network port of the message sender.
Obtaining the common.filter identifier
The common.filter context entry parameter identifies the Application Detection configuration that is associated with your
detection request. For detailed information on Application Detection configurations, see the online Help.
You can obtain the common.filter identifier from the Manage > Application Detection > Configuration > Edit
Configuration page in the Enforce Server administrative console.
To obtain the common.filter identifier
11
1. In the Enforce Server administrative console, navigate to Manage > Application Detection > Configuration.
2. Optional: If you have not already done so, create and save a Cloud Detection API Service Application Detection
configuration for your application.
3. Click the name of the appropriate Application Detection configuration on the Manage > Application Detection >
Configuration list page.
The Manage > Application Detection > Configuration > Edit Configuration page appears.
4. Copy the value in the ID field. This value is the common.filter identifier.
Content Blocks
This section describes the fields of the content blocks that you can submit with your detection request.
ContentBlock ::= SEQUENCE {
contentBlockId UTF8String,
mimeType UTF8String,
characterEncoding UTF8String,
extracted Boolean,
fileName UTF8String,
fileType UTF8String,
originalSize Integer,
data Base64 encoded data
}
Table 6: Content block fields
Field Required or optional? Description
contentBlockId Required A client-defined ID that uniquely identifies
the content block within the scope of the
detection request. This ID is used for
response action targeting.
mimeType Required Specifies the MIME type of the base64-
decoded content block.
characterEncoding Optional Specifies the character set encoding used
by the base64-decoded content block.
extracted Optional Boolean value indicating that the data in the
content block has already had its content
extracted. In such a case, the Cloud
Detection Service or REST API Appliance
will not perform content extraction. If this
field is omitted, the Cloud Detection Service
or REST API Appliance performs content
extraction.
fileName Optional Specifies the name of the file in the content
block.
fileType Optional Specifies the file type of the file in the
content block. Use this field only for content
that you have already extracted.
12
Field Required or optional? Description
originalSize Optional An integer specifying the original size of the
file included in the content block, in bytes.
Use this field only for content that you have
already extracted.
data Required The base64-encoded file content you want
to submit for detection.
Option entry
This section describes the fields of the option entry that you can submit with your detection request.
OptionEntry ::= SEQUENCE {
name ENUMERATED UTF8String,
value SEQUENCE OF UTF8String
}
Options are request parameters added so that the response can have more details. Options include a collection of
name,value pairs where the value can be a sequence of strings.
•
name - Option parameter name
•
value - Option parameter values
Table 7: List of possible options
Option Parameter Name Option Parameter Value Applicability Description
returnTopLevelFileTypes True or False Only if attachments are present.
Returns file type even if no policies are violated.
This option requests to return top-level file types in the response if attachments are present. If the file type cannot be
determined, then a value of UNKNOWN is returned. The response does not contain the file types in the following cases:
•
In the absence of the returnTopLevelFileTypes option, or
•
When Content Extraction times out, or
•
When there are illegal parameter values for this option.
With container files, only the top-level file type is returned. The string returned corresponds to DLP-defined file types.
Sample request
This is a sample detection request:
POST /v2.0/DetectionRequests HTTP/1.1
User-Agent: curl/7.35.0
Host: 10.1.2.3
Content-Type: application/json
Accept: application/json
{
"options" : [
{"name": "returnTopLevelFileType", "value": ["false"]},
],
"context" : [
{"name": "common.dataType", "value": ["DIM"]},
{"name": "common.application", "value": ["securlet.googledrive"]},
{"name": "email.envelope.sender", "value": ["[email protected]"]},
13
{"name": "email.envelope.recipient", "value": ["[email protected]",
"[email protected]"]},
{"name": "email.header.sender", "value": ["[email protected]"]},
{"name": "email.header.recipient", "value": ["[email protected]",
"[email protected]"]},
{"name": "location.region", "value": ["United States"]},
{"name": "location.region.country", "value": ["US"]},
{"name": "http.url", "value": ["http://google.com"]},
{"name": "link.user.exposures", "value": ["http://google.com/
userexposures"]},
{"name": "link.uba", "value": ["http://google.com/uba"]},
{"name": "link.doc.exposure", "value": ["http://google.com/docexposures"]},
{"name": "link.service.file.activity", "value": ["http://google.com/
servicefileactivity"]},
{"name": "link.incident", "value": ["http://google.com/incident"]},
{"name": "link.service.application", "value": ["http://google.com/
serviceapplication"]},
{"name": "common.transactionId", "value": ["a32cc030-9776-45ce-
ba55-84f9f5afe009"]},
{"name": "common.user.name", "value": ["My Favorite User"]},
{"name": "common.doc.exposed", "value": ["True"]},
{"name": "common.doc.exposures.public", "value": ["True"]},
{"name": "common.user.threatScore", "value": ["99"]},
{"name": "common.doc.type", "value": ["folder"]},
{"name": "common.user.docsExposedCount", "value": ["3"]},
{"name": "common.doc.creatorId", "value": ["321"]},
{"name": "common.doc.parentFolderId", "value": ["123"]},
{"name": "http.method", "value": ["GET"]},
{"name": "http.cookies", "value": ["G123213ET"]},
{"name": "device.type", "value": ["mobile"]},
{"name": "http.siteRiskScore", "value": ["66"]},
{"name": "common.user.activityType ", "value": ["create"]},
{"name": "http.browser ", "value": ["IE"]},
{"name": "common.filter", "value": ["69132E5E-732B-42AB-89C5-
C18B4A82434D"]},
{"name": "common.expectActionsAck", "value": ["true"]}
],
"subject":
{"contentBlockId": "block1",
"mimeType": "text/plain",
"data": "c2VjcmV0"}
}
Input Validation
Detection requests are validated before the Cloud Detection Service or REST API Appliance submits them to Symantec
Data Loss Prevention for detection. Some validation errors are fatal. Detection requests with fatal validation errors are not
submitted to Symantec Data Loss Prevention for detection. The Cloud Detection Service or REST API Appliance returns
an HTTP error with an error message body describing the problem.
If your detection request has a minor problem with validation, the Cloud Detection Service or REST API Appliance submits
the content to Symantec Data Loss Prevention for detection, and it returns a warning in the detection result.
14
All context entries are validated against the following constraints:
•
Entry has a non-null name. Failure to validate against this constraint results in a fatal error.
•
Entry has a non-null value. Failure to validate against this constraint results in a fatal error.
•
Values do not exceed a configuration length. Failure to validate against this constraint results in a warning.
•
Entry is checked for whether it is allowed to have multiple values. Failure to validate against this constraint results in a
warning.
In addition to these validations, the following table specifies context entries that are subject to more validation:
Table 8: More context entry validations
Context entry
Multiple
values
allowed
Match value
against list
Range
check
Numeric
characters
only
DIM/DAR
specific
Date format
check
common.authrecipient Yes
common.created Yes Yes (Fatal
error)
common.dataType Yes (Fatal
error)
common.description Yes
common.lastAccessed Yes Yes (Fatal
error)
common.lastModified Yes Yes (Fatal
error)
common.sharedWithList Yes Yes
common.sharingUrl Yes
common.tag Yes
common.doc.exposures.externalCollaboratorsYes
common.doc.exposures.internalCollaboratorsYes
common.user.groupMembership Yes
email.envelope.recipient Yes
email.header.recipient Yes
http.siteRiskScore Yes Yes
network.direction Yes (Fatal
error)
network.recipient.port Yes Yes Yes
network.sender.port Yes Yes
Detection Results
This section describes the content of detection results sent from the Cloud Detection Service or REST API Appliance back
to your REST client.
A detection request may result in zero to many policy violations. Each policy violation may indicate one or more response
actions that the Symantec Data Loss Prevention policy indicates that your organization should apply. Response actions
are included in the detection result for informational purposes only. Someone in your organization must carry out the
indicated response action to comply with your data loss prevention policies.
15
HTTP Response Headers
The following table describes the HTTP response headers for a detection result response.
Table 9: HTTP Response Headers
HTTP Header Description
cache-control This header is the standard HTTP caching header.
pragma: no-cache This header is identical to cache-control: no-cache
WWW-Authenticate: Basic realm="realm" Indicates that basic authentication is required, in compliance with
HTTP standards. The Cloud Server Connector returns the realm
Enforce.
HTTP Response Codes
The detection response includes one of these response codes:
Success response code:
•
201 Created
Error response codes:
•
400 Bad Request
•
401 Unauthorized
•
403 Forbidden
•
408 Request timeout
•
503 Service Unavailable
Detection result format and definitions
This section describes and defines the format of a single detection result. The detection result consists of five fields:
requestId, violation, responseAction, warning, and contentDetails.
DetectionResult ::= SEQUENCE {
requestId UTF8String
violation SEQUENCE OF Policy OPTIONAL,
responseAction SEQUENCE OF ResponseAction OPTIONAL,
warning SEQUENCE OF Warning OPTIONAL,
contentDetails SEQUENCE OF ContentDetail OPTIONAL,
}
Table 10: Detection result fields
Field Description
requestId A unique identifier for the detection request. The REST Detection Service assigns a
globally unique ID to each incoming detection request. When an incident is generated,
the requestId is submitted to Enforce along with other request-specific data. You can
use the requestId in reports in the Enforce Server administration console to correlate
your REST client detection requests and Symantec Data Loss Prevention incidents.
violation An unordered list of violated policies, if applicable. Each policy in the set has a unique
policyid value.
16
Field Description
responseAction An unordered list of response actions indicated by the policies, if applicable. Your
incident responder must process response actions by their embedded priority order
fields.
warning A list of warnings, if applicable. Warnings may appear if minor problems are encountered
with the detection request, but detection processing still took place.
contentDetails A list of content details, if applicable. See the OPTIONS parameters in the request.
Policy
This section describes the fields in the list of violated policies that may appear in your detection result.
Policy ::= SEQUENCE {
policyId UTF8String,
name UTF8String,
contentBlockIds SEQUENCE of UTF8String,
}
Table 11: Policy fields
Field Description
policyId The identifier of the violated policy.
name The descriptive name of the violated policy.
contentBlockIds List of the contentBlockIds from the requests that violated this
policy.
Response Action
This section describes the fields in the list of response actions that may appear in your detection result.
ResponseAction ::= SEQUENCE {
action ENUMERATED UTF8String,
priority INTEGER,
parameter SEQUENCE OF ResponseActionParameter
}
Table 12: Response Action Fields
Field Description
action An enumerated list of response actions.
Action descriptions
priority The response rule execution priority.
parameter A list of response action parameters. This list varies according to the response action.
Response action parameter descriptions
17
Table 13: Action descriptions
Action Description
block The policy indicates that you should block the file and should display an error to the user.
Required parameters: message.
Optional parameters: contentBlockId.
Applies to DIM detection requests.
breaklinks The policy indicates that you should break the links in the content.
Required parameters: none.
Optional parameters: contentBlockId, customResponsePayload.
Applies to DAR detection requests.
custom The policy indicates that a custom response rule should be applied. You must interpret
what the custom response rule should be based on the response action parameters.
Required parameters: none.
Optional parameters: contentBlockId, customResponsePayload.
Applies to both DAR and DIM detection requests.
delete The policy indicates that you should delete the content.
Required parameters: none.
Optional parameters: contentBlockId.
Applies to DAR detection requests.
drm The policy indicates that data rights management should be applied to the content.
Required parameters: none.
Optional parameters: contentBlockId, customResponsePayload.
Applies to both DAR and DIM detection requests.
encrypt The policy indicates that you should encrypt the content.
Required parameters: none.
Optional parameters: contentBlockId, customResponsePayload.
Applies to both DAR and DIM detection requests.
quarantine The policy indicates that you should quarantine or move the content.
Required parameters: none.
Optional parameters: contentBlockId, customResponsePayload.
Applies to both DAR and DIM detection requests.
redact The policy indicates that you should replace the content with the specified message. You
can choose whether to display an error to the user.
Required parameters: message.
Optional parameters: contentBlockId.
Applies to DIM detection requests.
tag The policy indicates that you should tag the content.
Required parameters: none.
Optional parameters: contentBlockId, customResponsePayload.
Applies to DAR detection requests.
Response Action Parameters
This section describes the fields and content of the response action parameters that may appear in the response action
section of your detection result.
ResponseActionParameter ::= SEQUENCE {
name UTF8String,
value SEQUENCE of UTF8String
18
}
Table 14: Response Action Parameter Fields
Field Description
name The name of the response action.
Response action parameter descriptions
value A list of values for the response action.
Table 15: Response Action Parameter Descriptions
Response Action Parameter Description
contentBlockId The identifier of the content block that violates the policy. This parameter may
have multiple values if the response rule applies to multiple content blocks.
customResponsePayload A custom response parameter that may be configured with the response action.
This custom parameter has no meaning to the Cloud Service Connector. For
example, you might configure a quarantine location for your organization to use
for content that triggers the quarantine response action.
message A message that you can display to your users.
Warning
This section describes the fields in the list of warnings that may appear in your detection response. When there are issues
with the content that you posted for detection, warnings are returned. The content is still submitted for detection.
Warning ::= SEQUENCE {
messageId UTF8String,
fieldName UTF8String,
message UTF8String
}
Table 16: Warning Field Descriptions
Warning Field Description
messageId An identifier for the validation warning type.
fieldName The issue in the detection request that triggered the warning.
message A detailed description of the warning.
Content Detail
Content details appear if the optional request parameters are present. For example, enabling
returnTopLevelFileTypes through the options returns the content detail for all the attachments present in the
request.
ContentDetail ::= SEQUENCE {
contentBlockId UTF8String,
topLevelFileType UTF8String
}
19
Table 17: Content Detail descriptions
Content field Description
contentBlockId The ID of the content block
topLevelFileType The top-level file type
Error Messages
If your detection request could not be submitted for detection, the detection response includes an error message.
Error ::= SEQUENCE {
messageId UTF8String,
message UTF8String
}
Table 18: Error Message Field Descriptions
Error Message field Description
messageId An identifier for the error message that uniquely identifies the error condition.
message A detailed description of the error.
Sample response
This is a sample detection response:
HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 250
Date: Wed, 23 Apr 2014 01:56:05 GMT
{
"requestId": "e402973a-5254-40ba-a725-84b2af6e58aa",
"violation": [
{"policyId": "pid12345689", "name": "Company Confidential Policy"},
{"policyId": "pid00000099", "name": "PCI Policy"}
],
"responseAction": [
{ "action": "redact",
"priority": 1,
"parameter" : [
{ "name": "contentBlockId", "value": ["block2"] },
{ "name": "message", "value": ["The content was removed due to a
loss
prevention policy violation"] }
]
}
]
"warning": [
{
"messageId": "conflicting-fields",
20
"fieldName": "attachments",
"message": "fileType should be specified for extracted data"
}
],
"contentDetails": [
{
"contentBlockId": "block2",
"topLevelFileType": "ascii"
}
]
}
Action Acknowledgment Requests
When a client receives a response action, it can optionally provide an action acknowledgment to the Cloud Detection
Service or REST API Appliance. The action acknowledgment indicates:
•
the action that is taken
•
the result of the action
•
the time the action was performed
•
an optional payload
This section describes the structure and usage of action acknowledgments in the Symantec Data Loss Prevention
Detection REST API 2.0.
For automated remediation actions, the client should only provide an action acknowledgment once per requestId or
transactionId. For manual remediation actions, the action acknowledgment can be provided more than once per
requestId or transactionId.
URL
The action acknowledgement URL is /v2.0/ActionsAcknowledge.
HTTP Method
The action acknowledgment HTTP method is POST.
HTTP Body
The HTTP body consists of a single detection request.
Action Acknowledgment Request Format and Descriptions
This section describes the fields in the client acknowledgment of a response action.
ActionsAcknowledgement ::= {
requestId UTF8String,
transactionId UTF8String OPTIONAL if requestId is supplied,
actionsTaken SEQUENCE OF ActionsTaken,
}
21
Table 19: Action Acknowledgment Field Descriptions
Action Acknowledgment Field Description
requestId A unique identifier for the detection request. The Cloud Detection Service or REST API Appliance
assigns an ID to each detection request. If the detection request results in a policy violation incident,
the Cloud Detection Service passes the requestId to Symantec Data Loss Prevention. You can
use the requestId in reports in the Enforce Server administration console to correlate your REST
client detection requests and Symantec Data Loss Prevention incidents.
transactionId A unique identifier for the request transaction. The REST client assigns a transaction identifier to
each detection transaction.
The transactionId field is optional if the requestId is included in the action acknowledgment. If
the action acknowledgment does not include a requestId, it must contain a transactionId. The
transactionId must also be included in the original detection request.
actionsTaken A sequence indicating the action taken, the result of the action, the time the action was performed,
and an optional payload.
Actions Taken
This section describes the values in the actionsTaken field of an action acknowledgment.
ActionsTaken::= SEQUENCE {
action UTF8String,
result UTF8String,
payload SEQUENCE of UTF8String OPTIONAL,
timestamp UTF8String in ISO8601 format
}
Table 20: Actions Taken Field Descriptions
Field Description
action A description of the action taken.
result The result of the action.
payload An optional custom payload.
timestamp A timestamp in ISO8601 format.
Sample Action Acknowledgment Request
A sample action acknowledgment request (line breaks that are added for legibility):
POST /v2.0/ActionsAcknowledge HTTP/1.1
User-Agent: curl/7.35.0
Host: 10.1.2.3
Content-Type: application/json
Accept: application/json
{
"requestId" : "56c55b54-c4fa-4a38-ad7e-3a106f746d09",
"transactionId" : "a32cc030-9776-45ce-ba55-84f9f5afe009",
"actionsTaken": [
{
"action": "quarantine",
22
"result": "failure",
"timestamp": "2015-10-14T10:11:06.419Z"
},
{
"action": "encrypt",
"result": "success",
"payload": {
"key1" : "https://abc.xyz.com/auth/admin/index.html#/documentDetails/
058b634e-8918-4440-ba4f-0de62d3017b4/",
"key2" : "https://somwhere.pgp.com"
},
"timestamp": "2015-10-14T10:11:06.419Z"
}
]
}
23
Supported File Types for DLP REST API 2.0 Detection
The following sections list the file types that are supported for detection by the Symantec Data Loss Prevention REST
API.
Word Processing File Types Supported for REST API 2.0 Detection
Multimedia File Types Supported for REST API 2.0 Detection
Spreadsheet File Types Supported for REST API 2.0 Detection
Presentation File Types Supported for REST API 2.0 Detection
Image File Types Supported for REST API 2.0 Detection
Encapsulation File Types Supported for REST API 2.0 Detection
Encryption File Types Supported for REST API 2.0 Detection
Other File Types Supported for REST API 2.0 Detection
24
Word Processing File Types Supported for REST API 2.0 Detection
•
act
•
adobe_maker
•
aes
•
aldus_pagemaker
•
amipro
•
applix_words
•
apple_pages
•
ascii
•
cdf
•
comet
•
dca_rft
•
display_write
•
doc
•
docuworks
•
folio_flat
•
health_level7
•
hwp
•
html
•
macwrite
•
mswrite
•
multimate
•
oasys
•
odt
•
omni_outliner
•
onenote
•
rtf
•
sgml
•
unicode
•
word_pro
•
wordperfect
•
wordstar
•
works
•
writenow
•
xml
•
xywrite
25
Multimedia File Types Supported for REST API 2.0 Detection
•
aiff
•
ac3_audio
•
asf
•
macromedia_flash
•
macromedia_dir
•
midi
•
mp3
•
mpeg_movie
•
qt
•
quickdraw
•
realaudio
•
realmedia
•
riff
•
video_win
•
vrml
•
wav
•
wma
•
wmv
Spreadsheet File Types Supported for REST API 2.0 Detection
•
123
•
applix_spread
•
apple_numbers
•
csv
•
mod
•
ods
•
quattro_pro
•
sylk
•
works_spread
•
xls
•
excel_macros
Presentation File Types Supported for REST API 2.0 Detection
•
apple_keynote
•
corel_pres
•
lotus-fg
•
odp
•
pdf
•
ppt
•
pr2
•
xfdl
•
xps
26
Image File Types Supported for REST API 2.0 Detection
•
ami_draw
•
app_graph
•
bmp
•
cad_draw
•
cat
•
cdd
•
cdr
•
cgm
•
ch3
•
dicom
•
dwg
•
drw
•
emf
•
enc_ps
•
fax_sys
•
freehand
•
gif
•
hpg
•
ico
•
jpg
•
ms_drawing
•
nur
•
pcx
•
pic
•
pict
•
pm_mf
•
png
•
pntg
•
ps
•
sgi_img
•
solid_works
•
svf
•
targa
•
tiff
•
visio
•
wmf
•
wpg
27
Encapsulation File Types Supported for REST API 2.0 Detection
•
7zip
•
binhex
•
bkf
•
bzip2
•
cab
•
compress
•
cpio
•
eml
•
emx
•
encase
•
gz
•
iso
•
lzh
•
lotus-dxl
•
lotus-nsf
•
msg
•
onm
•
pex
•
rar
•
scrap
•
shar
•
stuffit
•
tar
•
tnef
•
uu
•
yenc
•
zip
Encryption File Types Supported for REST API 2.0 Detection
•
encrypted_doc
•
encrypted_nero
•
encrypted_pdf
•
encrypted_ppt
•
encrypted_xls
•
encrypted_zip
•
open-pgp
•
pgp
•
pgpnetshare
28
Other File Types Supported for REST API 2.0 Detection
•
access
•
dbf
•
exe
•
exe_unix
•
fm
•
frame
•
help
•
macbin
•
paradox
•
pcl
•
proj
•
publ
•
qxpress
•
smtp
•
wcm
•
works_db
29
Documentation Legal Notice
This Documentation, which includes embedded help systems and electronically distributed materials, (hereinafter referred
to as the “Documentation”) is for your informational purposes only and is subject to change or withdrawal by Broadcom
at any time. This Documentation is proprietary information of Broadcom and may not be copied, transferred, reproduced,
disclosed, modified or duplicated, in whole or in part, without the prior written consent of Broadcom.
If you are a licensed user of the software product(s) addressed in the Documentation, you may print or otherwise make
available a reasonable number of copies of the Documentation for internal use by you and your employees in connection
with that software, provided that all Broadcom copyright notices and legends are affixed to each reproduced copy.
The right to print or otherwise make available copies of the Documentation is limited to the period during which the
applicable license for such software remains in full force and effect. Should the license terminate for any reason, it is your
responsibility to certify in writing to Broadcom that all copies and partial copies of the Documentation have been returned
to Broadcom or destroyed.
TO THE EXTENT PERMITTED BY APPLICABLE LAW, BROADCOM PROVIDES THIS DOCUMENTATION “AS
IS” WITHOUT WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL
BROADCOM BE LIABLE TO YOU OR ANY THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT,
FROM THE USE OF THIS DOCUMENTATION, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST
INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR LOST DATA, EVEN IF BROADCOM IS EXPRESSLY
ADVISED IN ADVANCE OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE.
The use of any software product referenced in the Documentation is governed by the applicable license agreement and
such license agreement is not modified in any way by the terms of this notice.
The manufacturer of this Documentation is Broadcom Inc.
Provided with “Restricted Rights.” Use, duplication or disclosure by the United States Government is subject to the
restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section 252.227-7014(b)
(3), as applicable, or their successors.
Copyright
©
2005–2023 Broadcom. All Rights Reserved. The term “Broadcom” refers to Broadcom Inc. and/or its
subsidiaries. All trademarks, trade names, service marks, and logos referenced herein belong to their respective
companies.
30
