SN66: APIs, SDK and Service-Oriented

Architecture in ArcSight ESM

Yanlin Wang
Software Architect
September 2010

2010 ArcSight, Inc. All rights reserved.

ArcSight and the ArcSight logo are trademarks of ArcSight, Inc. All other product and company names may be trademarks or registered trademarks of their respective owners.
www.arcsight.com

2010 ArcSight Confidential

Overview

This session will be geared towards the advance ArcSight ESM

user, system integrator, ISV, etc.

To learn how to programmatically consume ArcSight ESM

functionalities
Run report in your portal
Retrieve ArcSight ESM resource data
Coding required

www.arcsight.com

2010 ArcSight Confidential

Agenda

Server architecture overview

ArcSight ESM service layer

SDK & development environment

Developing ArcSight ESM application

www.arcsight.com

2010 ArcSight Confidential

Server Architecture Overview

www.arcsight.com

2010 ArcSight Confidential

Server Architecture Overview

ArcSight ESM The Open Platform

Plugin
DM
Plugin
DM
ESM Plugin

ESM Open Platform

Web 2.0 Client

www.arcsight.com

Web Service Client

JMX-WS/WSMan Client

2010 ArcSight Confidential

iPhone/iPad

Server Architecture Overview

Demo

www.arcsight.com

2010 ArcSight Confidential

Server Architecture Overview

Server Architecture

Next generation J2EE technology ArcSight DM Framework

ArcSight ESM service layer enterprise SOA platform

Expose ArcSight ESM functionalities to web services: SOAP,
REST/JSON, REST/XML, GWTRPC, etc.
SDK

New management tools

ArcSight DM console
Remote JMX tool

www.arcsight.com

2010 ArcSight Confidential

Server Architecture Overview

ArcSight ESM Manager Components Diagram

ESM Service Layer

Dynamic Modules

ESM Manager
Server DM

Plugin DM
Plugin DM
Plugin DM

ArcSight DM Framework
ArcSight DM
Core Services

J2EE Container DM
Service

ArcSight DM
Service Extention

Equinox (OSGI)

JVM
www.arcsight.com

2010 ArcSight Confidential

ArcSight ESM Service Layer

www.arcsight.com

2010 ArcSight Confidential

ArcSight ESM Service Layer

What is ArcSight ESM Service Layer

A SOA platform
Expose ArcSight ESM functionalities to web services

Provides a suite of loosely coupled services with multiple

protocols
SOAP, REST (XML/JSON), GWTRPC, JMX-WS (WS-Man), etc.

Options to consume the ArcSight ESM service

By Java service client API (ArcSight ESM SDK)
SOAP Client API
RESTful Scripts
GWTRPC Client API

By protocol
WSDL

www.arcsight.com

2010 ArcSight Confidential

10

ArcSight ESM Service Layer

Service Implementation

ArcSight ESM Manager

ArcSight ESM Service Layer
AXIS2
JAXWS

SOAP

www.arcsight.com

Jersey
JAXRS1.0

GWTRPC

JSR262
RI

REST/J
SON,
XML

GWT
RPC

JMXW
S

2010 ArcSight Confidential

11

ArcSight ESM Service Layer

General Steps of Consuming Service

Login through LoginService and get auth token

Use auth token to consume services

www.arcsight.com

2010 ArcSight Confidential

12

ArcSight ESM Service Layer

Example of Consuming Service via REST XML (1 of 3)

Login and get auth token

https://myhost:8443/www/coreservice/rest/LoginService/login?login=admin&password=password

www.arcsight.com

2010 ArcSight Confidential

13

ArcSight ESM Service Layer

Example of Consuming Service via REST XML (2 of 3)

Search a data monitor with text string (Same function as console

full text search)
https://myhost:8443/www/managerservice/rest/ManagerSearchService/search1?authToken=hudcmyGWT
hlIGhJtWr9ZZxUZvvT9gIhKpTg4S8QHgPw.&queryStr=datamonitor
event throughput&pageSize=50

www.arcsight.com

2010 ArcSight Confidential

14

ArcSight ESM Service Layer

Example of Consuming Service via REST (3 of 3)

Get the detailed resource data

https://myhost:8443/www/managerservice/rest/ResourceService/findByUUID?authToken=hudcmyGWThlI
GhJtWr9ZZxUZvvT9gIhKpTg4S8QHgPw.&id=C6G3MNPMAABCAbTjj
DsBRuQ==

www.arcsight.com

2010 ArcSight Confidential

15

ArcSight ESM Service Layer

Service Layer in ArcSight ESM 5.0

SOA infrastructure
ArcSight ESM 5.0 Services
ArchiveReportService
ManagerSearchService
ResourceService
DashboardService
Currently Service Layer provides service around following resources
ArchiveReport
Dashboard
DataMonitor
FileResource
Portlet
Report
Basic Resource (contains attributes share among all resources)
Resource Reference
ViewerConfigurarion

www.arcsight.com

2010 ArcSight Confidential

16

ArcSight ESM Service Layer

How to Find Out Services

https://myhost:8443/www/manager-service/services/listServices

www.arcsight.com

2010 ArcSight Confidential

17

ArcSight ESM Service Layer

How to Find Out WSDL

https://myhost:8443/www/managerservice/services/servicename?wsdl

www.arcsight.com

2010 ArcSight Confidential

18

SDK & Development Environment

www.arcsight.com

2010 ArcSight Confidential

19

SDK & Development Environment

ArcSight ESM Service Layer SDK

SDK is a set of tools and libraries provided for software

developers to create their own application which consumes
services provided by ArcSight ESM service layer

SDK contains SOAP and GWTRPC client Java API

Generate report
Full text search
Retrieve resource data

SDK is installed within ArcSight ESM manager

$ARCSIGHT_HOME/utilites/sdk/lib
Service client API libraries
Java doc are located

www.arcsight.com

2010 ArcSight Confidential

20

SDK & Development Environment

Setup JDK

Install JDK 1.6.0_17 or above

Import ArcSight ESM managers CA cert or self signed cert to

jdk/lib/security/cacerts
self signed certificate with ip address in CN will get exception
java.security.cert.CertificateException: No subject
alternative names present
Wrong CA cert or self signed cert will get exception
sun.security.validator.ValidatorException: PKIX path
building failed

www.arcsight.com

2010 ArcSight Confidential

21

SDK & Development Environment

Setup IDE Eclipse

Add user libraries

Preferences->Java->Build Path->Classpath Variables
Create Variable (eg. ESM_SDK_LIB) pointing to
$ARCSIGHT_HOME/utilites/sdk/lib

User JDK 1.6.0_17 as default JDK

Create new project

Add SDK library jar files to project build path
Project->properties->Java Build Path->Libraries->Add Variable
Choose ESM_SDK_LIB -> Extend
Add all SDK library jar files

www.arcsight.com

2010 ArcSight Confidential

22

Developing ArcSight ESM Application

www.arcsight.com

2010 ArcSight Confidential

23

Developing ArcSight ESM Application

Example of Consuming Service

via SOAP Client API Provided in SDK (Slide 1 of 2)
// =================================================
// Invoke Login Service
// =================================================
// construct LoginServiceFactory (LoginService is part of core service
// module)
LoginServiceClientFactory loginServiceClientFactory = new LoginServiceClientFactory();
// set the service base url. ESMs service base url is
// https://host:port/www/
System.setProperty("com.arcsight.coma.client.ws.baseURL",
"https://yanlinwang-pc:8443/www/");
// loginServiceClientFactory.setBaseURL("https://10.4.21.186:8443/www/");
// create service client instance from factory
LoginService loginService = loginServiceClientFactory.createClient();
// invoke login service and get authToken
String authToken = loginService.login(null, "admin", "password");

www.arcsight.com

2010 ArcSight Confidential

24

Developing ArcSight ESM Application

Example of Consuming Service

via SOAP Client API Provided in SDK (Slide 2 of 2)
// =================================================
// Invoke Archive Report Service
// =================================================
ArchiveReportServiceClientFactory archiveReportServiceClientFactory = new ArchiveReportServiceClientFactory();
// create service client instance from factory
ArchiveReportService archiveReportService = archiveReportServiceClientFactory
.createClient();
// invoke report service to create achiveReport by a reported, the
// return will be archive report file id, you can use that to download
// report.
String fileId = archiveReportService
.initDefaultArchiveReportDownloadByURI(
authToken,
"/All Reports/ArcSight Administration/ESM/Configuration Changes/Resources/Resource Updated Report",

"Manual");
// Download report using the download job id
download(
new URL(
"https://yanlinwang-pc:8443/www/manager-service/fileservlet?file.command=download&file.id="
+ fileId), "Resources Updated Report.html");

www.arcsight.com

2010 ArcSight Confidential

25

Developing ArcSight ESM Application

APIs

ArchiveReportService generate archive report

ManagerSearchService full text search resources

DashboardService retrieve dashboard data

ResourceService retrieve resource data

InfoService retrieve manager server info

www.arcsight.com

2010 ArcSight Confidential

26

Developing ArcSight ESM Application

Documents
Find ArcSight ESM web
services API in
$ARCSIGHT_HOME/utilites/sdk/lib
/manager-javadoc1.0.0.release.xxx.jar

Extract jar file into a folder

Open index.html in the
extracted folder with web
browser
Get SDK development guide
from support

www.arcsight.com

2010 ArcSight Confidential

27

Developing ArcSight ESM Application

Test and Debug

Check ArcSight ESM manager log

Use browser and REST URL to test

Write unit test before integrating into the system

www.arcsight.com

2010 ArcSight Confidential

28

Developing ArcSight ESM Application

Consuming Service
via REST Programmatically (Slide 1 of 4)

Pros
Simple
No need to setup SDK libraries
Return data will be XML/JSON

Cons
Not strong typed
Not suitable for large application

www.arcsight.com

2010 ArcSight Confidential

29

Developing ArcSight ESM Application

Consuming Service
via REST Programmatically (Slide 2 of 4)
/**
* generate ESM REST service URL based on parameters
*
* @param moduleName - ESM service module (eg. manager-service)
* @param serviceName - ESM service name (eg. ManagerSearchService)
* @param methodName - service method name (eg. search1)
* @param params - REST service parameters
* @return url string
*/
public static String getRestUrl (String moduleName, String serviceName, String methodName, HashMap<String, String> params)
{
String url = "https://yanlinwang-pc:8443/www/" + moduleName + "/rest/" + serviceName + "/" + methodName;

boolean questionMark = false;

for (Entry<String, String> param : params.entrySet()){
if (!questionMark) {
url = url + "?" + param.getKey() + "=" + new String(URLEncoder.encode(param.getValue()));
questionMark = true;
} else {
url = url + "&" + param.getKey() + "=" + new String(URLEncoder.encode(param.getValue()));
}
}
return url;
}

www.arcsight.com

2010 ArcSight Confidential

30

Developing ArcSight ESM Application

Consuming Service
via REST Programmatically (Slide 3 of 4)
/**
* Query a REST service and return the xml data
*
* @param moduleName - ESM service module (eg. manager-service)
* @param serviceName - ESM service name (eg. ManagerSearchService)
* @param methodName - service method name (eg. search1)
* @param params - REST service parameters
* @return REST response xml
* @throws Exception
*/
public static String getRestXml(String moduleName, String serviceName,
String methodName, HashMap<String, String> params) throws Exception {
String urlstr = getRestUrl(moduleName, serviceName, methodName, params);
URL url = new URL(urlstr);
URLConnection connection = url.openConnection();
BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
StringBuffer sb = new StringBuffer();
String line;
while ((line = in.readLine()) != null) {
sb.append(line);
}
in.close();
return sb.toString();
}

www.arcsight.com

2010 ArcSight Confidential

31

Developing ArcSight ESM Application

Consuming Service
via REST Programmatically (Slide 4 of 4)
//Login through REST
HashMap<String, String> params = new HashMap<String, String>();
params.put("login", "admin");
params.put("password", "password");
String xml = getRestXml("core-service", "LoginService", "login", params);
// Parse the XML for token
DocumentBuilderFactory f = DocumentBuilderFactory.newInstance();
DocumentBuilder b = f.newDocumentBuilder();
Document d = b.parse(new ByteArrayInputStream( xml.getBytes()));
Node node = d.getDocumentElement().getChildNodes().item(0);
String token = node.getTextContent();
if (token==null){
System.out.println("Failed to login");
System.out.println (xml);
return;
}
//Search datamonitor resource
params = new HashMap<String, String>();
params.put("authToken", token);
params.put("queryStr", "datamonitor event throughput" );
params.put("pageSize", "50");
String resXml = getRestXml("manager-service", "ManagerSearchService", "search1", params);

www.arcsight.com

2010 ArcSight Confidential

32

Your Feedback Builds a Better Conference!

Text to 32075 (USA & Canada) or 447786204951 (Non-USA)

Type ARCS <space> 66 and the letter to each response

SMS body example: ARCS 66ae*your comments
Excellent
Good
Fair

Poor

Rate the speaker

Rate the content

Please provide comments: (*) enter any comments/feedback

Download session replays after the conference:
https://protect724.arcsight.com/community/protect10
www.arcsight.com

2010 ArcSight Confidential

33

ArcSight, Inc.
Corporate Headquarters: 1 888 415 ARST
EMEA Headquarters: +44 (0)844 745 2068
Asia Pac Headquarters: +65 6248 4795
www.arcsight.com

www.arcsight.com

2010 ArcSight Confidential

34