Programmer s Guidelines for Writing a Third-Party Ticketing Plug-In

Transcription

1 IBM Proventia Management SiteProtector Programmer s Guidelines for Writing a Third-Party Ticketing Plug-In May 19, 2009 Overview Introduction The SiteProtector application contains a built-in ticketing system and includes a thirdparty ticketing API. With the API, a third-party plug-in writer can create a plug-in that allows tickets created in SiteProtector to be managed by a third-party ticketing system. Scope This document provides high-level guidelines for using the ticketing plug-in API. For details, see the IBM ISS Ticketing Plug-In API Specification, available in Javadoc format on the IBM ISS Web site at docs.php?product=16&family=8. Audience This document is intended for experienced Java developers. To use this document, you need a working knowledge of SiteProtector and an in-depth knowledge of the integration details of your third-party ticketing system. Support for Remedy The ticketing API was used to implement a plug-in for the BMC Remedy Action Request System. That plug-in comes with SiteProtector. For information about using the plug-in, download the Integration Notes document for IBM ISS from the partners pages on the BMC Software, Inc., Web site. In this document This document contains the following sections: Section Page Section A, "Implementing the Ticketing Plug-In" 3 Section B, "Integrating the Ticketing Plug-In" 9 Section C, "Implementation Example" 13 IBM Internet Security Systems 1

2 Programmer s Guidelines for Writing a Third-Party Ticketing Plug-In 2

3 SECTION A: Implementing the Ticketing Plug-In Overview Introduction The ticketing plug-in interface (IssTicketingUtils in the net.iss.rssp.ticketing. plugin.interfaces package) is the extension point for the plug-in writer. You can use the methods in this interface to do the following: create tickets for asset, agent, and agent analysis data customize the selections available in the IBM ISS ticketing system For example, you can insert, update, or delete selections for status, category, and priority so that they match the selections available in your ticketing system. Component architecture Figure 1 illustrates the relationship between SiteProtector and the ticketing components: Figure 1: Third-party ticketing plug-in component architecture Requirements To implement the ticketing plug-in, you must do the following: Define a class for the ticketing plug-in interface. Define a class constructor and implement the initialize method. Implement the create ticket methods: host agent agent analysis data Refer to the IBM ISS Ticketing Plug-In API Specification for details. In this section This section contains the following topics: Topic Page Define a Class for the Ticketing Plug-In Interface 4 Implement the Initialize Method 4 Implement the Create Ticket Methods 5 Incorporate Supplemental Host or Component Data into Tickets 7 3

4 Programmer s Guidelines for Writing a Third-Party Ticketing Plug-In Define a Class for the Ticketing Plug-In Interface Requirement Define a class implementing the net.iss.rssp.ticketing. interfaces.ticketingplugin interface. Implement the Initialize Method Introduction The IssTicketingUtils interface provides access to information in the IBM ISS ticketing system. Use the initialize method to load configuration files and to create a connection to the third-party ticketing system. Procedure Do the following: Define a class constructor with no arguments and implement the initialize method. Important: The initialize method should accept the IssTicketingUtils interface in the net.iss.rssp.ticketing.plugin.interface package as input. Example Use this example as a guide for implementing the initialize method: public void initialize (IssTicketingUtils utils) throws PluginException try String configfile = utils.getconfigdirectory() + File.separator + PLUGIN_CONFIG_FILENAME; loadconfig(configfile); verifyuser(); catch (Exception e) throw new PluginException(e.getMessage()); 4

5 Implement the Create Ticket Methods Implement the Create Ticket Methods Introduction The create ticket methods are the main entry points for the flow of data between the IBM ISS ticketing system and a third-party ticketing system. This topic explains the methods you use to create tickets and describes the data available to include in the tickets. Using supplemental data The create ticket methods described in this topic create tickets with data from the SiteProtector database. For methods that incorporate supplemental data, see Incorporate Supplemental Host or Component Data into Tickets on page 7. Ticket methods The following table describes the createticket methods to use for the types of tickets you can create: Type of Ticket asset agent agent analysis data (described as the sensor analysis data ticket in the Javadoc) Create Ticket Method createticket (TicketDetail, TicketFilterHosts) createticket (TicketDetail, TicketFilterComponents) createticket (TicketDetail, TicketFilterSensorData) Requirement The create ticket methods should return a reference to the ticket ID that is created in the third-party ticketing system. SiteProtector maps its ticket ID to the third-party ticket ID. Data available in the TicketDetail object Use the TicketAppendedData class from the TicketDetail object to access ticket details ticket, agent, and agent analysis data. The ticket details are stored in the TicketAppendedData as a TicketAVP map object. The following table describes the attribute-value pairs for each type of ticket: Asset Tickets Agent Tickets Agent Analysis Data Tickets Asset Criticality Asset Function ID Asset Function Asset ID Asset Owner Asset Owner ID Domain Host Comments DNS Name Host ID Host IP Address Host Name Host NB Domain Host OS Name Host Owner Inventory Tag Agent Name Asset Criticality Asset Owner Component ID Component Status Component Version DNS Name Event Collector Name Host IP Address Host Name Last Heartbeat Time Policy Policy Group ID Role ID XPU State Agent DNS Name Event Count Event Tag Name Event Time Object Name Object Type Severity Source IP Address Source Port Target IP Address User Name Vulnerability Status 5

6 Programmer s Guidelines for Writing a Third-Party Ticketing Plug-In Asset Tickets Agent Tickets Agent Analysis Data Tickets IPV6 Display String Network Interface ID OS Owner Protection Example: retrieve agent details The following example uses the createticket method to retrieve agent details from TicketAppendedData: public String createticket ( TicketDetail ticket, TicketFilterComponents filter ) try List<TicketAppendedData> component_data = ticket.getappendeddata(); //code to create custom ticket // using ticket details and component_data return foreign_ticket_id; catch ( Exception e ) throw new PluginException( e.getmessage() ); 6

7 Incorporate Supplemental Host or Component Data into Tickets Incorporate Supplemental Host or Component Data into Tickets Introduction The create ticket methods described earlier access data from only the host and component (agent) tables in the SiteProtector database. You can include supplemental host and component data in tickets if you provide the data in another file or database. You would then use the methods in this topic to create tickets using your supplemental data sources. Requirement When you add supplemental data to a ticket, you must use the SiteProtector Asset ID or Component ID to identify the asset or component. Methods for asset and agent tickets The following table describes the methods to use when you have supplemental data. Use the IssTicketingUtils interface passed into the initialize method as follows: Type of Ticket Method to Extract Data Data Location asset createticket (TicketDetail, TicketFilterHosts) gettickethostsbyidlist(string, String) in the IssTicketingUtils interface The asset ID information is encapsulated in the TicketFilterHosts data object. Refer to the TicketHost class in the API Specifications for more details. agent createticket (TicketDetail, TicketFilterCompo nents) getticketcomponentsbyidlist( String, String) in the IssTicketingUtils interface The component ID information is encapsulated in the TicketFilterComponents data object. Refer to the TicketComponent class in the API Specifications for more details. Example: retrieve asset details The following example uses the createticket method, which uses the gettickethostsbyidlist method, to retrieve asset details: public String createticket ( TicketDetail ticket, TicketFilterHosts filter ) try List<TicketHost> host_data = IssTicketingUtils.getTicketHostsByIdList( filter.getcommaseparatedlist() ); //code to create custom ticket // using ticket details and host_data return foreign_ticket_id; catch ( Exception e ) throw new PluginException( e.getmessage() ); 7

8 Programmer s Guidelines for Writing a Third-Party Ticketing Plug-In 8

9 SECTION B: Integrating the Ticketing Plug-In Overview Introduction This section explains how to integrate the plug-in you have written with the IBM ISS ticketing system. Perform the tasks in this topic in the order in which they are given. In this section This section contains the following topics: Topic Page Task 1: Configuring and Copying Plug-In Files 10 Task 2: Activate the Ticketing Plug-In 11 9

10 Programmer s Guidelines for Writing a Third-Party Ticketing Plug-In Task 1: Configuring and Copying Plug-In Files Introduction The first steps for integrating the ticketing plug-in are as follows: 1. Create a plug-in JAR (Java Archive) file that contains the libraries and Java classes that your third-party plug-in references. 2. Copy this file and any other required configuration files to the Application Server. Prerequisite Find the value of the following registry key: HKEY_LOCAL_MACHINE_\SOFTWARE\ISS\SiteProtector\Application Server\Home Procedure To configure and copy plug-in files: 1. Create a plug-in JAR file that contains the required libraries and Java classes. 2. On the computer where the SiteProtector Application Server is installed, copy the plug-in JAR file to the following directory: SiteProtector Version SiteProtector 2 SP 7.0 and later SiteProtector 2 SP 6.1 and earlier Directory value_of_registry_key\deployedapps\iss\siteprotector.ear\lib value_of_registry_key\webserver\jboss\server\ default\deploy\ SiteProtector.ear\startup.sar 3. Copy configuration files to the following directory: value_of_registry_key\config 4. Restart the Application Server computer. 10

11 Task 2: Activate the Ticketing Plug-In Task 2: Activate the Ticketing Plug-In Introduction After you have created and added the required files to the Application Server, you must enable the ticketing plug-in. You can enable the plug-in from any SiteProtector Console. Prerequisites To activate the plug-in, you must have the following: the exact name of the class that is implementing the IssTicketingUtils interface an account with Administrator privileges Loading the Plug-in To enable the plug-in: 1. On the Tools menu in the SiteProtector Console, select Ticketing Setup. 2. Select the Plug-In tab. 3. Click Add. 4. Provide the following information about the plug-in: Field Class Name Name Description Description The exact name of the class that is implementing the TicketingPlugin interface. An optional name for this plug-in. An optional description of this plug-in. 5. Click OK. 6. Select the plug-in that you added in Step 4, and then click Activate. Identifying errors If the plug-in loads without error, a ticket created within SiteProtector should create a ticket in the third-party ticketing system. To identify errors in loading the plug-in, do the following: 1. Find the value of the following registry key: HKEY_LOCAL_MACHINE\SOFTWARE\ISS\SiteProtector\Console\Home 2. Check the spconsole_trace.txt file in the value_of_registry_key\bin directory. 11

12 Programmer s Guidelines for Writing a Third-Party Ticketing Plug-In 12

13 SECTION C: Implementation Example Overview Introduction This section provides an example of a simple implementation of the ticketing API. It includes the Java implementation and the XML support file used by the Java code. In this section This section contains the following topics: Topic Page Example of Java Implementation 14 XML Support File for the Java Implementation Example 19 13

14 Programmer s Guidelines for Writing a Third-Party Ticketing Plug-In Example of Java Implementation package net.iss.ticketing.plugin; import net.iss.rssp.ticketing.plugin.interfaces.*; import net.iss.rssp.ticketing.plugin.utils.pluginexception; import net.iss.rssp.ticketing.service.entity.*; import net.iss.util.xmlutil; import java.util.*; import java.io.file; import java.io.fileinputstream; import java.io.ioexception; import java.io.filewriter; import org.jdom.document; import org.jdom.element; /** * Sample implementation of ticketing plugin. */ public class PluginTester implements TicketingPlugin IssTicketingUtils ticketingutils = null; private static String struser; private static String strpassword; private static String strlocale; private static String strserver; private static String PLUGIN_CONFIG_FILENAME = "TestPluginConfig.xml"; //Config file XML Tag public static final String PLUGIN_CONFIG = "test-plugin-config"; public static final String PLUGIN_DISPLAY_NAME = "display-name"; public static final String PLUGIN_DESCRIPTION = "description"; public static final String PLUGIN_VERSION = "version"; public static final String PLUGIN_USER = "plugin-user"; public static final String USER = "user"; public static final String PASSWORD = "password"; public static final String LOCALE = "locale"; public static final String SERVER = "server"; public static final String ENCRYPTED_PASSWORD="encrypt-password"; public static final String ENCRYPT_FILE = "encrypt-file"; private static int AGENT_TICKET_COUNTER = 1; private static int ASSET_TICKET_COUNTER = 1; private static int AGENT_ANALYSIS_TICKET_COUNTER = 1; public PluginTester() public void initialize(issticketingutils utils) throws PluginException setissnativeutils(utils); try 14

15 Example of Java Implementation String configfile = ticketingutils.getconfigdirectory() + File.separator + PLUGIN_CONFIG_FILENAME; loadconfig(configfile); verifyuser(); catch (Exception are) throw new PluginException(are.getMessage()); private Document configdocument = null; private void loadconfig(string filename) throws PluginException try configdocument = XmlUtil.parse(new FileInputStream(new File(filename))); Element root = configdocument.getrootelement(); Element serveruser = root.getchild(plugin_user); struser = serveruser.getattributevalue(user); strpassword = serveruser.getattributevalue(password); String strencrypted = serveruser.getattributevalue(encrypted_password); boolean bencrypted = Boolean.valueOf(strEncrypted); if(bencrypted) strpassword = ticketingutils.getencryptedentry(strpassword, serveruser.getattributevalue(encrypt_file)); strlocale = serveruser.getattributevalue(locale); if (strlocale == null strlocale.trim().equals("")) strlocale = Locale.getDefault().getLanguage(); strserver = serveruser.getattributevalue(server); catch (Throwable e) e.printstacktrace(); throw new PluginException(e); public void verifyuser() throws Exception public void setissnativeutils(issticketingutils ticketingutils) this.ticketingutils = ticketingutils; public IssTicketingUtils getissnativeutils() return ticketingutils; public String createticket(ticketdetail ticket, TicketFilterHosts filterhosts) throws PluginException String foreignticketid = "Plugin Host Ticket-" + ASSET_TICKET_COUNTER++; return foreignticketid; 15

16 Programmer s Guidelines for Writing a Third-Party Ticketing Plug-In public String createticket(ticketdetail ticket, TicketFilterComponents filtercomponents) throws PluginException String foreignticketid = "Plugin Component Ticket-" + AGENT_TICKET_COUNTER++; return foreignticketid; public String createticket(ticketdetail ticket, TicketFilterSensorData filtersensordata, String principalidlist) throws PluginException String foreignticketid = "Plugin SensorData Ticket-" + AGENT_ANALYSIS_TICKET_COUNTER++; return foreignticketid; public List<TicketCategory> getallticketingcategories() throws PluginException return ticketingutils.getnativeticketingcategories(); public TicketCategory addnewticketingcategory(ticketcategory category) throws PluginException return ticketingutils.addnativeticketingcategory(category); public TicketCategory updateticketingcategory(ticketcategory category) throws PluginException return ticketingutils.updatenativeticketingcategory(category); public void deleteticketingcategory(ticketcategory category) throws PluginException ticketingutils.deletenativeticketingcategory(category); public List<TicketPriority> getallticketingpriorities() throws PluginException return ticketingutils.getnativeticketingpriorities(); public TicketPriority addnewticketingpriority(ticketpriority priority) throws PluginException return ticketingutils.addnativeticketingpriority(priority); public void updateticketingpriority(ticketpriority priority) throws PluginException ticketingutils.updatenativeticketingpriority(priority); public void deleteticketingpriority(ticketpriority priority) throws PluginException ticketingutils.deletenativeticketingpriority(priority); 16

17 Example of Java Implementation public List<TicketStatus> getallticketingstatus() throws PluginException return ticketingutils.getnativeticketingstatuses(); public TicketStatus addnewticketingstatus(ticketstatus status) throws PluginException return ticketingutils.addnativeticketingstatus(status); public void updateticketingstatus(ticketstatus status) throws PluginException ticketingutils.updatenativeticketingstatus(status); public void deleteticketingstatus(ticketstatus status) throws PluginException ticketingutils.deletenativeticketingstatus(status); public static long converttolong(string string) if (string == null string.trim().equals("")) return 0; return Long.valueOf(string).longValue(); public String getstatusfromid(string statusid) try List<TicketStatus> list = getallticketingstatus(); for (TicketStatus status : list) if (status.getid().equalsignorecase(statusid)) return status.getname(); return statusid; catch (PluginException e) return statusid; public String getpriorityfromid(string priorityid) try List<TicketPriority> list = getallticketingpriorities(); for (TicketPriority p : list) if (p.getid().equalsignorecase(priorityid)) return p.getname(); 17

18 Programmer s Guidelines for Writing a Third-Party Ticketing Plug-In return priorityid; catch (PluginException e) return priorityid; 18

19 XML Support File for the Java Implementation Example XML Support File for the Java Implementation Example <?xml version="1.0" encoding="utf-8"?> <test-plugin-config version ="1.0" display-name="test Plugin" description="the plugin for Test system version 6.3"> <plugin-user user='admin' password='newuser' locale='' server='puddy.msqa.qatest.iss.net' encrypt-password="false" encrypt-file="add.properties"/> </test-plugin-config> 19

20 Programmer s Guidelines for Writing a Third-Party Ticketing Plug-In Copyright IBM Corporation 1994, All Rights Reserved. IBM and the IBM logo are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. ADDME, Ahead of the threat, BlackICE, Internet Scanner, Proventia, RealSecure, SecurePartner, SecurityFusion, SiteProtector, System Scanner, Virtual Patch, X-Force and X-Press Update are trademarks or registered trademarks of Internet Security Systems, Inc. in the United States, other countries, or both. Internet Security Systems, Inc. is a wholly-owned subsidiary of International Business Machines Corporation. Microsoft, Windows, and Windows NT are trademarks of Microsoft Corporation in the United States, other countries, or both. Other company, product and service names may be trademarks or service marks of others. References in this publication to IBM products or services do not imply that IBM intends to make them available in all countries in which IBM operates. 20