REST access to ESM Web Services

Transcription

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

2 Forward-looking statements This is a rolling (up to three year) Roadmap and is subject to change without notice. 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. 3

3 HP confidential information This is a rolling (up to three year) Roadmap and is subject to change without notice. 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. 4

4 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 5

5 Use cases When do you need ESM web services API? HP ArcSight Console Integrations with ESM Building custom UI HP ArcSight ACC HP ArcSight Extending functionality? REST ESM 6

6 Web services supported in next ESM Provided by two web-applications: Core-service and manager-service 1. LoginService (10 methods) 2. GroupService (93 methods) 3. CaseService (80 methods) 4. SecurityEventService (75 methods) 5. ReportService (72 methods) 6. ResourceService (72 methods) 7

7 Software Development Kit

8 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/) 9

9 Provided SDK how to use Objective 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 10

10 Provided SDK how to use Available services (running ESM)

11 Provided SDK how to use Available services (offline docs) 12

12 Provided SDK how to use First request to authenticate a session 13

13 Provided SDK how to use Available services (offline docs) 14

14 Provided SDK how to use REST request (offline docs) 15

15 Provided SDK how to use REST request (execution) 16

16 Provided SDK how to use REST response 17

17 How-tos

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

19 How to expected response 20

20 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? 21

21 How to do it programmatically Java example with java.net.httpurlconnection (page 1) 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() 22

22 How to do it programmatically Java example with java.net.httpurlconnection (page 2) private String login() { Map<String, String> props = new HashMap<String, String>(); props.put( accept", application/json"); return doget(" core-service/rest/loginservice/login?login=admin&password=password", props); } 23

23 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? A: Yes, HttpUrlConnection, apache HttpClient Q: How do I prepare the correct request body? 24

24 How to request body preparation Request body preparation, option A 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 25

25 How to request body preparation Request body preparation, option B 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. 26

26 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? 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/ 27

27 How to provided examples Print the list of existing examples 28

28 How to provided examples Run an example 29

29 Dos and don ts

30 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: * ' ( ) ; & = + $, /? # [ ] 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 31

31 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 32

32 Please give me your feedback Session TB2978 Speaker Dmitry Udalov 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. 33

33 Thank you

34