events

Description

This pluggable module provides access to IDEA message database. It enables users to execute custom queries via provided search form, display the details of the messages or download them locally to their own computers. Additionally the overview dashboard panel is provided.

Provided endpoints

/events/search

Endpoint providing search form for querying the IDEA message database.

  • Authentication: login required
  • Authorization: any role
  • Methods: GET
/api/events/search

Endpoint providing API search form for querying the IDEA message database. See appropriate section below for the description of API interface.

  • Authentication: login required
  • Authorization: any role
  • Methods: GET, POST
/events/<item_id>/show

Endpoint providing detail view of given IDEA message.

  • Authentication: login required
  • Authorization: any role
  • Methods: GET
/api/events/<item_id>/show

Endpoint providing API for retrieving given IDEA message. See appropriate section below for the description of API interface.

  • Authentication: login required
  • Authorization: any role
  • Methods: GET
/events/<item_id>/download

Endpoint enabling users to download given IDEA message as JSON file.

  • Authentication: login required
  • Authorization: any role
  • Methods: GET
/events/dashboard

Endpoint providing overall IDEA message dashboard overview.

  • Authentication: login required
  • Authorization: any role
  • Methods: GET
/api/events/dashboard

Endpoint providing API for retrieving overall IDEA message dashboard overview. See appropriate section below for the description of API interface.

  • Authentication: login required
  • Authorization: any role
  • Methods: GET
/api/events/metadata

Endpoint providing API for retrieving various IDEA message metadata. See appropriate section below for the description of API interface.

  • Authentication: login required
  • Authorization: any role
  • Methods: GET

Web API

The API interface must be accessed by authenticated user. For web client side scripts and applications it should be sufficient to use standard cookie-based authentication. If you need to access the API from outside of the web browser, it might be usefull to generate yourself an API access token and use the token based authentication. For security reasons you have to use POST method for sending the token, otherwise it might get logged on many different and insecure places (like web server logs).

API endpoint: show

Endpoint URL: /api/events/<item_id>/show

Response format

JSON document, that will be received as a response for the search, can contain following keys:

item
  • Description: This subkey is present in case requested item exists. It contains the IDEA message according to the IDEA specification.
  • Datatype: IDEA message as dictionary
item_id
  • Description: This subkey is present in case requested item exists. It contains the identifier of the message.
  • Datatype: string
search_widget_item_limit
  • Description: This subkey is always present in the response. It is intended for internal purposes.
  • Datatype: integer
status
  • Description: This subkey is present in case there were any errors in the submitted request. So in another words the presence of this subkey is an indication of failure. This subkey contains the HTTP status code of the error.
  • Datatype: integer
message
  • Description: This subkey is present in case there were any errors in the submitted request. So in another words the presence of this subkey is an indication of failure. This subkey contains the human readable message describing the error that occured.
  • Datatype: string

. _section-hawat-plugin-events-webapi-metadata:

API endpoint: metadata

Endpoint URL: /api/events/metadata

The main reason for existence of this endpoint is the ability to somehow retrieve all possible and correct values for various IDEA message attributes. These lists can be then used for example for rendering some UI widgets.

Response format

JSON document, that will be received as a response for the search, can contain following keys:

categories
  • Description: This subkey contains all possible values for IDEA message categories.
  • Datatype: list of strings
classes
  • Description: This subkey contains all possible values for IDEA message classes.
  • Datatype: list of strings
detector_types
  • Description: This subkey contains all possible values for IDEA message detector types.
  • Datatype: list of strings
detectors
  • Description: This subkey contains all possible values for IDEA message detector names.
  • Datatype: list of strings
host_types
  • Description: This subkey contains all possible values for IDEA message host types.
  • Datatype: list of strings
inspection_errs
  • Description: This subkey contains all possible values for IDEA message inspection errors.
  • Datatype: list of strings
protocols
  • Description: This subkey contains all possible values for IDEA message protocols.
  • Datatype: list of strings
severities
  • Description: This subkey contains all possible values for IDEA message severities.
  • Datatype: list of strings
source_types
  • Description: This subkey contains all possible values for IDEA message source types.
  • Datatype: list of strings
target_types
  • Description: This subkey contains all possible values for IDEA message target types.
  • Datatype: list of strings

API endpoint: dashboard

Endpoint URL: /api/events/dashboard

The URL for web API interface is available as normal endpoint to the user of the web interface. This fact can be used to debug the queries interactively and then simply copy them to another application. One might for example start with filling in the search form in the /events/dashboard endpoint. Once you are satisfied with the result, you can simply switch the base URL to the /api/events/dashboard endpoint and you are all set.

Available query parameters:

Following parameters may be specified as standard HTTP query parameters:

dt_from
  • Description: Lower event detection time boundary
  • Datatype: Datetime in the format YYYY-MM-DD HH:MM:SS, for example 2018-01-01 00:00:00
  • Default: Previous midnight
  • Note: Default value kicks in in case the parameter is not specified, explicitly use empty value for boundless search
dt_to
  • Description: Upper event detection time boundary
  • Datatype: Datetime in the format YYYY-MM-DD HH:MM:SS, for example 2018-01-01 00:00:00

Response format

JSON document, that will be received as a response for the search, can contain following keys:

form_data
  • Description: This subkey is present in case search operation was triggered. It contains a dictionary with all query parameters described above and their appropriate processed values.
  • Datatype: dictionary
form_errors
  • Description: This subkey is present in case there were any errors in the submitted search form and the search operation could not be triggered. So in another words the presence of this subkey is an indication of search failure. This subkey contains list of all form errors as pairs of strings: name of the form field and error description. The error description is localized according to the user`s preferences.
  • Datatype: list of tuples of strings
  • Example: [["dt_from", "Not a valid datetime value"]]
items
  • Description: This subkey is present in case search operation was triggered. It contains a list of IDEA messages that matched the query parameters. The messages are formated according to the IDEA specification.
  • Datatype: list of IDEA messages as dictionaries
items_count
  • Description: This subkey is present in case search operation was triggered. It contains the number of messages in the result set items. By comparing this number with the value of pager_index_limit it is possible to determine, if the current result set/page is the last, or whether there are any more results.
  • Datatype: integer
query_params
  • Description: This subkey is always present in the response. It contains processed search query parameters that the user actually explicitly specified.
  • Datatype: dictionary
  • Example: {"dt_from": "", "submit": "Search"}
search_widget_item_limit
  • Description: This subkey is always present in the response. It is intended for internal purposes.
  • Datatype: integer
searched
  • Description: This subkey is present in case search operation was triggered. It is a simple indication of the successfull search operation.
  • Datatype: boolean always set to True