REST access to ESM Web Services - Hewlett Packard Enterprise · 3 © Copyright 2014 Hewlett-Packard Development Company, L.P. The information contained herein is subject to change

© Copyright 2014 Hewlett-Packard Development Company, L.P. The information contained herein is subject to change without notice.

REST access to ESM Web Services Dmitry Udalov, Sr. Software Engineer #HPProtect

© Copyright 2014 Hewlett-Packard Development Company, L.P. The information contained herein is subject to change without notice. 3

This is a rolling (up to three year) Roadmap and is subject to change without notice.

Forward-looking statements

This document contains forward looking statements regarding future operations, product development, product capabilities and availability dates. This information is subject to substantial uncertainties and is subject to change at any time without prior notification. Statements contained in this document concerning these matters only reflect Hewlett Packard's predictions and / or expectations as of the date of this document and actual results and future plans of Hewlett-Packard may differ significantly as a result of, among other things, changes in product strategy resulting from technological, internal corporate, market and other changes. This is not a commitment to deliver any material, code or functionality and should not be relied upon in making purchasing decisions.


This is a rolling (up to three year) Roadmap and is subject to change without notice.

HP confidential information

This Roadmap contains HP Confidential Information.

If you have a valid Confidential Disclosure Agreement with HP, disclosure of the Roadmap is subject to that CDA. If not, it is subject to the following terms: for a period of 3 years after the date of disclosure, you may use the Roadmap solely for the purpose of evaluating purchase decisions from HP and use a reasonable standard of care to prevent disclosures. You will not disclose the contents of the Roadmap to any third party unless it becomes publically known, rightfully received by you from a third party without duty of confidentiality, or disclosed with HP’s prior written approval.


Agenda

1. Use cases

2. Available web services

3. Provided SDK – what’s in it

4. How-tos

5. Dos and don’ts

6. Q&A


When do you need ESM web services API?

Use cases

• Integrations with ESM

• Building custom UI

• Extending functionality

HP ArcSight

Console

ACC

REST

HP ArcSight

? ESM

HP ArcSight


Provided by two web-applications: Core-service and manager-service

Web services supported in next ESM

1. LoginService (10 methods)

2. GroupService (93 methods)

3. CaseService (80 methods)

4. SecurityEventService (75 methods)

5. ReportService (72 methods)

6. ResourceService (72 methods)


Software Development Kit


Provided SDK – what’s in it

Developer’s guide • How to develop client-side applications

• Where to find information (published and live queries)

Javadoc (html + pdf) • Standard descriptions of client-side classes

• URL, Http Method, Content-type, JSON prototypes, Statuses

• Available in both html and pdf-formats

Client-side SDK (utilities/sdk/lib)

Examples (utilities/sdk/examples/)


Objective

Provided SDK – how to use

We have an external ticketing system and we want to add information from ArcSight ESM to the related cases in that system. Added information will contain data enriched by ESM correlation analysis: 1. For any open case, note the related event Ids (e.g. integration command)

2. Using ESM API, get these events from ESM

3. Retrieve Event field in question

4. Submit the value of the field as additional data to the ticketing system via its API


Available services (running ESM)


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

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










Available services (offline docs)



First request to authenticate a session



Available services (offline docs)



REST request (offline docs)



REST request (execution)



REST response



How-tos


How to

Q: How do I find out what will be returned?


How to – expected response


How to

Q: How do I find out what will be returned? A: Check the provided javadoc

Q: Can I do it programmatically? Any examples?


Java example with java.net.HttpURLConnection (page 1)

How to – do it programmatically

public String doGet(String urlstr, Map<String, String> props) {

java.net.URL url = new java.net.URL(urlstr);

HttpURLConnection connection = (HttpURLConnection)url.openConnection();

for (Map.Entry<String, String> nextParam : props.entrySet()) {

connection.setRequestProperty(nextParam.getKey(), nextParam.getValue());

}

int code = connection.getResponseCode();

if ( HttpURLConnection.HTTP_NO_CONTENT == code ) {

return "";

}

// read connection.getInputStream()

}


Java example with java.net.HttpURLConnection (page 2)

How to – do it programmatically

private String login() {

Map<String, String> props = new HashMap<String, String>();

props.put(“accept", “application/json");

return doGet("https://localhost:8443/www/ core-service/rest/LoginService/login ?login=admin&password=password", props);

}


How to


Q: Can I do it programmatically? Any examples? A: Yes, HttpUrlConnection, apache HttpClient

Q: How do I prepare the correct request body?


Request body preparation, option A

How to – request body preparation

1. Identify web-service and method

2. Open correspondent page in javadoc

3. Note Content-type to prepare request in XML or JSON

4. Start with provided JSON prototype for the class { "sev.getSecurityEvents" : { "sev.authToken" : value, "sev.ids" : [ "a1", "a2", "a3" ], "sev.timeField" : { "JSON for the nested object" }, "sev.startMillis" : "value", "sev.endMillis" : "value“ } }

5. Add parts for nested classes recursively


Request body preparation, option B

How to – request body preparation

1. Identify web-service and method

2. Open correspondent page in javadoc and note class for parameter public SecurityEventServiceGetSecurityEventsResponse getSecurityEvents(SecurityEventServiceGetSecurityEvents value)

3. Add to your project client-side SDK (utilities/sdk/lib/manager-service*.jar)

4. In your code create an instance of that class and fill it in final List<Long> eventIds = ... SecurityEventServiceGetSecurityEvents requestObject = new SecurityEventServiceGetSecurityEvents(); requestObject.setAuthToken(authToken); requestObject.setIds(eventIds); requestObject.setStartMillis(-1L); requestObject.setEndMillis(-1L);

5. Use third-party libraries to convert that object into JSON (e.g. http://jettison.codehaus.org/)


How to


Q: Can I do it programmatically? Any examples? A: Yes, HttpUrlConnection, apache HttpClient

Q: How do I prepare the correct request body? A: Manually using JSON prototypes or using imported SDK classes.

Q: Provided examples. What’s provided, where, and how to use? A: utilities/sdk/examples/TestKit/


How to – provided examples Print the list of existing examples


How to – provided examples Run an example


Dos and don’ts


Things to remember

1. For missed request parameter, ESM uses default values

2. Make sure that request uses correct names for parameters

3. URL encoding for reserved URI symbols: (URI syntax: http://tools.ietf.org/html/rfc3986)

4. Before reading HTTP response, check response code (204 No Content)

5. Be aware of JSON syntax for single element array (jettison)

6. Do not forget to log out

! * ' ( ) ; : @ & = + $ , / ? # [ ]

http://tools.ietf.org/html/rfc3986

http://en.wikipedia.org/wiki/Exclamation_mark

http://en.wikipedia.org/wiki/Asterisk

http://en.wikipedia.org/wiki/Apostrophe_(mark)

http://en.wikipedia.org/wiki/Parentheses

http://en.wikipedia.org/wiki/Parentheses

http://en.wikipedia.org/wiki/Semicolon

http://en.wikipedia.org/wiki/Colon_(punctuation)

http://en.wikipedia.org/wiki/At_sign

http://en.wikipedia.org/wiki/Ampersand

http://en.wikipedia.org/wiki/Equal_sign

http://en.wikipedia.org/wiki/Plus_sign

http://en.wikipedia.org/wiki/Dollar_sign

http://en.wikipedia.org/wiki/Comma_(punctuation)

http://en.wikipedia.org/wiki/Slash_(punctuation)

http://en.wikipedia.org/wiki/Question_mark

http://en.wikipedia.org/wiki/Number_sign

http://en.wikipedia.org/wiki/Bracket

http://en.wikipedia.org/wiki/Bracket


For more information

Visit these demos

• HP ArcSight ESM - Leave the bad guys with no place to hide

After the event

• Contact your sales rep


Please fill out a survey.

Hand it to the door monitor on your way out.

Thank you for providing your feedback, which helps us enhance content for future events.

Session TB2978 Speaker Dmitry Udalov

Please give me your feedback


Thank you


REST access to ESM Web Services - Hewlett Packard Enterprise · 3 © Copyright 2014 Hewlett-Packard Development Company, L.P. The information contained herein is subject to change

Documents