hawat.blueprints.events package

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

Example usage with curl:

$ curl -X POST -d "api_key=your%AP1_k3y" "https://.../api/events/event_id/show"

. _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

Example usage with curl:

$ curl -X POST -d "api_key=your%AP1_k3y" "https://.../api/events/metadata"

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

Example usage with curl:

$ curl -X POST -d "api_key=your%AP1_k3y" "https://.../api/events/dashboard?submit=Search"
class hawat.blueprints.events.APIDashboardView[source]

Bases: hawat.base.AJAXMixin, hawat.blueprints.events.AbstractDashboardView

View responsible for presenting overall IDEA event statistics dashboard in the form of HTML page.

classmethod get_view_name()[source]

Implementation of hawat.base.BaseView.get_view_name().

class hawat.blueprints.events.APIMetadataView[source]

Bases: hawat.base.AJAXMixin, hawat.base.SimpleView

Application view providing access event database status information.

authentication = True
authorization = [<Permission needs={Need(method='role', value='admin'), Need(method='role', value='user'), Need(method='role', value='maintainer'), Need(method='role', value='developer')} excludes=set()>]
do_before_response(**kwargs)[source]

Implementation of hawat.base.RenderableView.do_before_response().

classmethod get_menu_title(item=None)[source]

Implementation of hawat.base.BaseView.get_menu_title().

classmethod get_view_name()[source]

Implementation of hawat.base.BaseView.get_view_name().

class hawat.blueprints.events.APISearchView[source]

Bases: hawat.base.AJAXMixin, hawat.blueprints.events.AbstractSearchView

View responsible for querying IDEA event database and presenting the results in the form of JSON document.

classmethod get_view_name()[source]

Implementation of hawat.base.BaseView.get_view_name().

methods = ['GET', 'POST']
class hawat.blueprints.events.APIShowView[source]

Bases: hawat.base.AJAXMixin, hawat.blueprints.events.AbstractShowView

Detailed IDEA message view that presents the result as HTML page.

classmethod get_view_name()[source]

Implementation of hawat.base.BaseView.get_view_name().

methods = ['GET', 'POST']
class hawat.blueprints.events.AbstractDashboardView[source]

Bases: hawat.base.SQLAlchemyMixin, hawat.base.BaseSearchView

Base class for presenting overall IDEA event statistics dashboard.

authentication = True
authorization = [<Permission needs={Need(method='role', value='admin'), Need(method='role', value='user'), Need(method='role', value='maintainer'), Need(method='role', value='developer')} excludes=set()>]
static build_query(query, model, form_args)[source]

Interface implementation of hawat.base.SQLAlchemyMixin.build_query().

dbmodel

Implementation of hawat.base.SQLAlchemyMixin.dbmodel().

Interface implementation of hawat.base.SearchView.do_after_search().

do_before_response(**kwargs)[source]

Implementation of hawat.base.RenderableView.do_before_response().

classmethod get_menu_icon()[source]

Implementation of hawat.base.BaseView.get_menu_icon().

classmethod get_menu_title(item=None)[source]

Implementation of hawat.base.BaseView.get_menu_title().

static get_search_form(request_args)[source]

Interface implementation of hawat.base.SearchView.get_search_form().

classmethod get_view_template()[source]

Implementation of hawat.base.RenderableView.get_view_template().

classmethod get_view_title(item=None)[source]

Implementation of hawat.base.BaseView.get_view_title().

class hawat.blueprints.events.AbstractSearchView[source]

Bases: hawat.base.PsycopgMixin, hawat.base.BaseSearchView

Base class for view responsible for searching IDEA event database and presenting the results.

authentication = True
authorization = [<Permission needs={Need(method='role', value='admin'), Need(method='role', value='user'), Need(method='role', value='maintainer'), Need(method='role', value='developer')} excludes=set()>]

Interface implementation of hawat.base.SearchView.do_before_search().

classmethod get_menu_title(item=None)[source]

Implementation of hawat.base.BaseView.get_menu_title().

static get_search_form(request_args)[source]

Interface implementation of hawat.base.SearchView.get_search_form().

classmethod get_view_title(item=None)[source]

Implementation of hawat.base.BaseView.get_view_title().

class hawat.blueprints.events.AbstractShowView[source]

Bases: hawat.base.PsycopgMixin, hawat.base.ItemShowView

Base class responsible for fetching and presenting single IDEA message.

authentication = True
authorization = [<Permission needs={Need(method='role', value='admin'), Need(method='role', value='user'), Need(method='role', value='maintainer'), Need(method='role', value='developer')} excludes=set()>]
classmethod get_menu_legend(item=None)[source]

Interface implementation of hawat.base.BaseView.get_menu_legend().

classmethod get_menu_title(item=None)[source]

Implementation of hawat.base.BaseView.get_menu_title().

hawat.blueprints.events.BLUEPRINT_NAME = 'events'

Name of the blueprint as module global constant.

class hawat.blueprints.events.DashboardView[source]

Bases: hawat.base.HTMLMixin, hawat.blueprints.events.AbstractDashboardView

View responsible for presenting overall IDEA event statistics dashboard in the form of HTML page.

classmethod get_view_name()[source]

Implementation of hawat.base.BaseView.get_view_name().

class hawat.blueprints.events.DownloadView[source]

Bases: hawat.base.PsycopgMixin, hawat.base.BaseView

Download IDEA event view.

authentication = True
authorization = [<Permission needs={Need(method='role', value='admin'), Need(method='role', value='user'), Need(method='role', value='maintainer'), Need(method='role', value='developer')} excludes=set()>]
dispatch_request(item_id)[source]

Mandatory interface required by the flask.views.View.dispatch_request(). Will be called by the Flask framework to service the request.

Single item with given unique identifier will be retrieved from database and injected into template to be displayed to the user.

classmethod get_menu_legend(item=None)[source]

Interface implementation of hawat.base.BaseView.get_menu_legend().

Implementation of hawat.base.BaseView.get_menu_link().

classmethod get_menu_title(item=None)[source]

Implementation of hawat.base.BaseView.get_menu_title().

classmethod get_view_name()[source]

Implementation of hawat.base.BaseView.get_view_name().

methods = ['GET']
class hawat.blueprints.events.EventsBlueprint(name, import_name, **kwargs)[source]

Bases: hawat.base.HawatBlueprint

Hawat pluggable module - IDEA events.

classmethod get_module_title()[source]

Implementation of hawat.base.HawatBlueprint.get_module_title().

register_app(app)[source]

Callback method. Will be called from hawat.base.HawatApp.register_blueprint() method and can be used to customize the Flask application object. Possible use cases:

  • application menu customization

Parameters

app (hawat.base.HawatApp) – Flask application to be customize.

class hawat.blueprints.events.SearchView[source]

Bases: hawat.base.HTMLMixin, hawat.blueprints.events.AbstractSearchView

View responsible for querying IDEA event database and presenting the results in the form of HTML page.

classmethod get_breadcrumbs_menu()[source]

Interface implementation of hawat.base.SearchView.get_breadcrumbs_menu().

classmethod get_context_action_menu()[source]

Interface implementation of hawat.base.SearchView.get_context_action_menu().

methods = ['GET']
class hawat.blueprints.events.ShowView[source]

Bases: hawat.base.HTMLMixin, hawat.blueprints.events.AbstractShowView

Detailed IDEA message view that presents the result as HTML page.

classmethod get_action_menu()[source]

Interface implementation of hawat.base.SearchView.get_action_menu().

methods = ['GET']
hawat.blueprints.events.get_blueprint()[source]

Mandatory interface and factory function. This function must return a valid instance of hawat.base.HawatBlueprint or flask.Blueprint.