charlieyqin / arcsight-rest

Python library for the ArcSight logger REST API

Arcsight Logger REST library

This is a python library to interact with the REST API that is offered on the Arcsight Logger

Installation

Install library with pip (You can install pip here)

$ pip install arcsightrest

Import the library

import arcsightrest

Different functions

Setting the location of the ArcSight Logger

Set the TARGET to the ip or hostname of the Arcsight logger

ArcsightLogger.TARGET = 'https://IPADDRESS:9000'

Logging in

Logging in. Storing of the token is done by the library, The last option is optional, if this is True it will ignore all SSL warnings ( if you have not imported the SSL certificate, this is default to False

ArcsightLogger('USERNAME', 'PASSWORD', True)

Searching

The search function will return 2 values, first the search_id that has been set for the search, and the HTTP content/response. You can also set start and end time, plus the other documented parameters. If you don't include the start and end time, this will default to 2 hours.

search(search_id, start_time=2014-05-26T21:49:46.000-07:00, end_time=2014-05-26T22:49:46.000-07:00)

Histogram

Returns data you can use to display a histogram (a column chart with no gap between columns) of the event distribution over time of an already searched time range

histogram(search_id)

Drilldown

Narrows the search results to the specified time range. For example, you can use it to narrow down the search results to be shown in the grid when a bar of the histogram is clicked.

drilldown(search_id, start_time, end_time)

Search status

There is two functions to check the search status, one function will check if the search is complete, the other will check the $

Waiting for the search to complete:

wait(search_id)

Just checking the current status:

search_complete(search_id)

Collecting the data from a search

The events function is what will return the actual events that is generated by the search, in a normal JSON format:

events(search_id)

Custom JSON format:

arcsight.events(search_id, True)

Collecting the data from a search (Raw_events)

Returns the raw events for the specified row IDs.

raw_events(search_id)

Displaying chart data

Returns the data you can use to display a chart and the table under the chart. The chart_data request also returns the results of aggregate operators like sort, tail, and head. For an example of returning the results of aggregate operators,

chart_data(search_id)

Stopping a search

There is two ways to stop the currently running search Stop, stops the search operation but keeps the search session so that the search results can be narrowed down later.

data = arcsight.stop(search_id)

Close, stops the execution of the search and clears the search session data from the server.

data = arcsight.close(search_id)

Example script

def searchfunction():
    # Define target
    arcsightrest.ArcsightLogger.TARGET = 'https://10.10.10.10:9000'
    # Logging in
    arcsight = arcsightrest.ArcsightLogger('USERNAME', 'PASSWORD', True)
    # Grabs the search_id of the search, and the response to see if the
    # search is started.
    search_id, response = arcsight.search('_deviceGroup in ["Logger Internal Event Device"]')
    print response
    # Waits for the search to complete, then checks what wait returns
    # (should be that the search is complete)
    wait = arcsight.wait(search_id)
    print wait
    # Gather the data from the started search, and prints all data returned
    data = arcsight.events(search_id)
    print data
    # Closes the search when i have the data needed, and checks the response
    close = arcsight.close(search_id)
    print close

Optional Parameters.

According to the ArcSight documentation, each function also support optional parameters. These are supported for all the calls in this library, all you have to do, is add the specified fields at the end of the function call, like this: Here search_id is the only required field (except user token, but that is handled by the library). So if you find a specific parameter to a REST call in the ArcSight documentation, it will always work in this library.

chart_data(search_id, length=NUMBER, offset=NUMBER)