reports

This pluggable module provides access to periodical event reports.

Provided endpoints

/api/reports/dashboard

Web API

For general information about web API please refer to section Web API.

Following is a list of all currently available API endpoints. These endpoints provide results as JSON document instead of full HTML page.

API endpoint: dashboard

Relevant endpoint:

/api/reports/dashboard

  • Authentication: login required

  • Authorization: any role

  • Methods: GET, POST

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 /reports/dashboard endpoint. Once you are satisfied with the result, you can simply switch the base URL to the /api/reports/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 2022-01-01 00:00:00

dt_to

  • Description: Upper event detection time boundary

  • Datatype: Datetime in the format YYYY-MM-DD HH:MM:SS, for example 2022-01-01 00:00:00

groups

  • Description: List of required abuse groups owning the reports

  • Datatype: list of strings

  • Logical operation: All given values are ORed

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"]]

statistics

  • Description: This subkey is present in case search operation was triggered. It contains the actual result of the search. Following subkeys can be found in this dictionary:

    • cnt_emails - Total number of report emails generated

    • cnt_events - Total number of matched events

    • cnt_events_all - Total number of reported events

    • cnt_events_filtered - Total number of matched events that were filtered and thus not reported

    • cnt_events_new - Total number of new events

    • cnt_events_relapsed - Total number of relapsed events

    • cnt_events_thresholded - Total number of thresholded events

    • cnt_recurring - Total number of relapsed events

    • cnt_reports - Total number of reports created

    • cnt_reports_summary - Total number of summary reports created

    • cnt_unique - Total number of unique events

    • dt_from - Lower time boundary of the result dataset

    • dt_to - Upper time boundary of the result dataset

    • abuses - Dictionary of the abuse groups and the number of events

    • analyzers - Dictionary of the analyzers and the number of events

    • asns - Dictionary of the ASNs and the number of reported events

    • categories - Dictionary of the categories and the number of reported events

    • category_sets - Dictionary of the category sets and the number of reported events

    • classes - Dictionary of the classes and the number of reported events

    • countries - Dictionary of the countries and the number of reported events

    • detectors - Dictionary of the detectors and the number of reported events

    • detectorsws - Dictionary of the detectors and analyzers and the number of reported events

    • emails - Dictionary of the emails and the number of reports

    • ips - Dictionary of the IPs and the number of reported events

    • severities - Dictionary of the severities and the number of reported events

    • timeline_cfg - Pre-calculated optimized timeline configurations

  • Datatype: list of dictionaries

items_count

  • Description: This subkey is present in case search operation was triggered. It contains the number of original datasets that have been processed to produce final dataset statistics.

  • 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"}

time_marks

  • Description: This subkey is present in case search operation was triggered. It contains list of time marks that can be used to calculate the duration of various processing steps like queriing database, processing and rendering the result.

  • Datatype: list of lists

searched

  • Description: This subkey is present in case search operation was triggered. It is a simple indication of the successful search operation.

  • Datatype: boolean always set to True

search_widget_item_limit

  • Description: This subkey is always present in the response. It is intended for internal purposes.

  • Datatype: integer

view_icon

  • Description: This subkey is always present in the response. It is intended for internal purposes.

  • Datatype: string

view_title

  • Description: This subkey is always present in the response. It is intended for internal purposes.

  • Datatype: string

Example usage with curl:

$ curl -X POST -d "api_key=your%AP1_k3y" "https://.../api/reports/dashboard?submit=Search"