AlgoSec Reporting Tool

This topic describes how to use the AlgoSec Reporting Tool (ART), which is an additional AFA reporting tool powered by Kibana.

ART enables you to visualize ASMS data about devices, change requests, and AppViz applications, in a variety of charts, tables, and dashboards.

In this topic:

Click to play the following video, which reviews a few dashboards provided out-of-the-box by AlgoSec.

AlgoSec Reporting Tool prerequisites and permissions

Using ART to create and view advanced dashboards has the following requirements:

Enable ART operations

To enable ART for your ASMS system, you must have the ART_Operation_Status parameter set to on in the AFA Administration area. ART starts collecting data only from the date at which this parameter value is defined. For more details, see Advanced Configuration. If your virtual machines had 4 cores and 16 GB RAM or less and was upgraded, after turning on ART using the parameter above, from within the machine using SSH, send the command: curl -sS -x "" -# 127.0.0.1:8080/afa/UserAliases/allUsersAliases This resets the user permissions for the data in ART and creates the relevant users.

User access to ART data

ART is available only to users who are configured for access. Non-admin users who have access to ART will only see data relevant to their allowed firewalls. For more details, see Manage users and roles in AFA and Manage privileged users.

Back to top

Access the AlgoSec Reporting Tool

The AlgoSec Reporting Tool is available from the main menu on the left in AFA or FireFlow, or from several areas in AppViz.

Once in ART, do the following to view data and create charts and dashboards.

• Discover data
• Visualize data
• Create or edit dashboards

Back to top

Discover data

In ART, click Discover to browse ASMS data and create search queries to use in graphs and charts. ART provides a few saved search queries out of the box, and also enables to you create custom searches and filters.

Save your search queries, export them, or share links with others.

Do the following:

1. From the main menu on the left, click Discover.

2. At the top-left, click the dropdown to select the type of data you want to view.

   applications	View data by AppViz application.
   change_requests	View data by FireFlow change requests.
   devices	View data by devices managed by AFA.

   Tip: Alternately, start with a saved search. Either click Open at the top of the page, or click Management > Saved Objects > Searches.

   If you need to, search for the name of your saved search. Click a name to load the saved search.

3. Determine the field data displayed by adding field names to the list of Selected Fields at the top-left.

   • In the Available Fields area, hover over the field heading and click Add to add it to the selected fields.
   • To remove a field from this list, hover over the field heading in the Selected Fields area and click Remove.

4. Filter the values of the fields displayed to further filter the data shown.

   Do the following:

   1. Above the data type dropdown, click Add a Filter . For example:

      

   2. In the Add filter dialog, enter a field name, operator, and value.

      Note: When selecting the is or is not operator, values must match actual values exactly, and are case-sensitive.

      To display a list of actual field values, click a field value header. A bar graph expands to display the sum of each value for the field.

   3. Click Save to add the selected values to the filter.

   The field and value is added to the filter list above the data type dropdown and field lists.

   For example:

   

   Filter field options

   Once a field is added to the filter, hover over the field in the filter to display further options.

   

   Do any of the following:

   /	Enable or disable the filter field. Use this option to keep the filter values defined, but temporarily disable it for the current data displayed.
   /	Pin or unpin the filter to the top. Use this option when you have several filters displayed, and you want to select specific filters to view at the top of the list.
   /	Invert a field definition to show all results that do not match the values selected. Inverting a field turns the field definition red to indicate that the results shown are negative results. Click Toggle to return to the original field definition.
   	Remove the field from the filter entirely. This removes your field values, and you'll need to define them from scratch if you need them again.
   	Edit the field values selected. In the Edit filter dialog, update the selected filter name, operator, and value, and then click Save.

   Tip: At the far right, click Actions q to display these same actions for all filters defined.

   Advanced query editing

   ART provides the following advanced filter editing features for experienced Kibana or Elastisearch users.

   • In the search bar at the top of the screen, enter a query syntax manually to define the field names and values for your filter.

     Click Show Latest to automatically add the Current:true field and filter out all historical data from the data displayed.

     For more details about query syntax, click the Uses lucene query syntax link at the right of the search box.

   • In the Edit filter dialog, click Edit Query DSL to manually update or copy in an Elastisearch Query DSL to use for this field value definition.

5. At the top of the page, click any of the following to manage the filtered data:

   New	Discard all of your changes and start a new filter from scratch.
   Save	Save your filter so that you or other users can return to it later on. Click Open to view a list of saved searches.
   Share	Display links to either share a saved search or a snapshot. Tip: Full link URLs may be long. Click Copy to copy the full URL to the clipboard, or Short URL to display a shorter URL that's easier to share.
   Date selector	Define the date range for the data displayed. For details, see Change date ranges.

Continue with creating graphs and dashboards. For details, see Visualize a specific field, Visualize data, and Create or edit dashboards.

Visualize a specific field

Jump directly from the Discover section of ART to Visualize in order to create graphs based on a specific filter field.

Do the following:

1. Hover over any filter name in the Selected or Available Fields list to display a bar chart of the values for that field.

   For example:

   

2. Click Visualize to display the selected field in the Visualize area.

For more details, see Visualize data.

Back to top

Visualize data

In ART, click Visualize to start by creating or loading graphs and charts and then adding or modifying the data used.

Export, share, or embed your visualizations in other locations, or add them to ART dashboards. For more details, see Create or edit dashboards.

Do the following:

1. Click Visualize from the main menu on the left.

   A list of saved visualizations is displayed.

   Tip: Alternately, click Visualize from a specific field dropdown in the Discover area. For more details, see Visualize a specific field.

   • Click the name of a saved search to display a chart based on that data.

   • Click

2. Click the name of a saved visualization to view, or click Create new visualization to create a new one.

   If you selected to create a new visualization, do the following:

   1. Select a chart type to use.
   2. Select a saved search to use as the data set, or select an index to create a new search. For more details, see Discover data.

3. Once your chart is displayed, define the data metrics and other options for your chart. Click to apply your changes.

   Available options depend on the type of chart you're working with. For example:

   

4. Above the chart display, define a filter to further filter the data shown.

   Do the following:

   1. Above the chart options, click Add a Filter .

   2. In the Add filter dialog, enter a field name, operator, and value.

      Note: When selecting the is or is not operator, values must match actual values exactly, and are case-sensitive.

   3. Click Save to add the selected values to the filter.

   The field and value is added to the filter list above the data type dropdown and field lists.

   For example:

   

   Filter field options

   Once a field is added to the filter, hover over the field in the filter to display further options.

   

   Do any of the following:

   /	Enable or disable the filter field. Use this option to keep the filter values defined, but temporarily disable it for the current data displayed.
   /	Pin or unpin the filter to the top. Use this option when you have several filters displayed, and you want to select specific filters to view at the top of the list.
   /	Invert a field definition to show all results that do not match the values selected. Inverting a field turns the field definition red to indicate that the results shown are negative results. Click Toggle to return to the original field definition.
   	Remove the field from the filter entirely. This removes your field values, and you'll need to define them from scratch if you need them again.
   	Edit the field values selected. In the Edit filter dialog, update the selected filter name, operator, and value, and then click Save.

   Tip: At the far right, click Actions q to display these same actions for all filters defined.

   Advanced query editing

   ART provides the following advanced filter editing features for experienced Kibana or Elastisearch users.

   • In the search bar at the top of the screen, enter a query syntax manually to define the field names and values for your filter.

     Click Show Latest to automatically add the Current:true field and filter out all historical data from the data displayed.

     For more details about query syntax, click the Uses lucene query syntax link at the right of the search box.

   • In the Edit filter dialog, click Edit Query DSL to manually update or copy in an Elastisearch Query DSL to use for this field value definition.

5. At the top of the page, click any of the following to manage the chart you created:

   Save	Save your chart so that you or other users can return to it later on.
   Share	Display links to either share a saved chart or a snapshot. Use the Embedded iframe URL to embed this chart in another location. Tip: Full link URLs may be long. Click Copy to copy the full URL to the clipboard, or Short URL to display a shorter URL that's easier to share.
   Refresh	Refresh the chart currently displayed with updated data from AFA, FireFlow, or AppViz.
   Date selector	Define the date range for the data displayed. For details, see Change date ranges.

Continue by creating dashboards that include your charts. For details, see Visualize a specific field, Visualize data, and Create or edit dashboards.

Back to top

Filter fields by data type

Each data type provides a different set of fields for discovering and visualizing data in ART.

For details, see:

Back to top

Create or edit dashboards

ART dashboards consist of graphs, or visualizations created in the Visualize area. In addition to the default dashboards that AFA provides out of the box, create or customize your own dashboards to suit your needs.

Do the following:

1. Click Dashboard from the main menu on the left. ART displays a list of saved dashboards.

   Search for the dashboard you want to view, or click Create new dashboard to create a new one.

2. Do one of the following:

   Add new dashboard	If you are creating a new dashboard from scratch, click Add to add saved graphs and charts to your dashboard. Click a visualization name to add it to the dashboard draft below. Scroll down to view your dashboard graphs and charts.
   Edit saved dashboard	If you are editing a saved dashboard, click Edit at the top of the page to modify the graphs and charts on the selected dashboard.

3. Each dashboard widget has the following options shown at the top right:

   • . Expand the selected widget to full-screen size.
   • . Open the selected chart or graph in the Visualize area for editing. For details, see Visualize data.
   • . Move the selected widget to a different location in the dashboard.
   • . Remove the selected widget from the dashboard.

   To resize a widget, hover over the widget and use the corner icon shown at the bottom right to drag the widget edges to the new size.

   Display advanced dashboard widget details

   Click the arrow at the bottom left of a widget to display the following:

   Table	Display the widget data in table form, or export the data. Below the table, click Raw or Formatted to export your data. From the Page Size drop down, select an option to determine the number of table rows to display.
   Request	Display the Elasticsearch request body.
   Response	Display the Elasticsearch response body.
   Statistics	Display additional statistics about the Elastisearch request performed for this widget.

4. When you're done customizing your dashboard, click Save and enter a name and description for your dashboard.

   Tip: Optionally, select Store time with dashboard to update the global date range to the date range currently selected, when you edited the dashboard.

   Click Cancel at the top of the page to exit the editing mode and discard your changes.

Dashboard options

Use the following additional options at the top of the page to manage your dashboard:

Share	Display links to either share a saved dahsboard or a snapshot. Use the Embedded iframe URL to embed this chart in another location. Tip: Full link URLs may be long. Click Copy to copy the full URL to the clipboard, or Short URL to display a shorter URL that's easier to share.
Clone	Make a copy of the dashboard currently displayed for editing.
Export to PDF	Click to save a PDF with the dashboard data currently displayed.
Mail Schedule	Click to jump in to the AFA Administration area and schedule email updates for the displayed dashboard. For more details, see Schedule dashboard notifications.
Date selector	Define the date range for the data displayed. For details, see Change date ranges.

Back to top

Change date ranges

All ART pages provide a date range selector, which enables you modify the date range of the data currently shown.

Do any of the following:

• Use the < > arrows to move back and forth between incremental date ranges.

• Click the selected date range, shown in the center of the < > arrows, to select a more complex date range.

  The Time Range area expands, providing you with a series of options of the following types:

  Quick	Provides quick options, like Today, Previous month, Last 24 hours, or Last 2 years.
  Relative	Enables you to define date ranges from a specified time ago or from now, to another specified time ago or from now.
  Absolute	Enables you to select specific start and end dates.

Click Go to update the data displayed based on your date range selections.

For example:

Back to top

Manage ART objects

The ART Management area enables you to manage saved queries, visualizations, and dashboards.

Do the following:

1. From the main menu, click Management, and then click Saved objects.

2. Click one of the following tabs:

   • Dashboards. Manage saved dashboards. For more details, see Create or edit dashboards.
   • Searches. Manage saved searches. For more details, see Discover data.
   • Visualizations. Manage saved graphs and charts. For more details, see Visualize data.

3. Do any of the following:

   Find your object	Browse the list or enter a name in the search field to locate your object.
   Edit object settings	Click an object name in the list to make changes, such as to the object title. This option also enables you manage advanced settings, such as supporting JSON code. We recommend making advanced changes like these only if you are an advanced Kibana user.
   Open object in ART	Hover over the object name, and click the eye icon to open it Discover, Visualize, or Dashboard areas.
   Delete objects	Select one or more objects in the list, and click Delete to delete the selected items. In the warning dialog that appears, click Delete ... to confirm the deletion.
   Export JSON details	Select one or more objects in the list and click Export to save the relevant JSON data locally. To export JSON data for all objects, click Export Everything at the top of the page.
   Import objects	Create ART objects by importing a JSON file. At the top of the page, click Import and select a JSON file to import.

Back to top

Troubleshoot ART

If you run into issues when using the AlgoSec Reporting tool, you may want to check the relevant log files.

ART-related logs are created for the Elastic, Kibana, and Logstash services in the /var/log directory on the AFA machine.

Back to top