Symantec™ Data Loss Prevention Incident Reporting and Update API Code Examples
Symantec™ Data Loss Prevention Incident Reporting and Update API Code Examples
Prevention Incident
Reporting and Update API
Code Examples
Version 15.5
Symantec Data Loss Prevention Incident Reporting
and Update API Examples
Documentation version: 15.5b
Legal Notice
Copyright © 2018 Symantec Corporation. All rights reserved.
Symantec, CloudSOC, Blue Coat, the Symantec Logo, the Checkmark Logo, the Blue Coat logo, and the
Shield Logo are trademarks or registered trademarks of Symantec Corporation or its affiliates in the U.S.
and other countries. Other names may be trademarks of their respective owners.
This Symantec product may contain third party software for which Symantec is required to provide attribution
to the third party (“Third Party Programs”). Some of the Third Party Programs are available under open
source or free software licenses. The License Agreement accompanying the Software does not alter any
rights or obligations you may have under those open source or free software licenses. Please see the
Third Party Legal Notice Appendix to this Documentation or TPIP ReadMe File accompanying this Symantec
product for more information on the Third Party Programs.
The product described in this document is distributed under licenses restricting its use, copying, distribution,
and decompilation/reverse engineering. No part of this document may be reproduced in any form by any
means without prior written authorization of Symantec Corporation and its licensors, if any.
THE DOCUMENTATION IS PROVIDED "AS IS" AND ALL EXPRESS OR IMPLIED CONDITIONS,
REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE
DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY
INVALID. SYMANTEC CORPORATION SHALL NOT BE LIABLE FOR INCIDENTAL OR CONSEQUENTIAL
DAMAGES IN CONNECTION WITH THE FURNISHING, PERFORMANCE, OR USE OF THIS
DOCUMENTATION. THE INFORMATION CONTAINED IN THIS DOCUMENTATION IS SUBJECT TO
CHANGE WITHOUT NOTICE.
The Licensed Software and Documentation are deemed to be commercial computer software as defined
in FAR 12.212 and subject to restricted rights as defined in FAR Section 52.227-19 "Commercial Computer
Software - Restricted Rights" and DFARS 227.7202, et seq. "Commercial Computer Software and
Commercial Computer Software Documentation," as applicable, and any successor regulations, whether
delivered by Symantec as on premises or hosted services. Any use, modification, reproduction release,
performance, display or disclosure of the Licensed Software and Documentation by the U.S. Government
shall be solely in accordance with the terms of this Agreement.
Symantec Corporation
350 Ellis Street
Mountain View, CA 94043
http://www.symantec.com
Contents
Note: To simplify the code, these examples use relaxed security implementations that are not
appropriate for production environments. For more information and sample code that
demonstrate securing your client applications, see "Authenticating a client with the Incident
Reporting and Update API Web Service" in the Symantec Data Loss Prevention Incident
Reporting and Update API Developers Guide.
Both the source code and complied classes are provided for the examples. For Java clients,
a build script is provided to build the examples from the source code. For .NET examples, a
Introducing the Incident Reporting and Update API Examples 6
About updates to this guide
Microsoft Visual Studio project file is provided. Instructions for running the examples, including
the required arguments are provided in this document.
To run these examples, you must have a functional installation of Symantec Data Loss
Prevention 15.5. The Enforce Server must be accessible over a network from the computer
where you run the examples.
Table 1-1
Date Description
6 September Added detailed information about the correct formats for user names.
2019
Note: Refer to the "Troubleshooting Incident Reporting and Update API client applications"
section of the API guide for up-to-date information about implementing clients using the current
release.
remediation process, or to support business processes that rely on Symantec Data Loss
Prevention incidents.
A Symantec Data Loss Prevention incident records all of the details that are associated with
a message that violated a Data Loss Prevention policy. A message in this context may refer
to an email message, an instant message, a file transfer, a copy or a print operation, an HTTP
request, or any other protocol message that you have configured Symantec Data Loss
Prevention to monitor. The data that is recorded in an incident includes the time the violation
occurred, the severity of the violation, and information about the originator and recipient of the
message that triggered the violation. Incidents also record data such as the text and headers
of the original message and files that were attached to the original message. Finally, an incident
may also contain historical data that is associated with efforts to remediate the incident in the
Enforce Server administration console. This historical data includes changes to the incident
severity or status and a list of any actions that were performed to help resolve or manage the
incident.
For example, you can use the API to correlate Symantec Data Loss Prevention incident data
with logs of the message sender’s telephone calls or network usage. Or, you can create
dashboard applications that integrate Symantec Data Loss Prevention incident data with data
from other systems, such as intrusion detection systems. By using the update functionality of
the API, you can create applications that perform custom remediation actions and then update
the results of the remediation in the Symantec Data Loss Prevention incident database. The
combined information from third-party systems and Symantec Data Loss Prevention, and the
ability to update the status of incidents, can provide valuable information to security experts
who are tasked with analyzing the data or with remediating security incidents.
The Incident Reporting and Update API is implemented as a Web Service that resides on the
Enforce Server. The Web Service conforms to the Simple Object Access Protocol (SOAP) 1.1
standard, and it advertises all available operations using a Web Services Description Language
(WSDL) document. You can use the WSDL document with compatible Web Services
development frameworks to generate certain client code automatically. Generated proxy code
for Java clients is also provided with your Symantec Data Loss Prevention installation.
Chapter 2
Java examples
This chapter includes the following topics:
File Description
File Description
Table 2-2 describes where to find Java implementations of the various Web service methods
that are defined by the Incident Reporting and Update API WSDL.
Java examples 10
Building the Java examples
The command outputs incident data and returns a status message to standard out.
To run the Update client Java program, run the following command, and add additional
arguments from Table 2-4 as required.
java -jar SampleReportingAPI-2.0.jar URL =
Enforce_Server/ProtectManager/services/v2011/incidents?wsdl USER=user
PASSWORD=password
The command updates the incident data and returns a status message to standard out.
For example, the following command line updates the NOTE_TEXT field for the incident whose
ID is 2:
java -jar SampleReportingAPI-2.0.jar URL=
Enforce_Server/ProtectManager/services/v2011/incidents?wsdl USER=user
PASSWORD=password INCIDENT_ID=2 NOTE_TEXT="My note"
WSDL connection URL URL for the WSDL hosted on the Enforce Server:
https://Enforce_Server
/ProtectManager/services/v2011/incidents?wsdl
WSDL connection USER User name with permission to perform the requested
operation. The correct user formats are as follows:
Read incident list REPORT_ID Specifies the ID of the saved report to execute on the
Enforce Server. Created this report using the Enforce
Server administration console before you execute the
Web Service call.
Read incident list DATE_LATER_THAN Constrains the list of returned incident IDs to include
only incidents created after this date.
Read incident details GET_HISTORY When set to TRUE, returns incident history details.
Read incident details GET_VIOLATIONS When set to TRUE, returns incident violation details.
Read incident message GET_ALL_COMPONENTS When set to TRUE, returns all incident components
and binary attachments (optional).
Read incident message GET_ORIGINAL_MESSAGE When set to TRUE, returns the original message of the
and binary attachments incident (optional).
Read image violations GET_IMAGE_VIOLATIONS When set to TRUE, returns all image violations (optional).
WSDL connection URL URL for the WSDL hosted on the Enforce Server:
https://Enforce_Server
/ProtectManager/services/v2011/incidents?wsdl
Java examples 13
Running the Java examples
WSDL connection USER User name with permission to perform the requested
operation. The correct user formats are as follows:
Update incident details DATA_OWNER_NAME Sets the data owner name value.
Update incident details DATA_OWNER_EMAIL Sets the data owner email value.
Java examples 14
Running the Java examples
Update the value of a CUSTOM_custom sets the value of a named custom attribute. Use the
custom attribute attribute_name following form:
CUSTOM_myAtttributeName=myValue
Retrieve list of custom FETCH_PARAM To retrieve a list of custom attributes, set the value to:
attributes
CUSTOM_ATTRIBUTES
INCIDENT_STATUSES
Chapter 3
.NET Examples
This chapter includes the following topics:
File Description
The file Program.cs is the main class for the Update client.
File Description
The file Program.cs is the main class for the Update client.
Table 3-2 describes where to find .NET implementations of the various Web service methods
that are defined by the Incident Reporting and Update API WSDL.
■ Update client:
\SampleClients\dot_net\UpdateAPISample\UpdateAPISample.sln
The command outputs incident data and returns a status message to standard out.
To run the Update client .NET program, run the following command, and add additional
arguments from Table 3-4 as required.
C:\Sample_Clients\Sample Clients\dot_net\UpdateAPISample\UpdateAPI.exe
URL=Enforce_Server/ProtectManager/services/v2011/incidents USER=user
PASSWORD=password
The command updates the incident data and returns a status message to standard out.
For example, the following command line updates the NOTE_TEXT field for the incident whose
ID is 2:
C:\Sample_Clients\Sample Clients\dot_net\UpdateAPISample\UpdateAPI.exe
URL=Enforce_Server/ProtectManager/services/v2011/incidents USER=user
PASSWORD=password INCIDENT_ID=2 NOTE_TEXT="My note"
WSDL connection URL URL for the WSDL hosted on the Enforce Server:
https://Enforce_Server
/ProtectManager/services/v2011/incidents
.NET Examples 19
Running the .NET examples
WSDL connection USER User name with permission to perform the requested
operation. The correct user formats are as follows:
Read incident list REPORT_ID Specifies the ID of the saved report to execute on the
Enforce Server. Create this report with the Enforce
Server administration console before you execute the
Web Service call.
Read incident list DATE_LATER_THAN Constrains the list of returned incident IDs to include
only incidents that were created after this date.
Read incident details GET_HISTORY When set to TRUE, returns incident history details.
Read incident details GET_VIOLATIONS When set to TRUE, returns incident violation details.
Read incident message GET_ALL_COMPONENTS When set to TRUE, returns all incident components.
and binary attachments (optional)
Read incident message GET_ORIGINAL_MESSAGE When set to TRUE, returns the original message of the
and binary attachments incident.(optional).
Read image violations GET_IMAGE_VIOLATIONS When set to TRUE, returns all image violations (optional).
WSDL connection URL URL for the WSDL hosted on the Enforce Server:
https://Enforce_Server
/ProtectManager/services/v2011/incidents
WSDL connection USER User name with permission to perform the requested
operation. The correct user formats are as follows:
Update incident details DATA_OWNER_NAME Sets the data owner name value.
Update incident details DATA_OWNER_EMAIL Sets the data owner email value.
Update the value of a CUSTOM_custom attribute sets the value of a named custom attribute. Use the
custom attribute name following form:
CUSTOM_myAtttributeName=myValue
Retrieve list of custom FETCH_PARAM To retrieve a list of custom attributes, set the value to:
attributes
CUSTOM_ATTRIBUTES
INCIDENT_STATUSES