Custom dashboards and charts

You can create custom dashboards in AFA that include built-in charts, custom charts, or both, by defining them directly in XML.

Note: For more details, see AlgoSec Reporting Tool.

Configure custom charts

When creating a dashboard with custom charts, you must configure the custom charts before you configure the dashboard itself.

  • You specify the title of the chart.

  • You specify the type of chart.

  • You specify the variable for which the chart displays data.

  • You specify the Y-axis values the chart displays.

  • For bar charts, you also specify the following:

    • The number of devices displayed in the chart.
    • Whether the chart starts with displaying the devices with the most of the variable or the least of the variable.
    • The direction of the chart.

  • For trend charts, you also specify how many days back the chart displays.

Add a custom chart

  1. Open a terminal and log in using the username "afa" and the related password.

  2. Create a new file in /home/afa/.fa/charts.

  3. Name the file chart_name.xml, where chart_name is the name you choose for the chart.

  4. Add the CHART tag to the file, using the information in Chart tag reference. For an example, see Chart Example.

  5. Save the file.

Chart tag reference

This reference describes the use of the chart tag and its sub-tags.

Tag syntax is presented as follows:

  • All parameters and content are presented in italics.
  • All optional elements of the tag appear in square brackets [ ].

Note: All tags, parameters, and content are case sensitive, and must be in lower case.

Syntax

chart

Description

This is the main tag for the chart. It specifies all the information included in the chart.

Parameters

None.

Subtags

Syntax

<title>title</title>

Description

This tag specifies the title of the chart.

Parameters

None.

Subtags

None.

Content

title

String. The name that you choose for the title of the chart. You can include the following variable in the title:

  • __GROUP_NAME__. The name of the device group that is analyzed by the chart (as defined in the dashboard XML file).
  • __THRESHOLD__. The value set as the "Chart_Threshold_Val" configuration item.
  • __COUNT__. The number of devices the chart displays.

Example

In the following example, if the number of devices in the chart is 8, and the chart analyzes the group "ALL_FIREWALLS", the title of the chart is "8 Devices with lowest security rating in group ALL_FIREWALLS".

<title>__COUNT__ Devices with lowest security rating in group __GROUP_NAME__</title>

Syntax

<variable_name [color="color"] [value_condition="value_condition"] [bar_name="bar_name"]>variable_name</variable_name>

Description

This tag specifies the variable that the chart displays.

Parameters

color

String. The color of the bar or series of the variable, expressed in #RGB.

This parameter is for count type and trend_count_group type charts, and the default chart type only.

This parameter is optional.
value_condition

String. A condition, such that, only devices with a variable value that passes the condition will be counted.

This parameter is for count type and trend_count_group type charts only. For trend_count_group type charts, only equality is supported, and the value is stated without the operator.

Note: For trend_count_group type charts, this variable is an integer.

This parameter is optional.
bar_name

String. The label of the bar.

This parameter is for count type charts only.

This parameter is optional.
function

String. An aggregate function used to compile the chart data. All aggregate SQL functions are supported (for example: "avg", "min",and "max").

This parameter is for trend_value type charts only.

This parameter is optional. The default function is the average function, which compiles the average of the data over the group.
legend

String. The label of the variable in the legend.

This parameter is for trend_value type charts only.

This parameter is optional.
sum

String. The sum of the statistic type.

This parameter is for sum_over_time and trend_sum_over_time type charts only.

This parameter is optional.

Subtags

None.

Content

Variable Content Options

Available Statistic Type.

Specifies this...
rules simple_count

The number of rules for each device.
covered_rules simple_count

The number of covered rules for each device.
special_case_rules simple_count

The number of special case rules for each device.
unused_rules simple_count

The number of unused rules for each device.
security_rating simple_count

The security rating for each device.
highest risk_level

The highest risk level of each device.
PCI compliance_pass

Whether a device meets PCI compliance.
high risks_per_risk_level

The number of high risks for each device.
suspected_high risks_per_risk_level

The number of suspected high risks for each device.
medium risks_per_risk_level

The number of medium risks for each device.
low risks_per_risk_level

The number of low risks for each device.

Example

In the following example, the color of the bars for this variable will be #cb3333, only devices with a variable value of 3 will be counted, and the label of the bars for this variable will be "high".

<variable_name color="#cb3333" value_condition="=3" bar_name="high">highest</variable_name>

Syntax

<statistics_type>statistics_type</statistics_type>

Description

This tag specifies the type of statistic that the chart displays.

Parameters

None.

Subtags

None.

Content

Content Options

Specifies this...
simple_count

The count of the variable for each device. This statistic type is available for the following variables: rules, covered_rules, special_case_rules, unused_rules, and security_rating. For example, if the statistic type is simple_count, and the variable is rules, the chart will display the number of rules for each device.

Note: When the simple_count statistic type is used with the security_rating variable, the security rating for each device is displayed.
risk_level

The risk level of each device. This statistic type is available for the highest variable. When this statistic type/variable combination is used, the chart will display the number of devices whose highest risk is high, suspected high, medium, and low.
compliance_score

The compliance score of each device. This statistics type is available for the following variables: HIPAA, BASEL, NIST_800-41, NIST_800-53, ISO27001, NERC4, GLBA, TRM, DSD, SOX, PCI.
compliance_color

The compliance color of each device. This statistics type is available for the following variables: HIPAA, BASEL, NIST_800-41, NIST_800-53, ISO27001, NERC4, GLBA, TRM, DSD, SOX, PCI.
baseline_score

The baseline compliance score of each device (the score is the percentage of met requirements).This statistics type is available for the baseline variable.
risks_per_risk_level

The number of risks for a specific risk level for each device. This statistic type is available for the following variables: high, suspected_high, medium, and low. For example, if the statistic type is risks_per_risk_level, and the variable is high, the chart will display the number of high risk rules for each device.
total_changes

The number of changes on each device. This statistic type is available for the sum variable. When this statistic type/variable combination is used, the chart will display the total number of changes on each device.

Example

In the following example, the chart will display a simple count of the specified variable.

<statistics_type>simple_count</statistics_type>

Syntax

<type>[type]</type>

Description

This tag specifies the type of chart.

Parameters

None.

Subtags

None.

Content

Content Options

Specifies this...
count

A bar chart that specifies the count of devices for each variable.
condition

A bar chart that displays the number of devices whose variable value is greater than the Chart_Threshold_Val configuration item, and the number of devices whose variable value is not, for all devices in the group.

For details, see the Chart_Threshold_Val parameter.
trend_value

A trend chart that displays a calculation (defined by the function parameter of variable_name) of the variable values over all devices in the group, over time.
trend_condition

A trend chart that displays the number of devices whose variable value is greater than the Chart_Threshold_Val configuration item, and the number of devices whose variable value is not, for all devices in the group, over time.

For details, see the Chart_Threshold_Val parameter.
trend_count_group

A trend chart that displays the total count of the variable for all devices in the group, over time.
sum_over_time

A bar chart that displays the accumulation of the statistic for each device in the group.
trend_sum_over_time

A trend chart that displays the accumulation of the statistic, over time.

empty (default)

A bar chart that displays the count of the variable for each device in the group. There can be multiple variables per device.

Example

In the following example, the chart will be a bar chart that displays the total count of the variable for each device in the group. For example, if the chosen variable is unused_rules, the chart will display a bar chart with the count of unused rules per device.

<type>count</type>

Syntax

<limit>[limit]</limit>

Description

This tag specifies the number of devices the chart displays. This tag is only for bar charts.

Parameters

None.

Subtags

None.

Content

Integer. The number of devices the chart will display. If left empty, the LIMIT tag defaults to 25.

Example

In the following example, the chart will display 6 devices.

<limit>6</limit>

Syntax

<order_dir>[order_dir]</order_dir>

Description

This tag specifies whether the chart starts with displaying the devices with the most of the variable or the least of the variable. This tag is only for bar charts.

Parameters

None.

Subtags

None.

Content

Content Options

Specifies this...
ASC

The bar chart will start with displaying devices with the least of the variable. For example, if the LIMIT tag is set to 6, this will produce a chart with the bottom 6 devices.
DESC

The bar chart will start with displaying devices with the most of the variable. For example, if the LIMIT tag is set to 6, this will produce a chart with the top 6 devices.

empty

The ORDER_DIR tag defaults to DESC.

Example

In the following example, the chart will start with displaying devices with the least of the variable.

<order_dir>ASC</order_dir>

Syntax

<direction>[direction]</direction>

Description

This tag specifies the direction the chart displays. This tag is only for bar charts.

Parameters

None.

Subtags

None.

Content

Content Options

Specifies this...
horizontal

The bar chart will display horizontally.
vertical

The bar chart will display vertically.

empty

The DIRECTION tag defaults to vertical.

Example

In the following example, the chart will display vertically.

<direction>vertical</direction>

Syntax

<ymin>[ymin]</ymin>

Description

This tag specifies the minimum y-axis value displayed in the chart. This tag is optional.

Parameters

None.

Subtags

None.

Content

Integer. The minimum y-axis value displayed in the chart. If left empty, the value is computed to fit the data.

Example

In the following example, the minimum y-axis value displayed in the chart is 0.

<ymin>0</ymin>

Syntax

<ymax>[ymax]</ymax>

Description

This tag specifies the maximum y-axis value displayed in the chart. This tag is optional.

Parameters

None.

Subtags

None.

Content

Integer. The maximum y-axis value displayed in the chart. If left empty, the value is computed to fit the data.

Example

In the following example, the maximum y-axis value displayed in the chart is 100.

<ymax>100</ymax>

Syntax

<days_back>[days_back]</days_back>

Description

This tag specifies the number of days back displayed in the chart. This tag is optional, and is only for trend charts.

Parameters

None.

Subtags

None.

Content

Integer. The number of days back displayed in the chart. If left empty, the value defaults to 100 days.

Example

In the following example, the trend chart will display data for the last 200 days.

<days_back>200</days_back>

<!-- This is an AFA dashboard chart configuration file. Each dashboard chart is configured by one such file. The user defined files should be in '<AFA home dir>/.fa/dashboards/charts'.
Note: The tags and properties in this file are case sensitive. A chart is configured by the 'CHART' tag. -->

<CHART>

<!-- The 'title' tag determines the title that will be displayed at the top of the chart. The title can contain several parameters which will be replaced by the appropriate values: __GROUP_NAME__ - The AFA devices group whose data will be compiled in this chart (as defined in the dashboard XML) __THRESHOLD__ - The threshold stated in the "Chart_Threshold_Val" configuration Item __COUNT__ - The number of devices compiled for the charts. -->

<title>Number of devices by leading risk severity in group __GROUP__</title>

<!-- The 'type' tag determines the chart type. The default type (if no value is specified) will cause each variable (there may be several, representing different series) value to be plotted for each group member. Available types are: count - Count each variable over all group members condition - Count values greater than the "Chart_Threshold_Val" configuration item trend_value - For each time frame, calculate the property over the group members defined by the function property of varible_name (the default is average) trend_condition - For each time frame, count values greater than the "Chart_Threshold_Val" configuration item trend_count_group - For each time frame, count the variable over all group members -->

<type>count</type>

<!-- 'statistics_type' - The type of the statistics. Allowed values are: simple_count, risk_level, compliance_pass, and risks_per_risk_level -->

<statistics_type>risk_level</statistics_type>

<!-- The 'variable_name' depends on 'statistics_type' value as follows: simple_count - covered_rules, security_rating, special_case_rules, unused_rules risk_level - highest compliance_pass - PCI risks_per_risk_level - high, suspected_high, medium, low For the default type and the count type, there may be multiple variables, which will be expressed as multiple series. The variable name has the following optional attributes: 'color' - The color of the bar/line (in count types) or series (in the default type), expressed in #RGB 'value_condition' - The condition to apply on statistics value to count (for example: ">3", "=2"...). For count type charts only. For trend_count_group type chart the condition is strictly equality and the value is stated without the operator (for example: "3", "2"...). Only values passing the condition will be counted. 'bar_name' - The label for the bar. For count type only. If not present than the condition will be taken. 'function' - An aggregate function to use when compiling the data on trend_value type charts. The default is 'avg', which averages the data over all devices. All aggregate SQL functions are supported (for example: 'min', 'max') 'legend' - The label of the variable in the legend. Relevant for trend_value chart type only. -->

<variable_name bar_name="high" value_condition="=3" color="#cb3333">highest</variable_name><variable_name bar_name="suspected high" value_condition="=2" color="#ff8213">highest</variable_name><variable_name bar_name="medium" value_condition="=1" color="#fcf00a">highest</variable_name><variable_name bar_name="low" value_condition="=0" color="#e4c67e">highest</variable_name>

<!-- A chart may have several additional configurable properties, specified by the following tags: 'order_dir' - The ordering of the results: asc (ascending) or desc (descending). The default is descending. For default type bar charts only. In case of multiple variables (multi-series chart), the sort is based on the first variable. 'limit' - How many results to show, combined with 'order_dir' creates a top-X/bottom-X charts. Default is 20. Relevant for the default type only. 'direction' - The direction of the chart: horizontal or vertical. The default is vertical. Relevant for bar charts only. 'ymin' - The minimum value of the Y axis. The default is auto computed to fit the data. 'ymax' - The maximum value of the Y axis. The default is auto computed to fit the data. 'days_back' - The number of days back to show in a trend chart. -->

</CHART>

Configure a custom dashboard

Configure a custom dashboard by specifying the charts that the dashboard includes, the relevant device group, and the number of charts that appear in a row.

Do the following:

  1. Open a terminal and log in as user afa.

  2. Create a new file in /home/afa/.fa/dashboards.

  3. Name the file <dashboard_name>.xml, where <dashboard_name> is the name you choose for the dashboard.

  4. Add the DASHBOARD tag to the file, with the additional CHARTS and CHART sub-tags.

    For more details, see Dashboard tag reference and Dashboard configuration example.

Dashboard tag reference

The following table describes the DASHBOARD tag and its subtags.

Tag name Description
DASHBOARD

Identifies the dashboard and specifies how charts are oriented. Includes the CHARTS sub-tag.

Parameters include:

  • name. String. The dashboard name. This name appears at the top of the dashboard.

  • columns. The number of charts that appear in each row of the dashboard.

    The charts will be filled in order of appearance, from left to right and top to bottom.
CHARTS

Defines all the charts that appear in the dashboard.

Includes several CHART sub-tags.
CHART

Defines the type of data in the chart, and which device group's data appears in the chart.

Parameters include:

  • group. String. The name of the AFA device group that is analyzed in the chart.

  • definition_file. String. The name of the chart XML file.

    Specify a custom chart that you created and saved in the <AFA home dir>/.fa/dashboards/charts directory, or a built-in chart.

Dashboard configuration example

The following code shows an AFA dashboard configuration file, including a DASHBOARD tag and CHARTS and CHART sub-tags.

        <DASHBOARD columns="2" name="Summary">
 <CHARTS> 
  <CHART definition_file="total_risks_per_type_per_fw.xml" group="ALL_FIREWALLS"/>
  
        <CHART definition_file="security_rating_trend.xml" group="ALL_FIREWALLS"/>
  
        <CHART definition_file="rules_per_fw.xml" group="ALL_FIREWALLS"/>
  
        <CHART definition_file="covered_rules_per_fw.xml" group="ALL_FIREWALLS"/>
 
        </CHARTS>
        
</DASHBOARD>