Reports

Introduction to reporting¶

The reporting module allows users with the appropriate credentials to build or view reports about data in the system. These reports can cover things like vulnerability trends, ticket loads, and top risk areas.

Reporting within Brinqa is extremely flexible and powerful due to the graph data model and our use of API calls to retrieve data. It allows the system to dynamically create subsets of data based on any attributes in a data model, provide in-report filtering, and display data on reports more quickly.

Clicking the Reports icon in the left navigation bar will take you to the Reports page, which displays a list view of all existing reports.

Table 1: List view contents

Creating a new report¶

1. Navigate to the Reports module using the left navigation bar.
2. Click Create Report
3. Fill in the following and click Create:

Table 2: New report properties

Adding inputs¶

Once you have created your report, you can start adding elements. One of these elements is Inputs, which allow viewers of the report to dynamically filter its contents. For example, you could create a ticket report that initially displays information about all existing tickets then, by changing a user input, display the same visualizations with ticket data for one particular staff member.

1. Click the + Add Inputs button at the top right of the screen. This will take you to the Edit Report modal
2. Select a Data Model from the drop down at the bottom of the modal. The inputs available on a report will be limited to attributes or related attributes of this data model.
3. Click the Inputs tab on the left.
4. Click Add Input
5. Add the following information and click Update:

Table 3. New input properties

Once they’ve been created, input fields can be edited or removed using the pencil and X buttons above the fields on the report.

Creating report layout¶

Creating the body of a report consists of first creating layout elements like columns and rows, then adding Sections containing data visualizations to those columns and rows.

Below, all buttons on the report builder UI are described. The buttons that pertain specifically to structuring the layout mention rows or columns.

Table 4: Report builder UI

Buttons	Description
	Adds a row to the report
	Adds an input to filter data in report
	Edit report/View source: if located at the top right of the page Edit column: if located at the top right of a column Edit section: if located at the top right of a section within a column
	Add column to associated row in report
	Remove associated row from the report
	Add a single visualization section to associated column. Visualization options listed below.
	Remove associated column from the report

Available sections/visualizations¶

Sections on a report contain individual data visualizations, which are described below. To see more in-depth information about visualizations, navigate to the Visualizations article in the documentation.  

Table 5: Report visualizations

Creating a visualization¶

1. Click the Section button associated with the column where you want the visualization
2. Select a visualization type and fill in the following:

Table 6: New visualization properties

Measures¶

Measures and dimensions are how you choose exactly what information is displayed in your visualization.

Measures are calculations performed on objects within the system. In Brinqa applications, you select an aggregate function and the objects of that function are determined by the data model you select. So, for example, if you select the Ticket data model and Count function, the calculation you receive is the total number of tickets.

Table 7. Measure functions

Dimensions¶

Dimensions are how data from the selected measure will be grouped. For example, in a visualization of total tickets per month, “total tickets” is the measure and “per month” is the dimension. The count of total tickets is divided into groups according to the month in which they were created.

All attributes of a data model will be selectable as dimensions, but some will make more sense than others as sorting options. In general, the only ones that will never make good candidates for dimensions are completely unique attributes like ID.

Multiple dimensions can be selected for the same visualization. This allows you to display things like total vulnerabilities per business unit per quarter.

Transformation¶

Dimensions that use timestamp attributes will have a transformation option when you select them, which allows you to determine the granularity of the dimension. For timestamps this means whether you’d like to look at the year, quarter, month, week or day of the timestamp.

Buckets¶

Dimensions that use numeric attributes (including timestamps, which are stored as integers) will have a bucket option. Buckets allow you to set ranges for dimensions. For example, vulnerability risk scores run from 0 to 10 but could be put into buckets of low (0-2), medium (3-6), and high (7-10) if that was a more desirable way of viewing the information.  

Configuring appearance¶

Once a visualization has been created users can modify its appearance, including the colors, grid lines, max values, and how the data stacks.

Most visualizations have the same appearance options, but tables and single value visualizations have slightly different modals. The tables below will cover each version of appearance modification.

1. Click the edit button associated with the visualization
2. Select Display and fill in the following:

Table 8. Display properties for line, area, column, bar, pie, donut, heatmap, and treemap charts

Single value and angular gauge appearance¶

Table 9. Appearance properties for single value and angular gauge visualizations

Table appearance¶

Tables have one central appearance setting, which is how values in columns render. There are a number of ways to render values including as links, icons, star ratings, and sparklines. You can also set simpler rendering options, like how many decimal places appear for numeric values.

Table 10. Table column rendering options

Using filters¶

The Filter option allows you to fine-tune the data that appears in a visualization, showing only relavant subsets.

1. Click the edit button associated with the view
2. Select Filters.
3. Add filters using the filter clause interface:

Table 11. Filter clause interface

Making more attributes filterable¶

If you don’t see an attribute as a filtering option, it isn’t set to allow filters in the data model. This can be changed by modifying the attribute’s metadata.

1. Navigate to the application the attribute’s data model is associated with
2. Navigate to Administration > Data Management > Data Models
3. Select the data model associated with the attribute
4. Find the desired attribute on the data model and click the Actions button
5. Select Edit
6. At the bottom of the modal window, check “Supports Filter”
7. Click Update to update the attribute
8. Click Update to update the data model

Copying to other reports/views¶

Visualizations on a report can be copied to other reports or views using the Copy To function. The function will copy not just the visualization, but also any filters or appearance changes associated with it. This is useful if you have multiple reports that will require the same visualization, or want a particular visualization to appear both on a report and a dashboard.

When using the Copy To function, remember that the system considers reports a type of view.

1. Click the Edit button associated with the section you want to copy
2. Select Copy to
3. Select the view/report you want to copy the visualization to
4. Click Update

After copying a visualization to another report or view, you may want to navigate to that report/view to see where the visualization was placed. If the placement is not desirable, you can drag the visualization to a different part of the report or view. Click Done when finished with your changes.

Sharing reports¶

Reports can be shared with other users of the Brinqa application. The share functionality allows you to specify permissions, include a message, and send a link via email.

1. Navigate to the report you want to share
2. Click Share and fill in the following:
Table 12. Share report dialog            

Fields	Description
Share with	Select from the list of Brinqa users who you would like to share the report with.
Permissions	Select whether users will be able to view, comment on, or edit the report.
Message	Enter a message that will be sent to the selected users along with link to report.
Get Link	Provides a direct sharing link to the selected report.

3. Click Share

TUTORIAL: Vulnerability Overview Report¶

This tutorial will cover how to create a Vulnerability Overview report. The report will contain the following visualizations and pieces of data:

• Total active vulnerabilities
• Number of new vulnerabilities in the last 30 days
• Percent of vulnerabilities that are critical risk
• Open vulnerabilities by risk score
• Top vulnerabilities
• New vulnerabilities by data center over time

1) Create the report.¶

1. Navigate to the Reports module using the left navigation bar.
2. Click Create Report
3. Fill in the the following properties:

Table 1: New report properties

2) Select the data model and inputs for the report.¶

Inputs allow viewers of a report to filter the data they see. This report is a vulnerability overview so when a user first views it, it will show the overall status of vulnerabilities at your company as a whole. Adding inputs like “Business Unit” or “Host Owner” will allow the viewers to filter out a subset of data, so they can e.g. get an idea of the health of individual parts of the company.

For this tutorial, we will be adding the following inputs:

• Business Unit: to see an overview of risk by business unit.
• Host Owner: to see the distribution and severity of issues by host owner.

1. Click the Edit (...) button at the top right of the screen
2. Select Edit Report from the drop-down menu
3. Select “Vulnerability” as the Data Model from the drop down at the bottom of the modal. This selection will make the Inputs tab appear on the modal and determine the inputs available to you on that tab.
4. Click the Inputs tab on the left.
5. Click Add Input
6. Click the + button to the right of that row. This will create settings for an additional input.
7. Add the following information for each input and click Update:

Table 2. Report input settings

3) Add a “total active vulnerabilities” section.¶

1. Click the Add Section button and select Single Value from the menu
2. Enter “Active Vulnerabilities” for the Title
3. Select “Vulnerability” for the Data Model
4. Select “Count” for the Measures. This tells the section to display the total number (count) of vulnerabilities in the system.
5. Click Add
6. Click the Actions button associated with the section
7. Select Filters
8. Select “Status” for the first attribute, “Not Equals To” for the operator, and “Fixed” for the value. This creates a conditional statement that only vulnerabilities that are still active should be counted in the total.
9. Click Update

4) Add columns and rows to the report.¶

At this step, your report will have a single wide section at the top displaying the total number of active vulnerabilities. Before adding another section, we should add a new column to place it in. This will allow us to display several small sections next to each other and make better use of the space on the report.

To add a column, click the Add Column button.

Rows can also be added to the report, using the Add Row button.

5) Add a “new vulnerabilities in last 30 days” section.¶

1. Click the Add Section button and select Single Value from the menu
2. Enter “Vulnerabilities in last 30 days” for the Title
3. Select “Vulnerability” for the Data Model
4. Select “Count” for the Measures. This tells the section to initially display the total number (count) of vulnerabilities in the system.
5. Click Add
6. Click the Actions button associated with the section
7. Select Display
8. Enter “new” in the After Label field. This will add text after the number of new vulnerabilities.
9. Click Update
10. Click the Actions button associated with the section
11. Select Filters
12. Click the Add AND Clause button. This will allow us to set two conditions on this section.
13. Select “Status” for the first attribute, “Not Equals To” for the operator, and “Fixed” for the value. This creates a conditional statement that only vulnerabilities that are still active should be counted in the total.
14. Select “First Found" for the second attribute, “In Last” for the operator, and "30 Days" for the value. This creates a conditional statement that only vulnerabilities first found in the last 30 days should be counted in the total.
15. Click Update

6) Add a “percent of vulnerabilities that are critical risk” section.¶

1. Add a new column to the report next to the existing sections.
2. Click the Add Section button and select Single Value from the menu
3. Enter “Critical Risk” for the Title
4. Select “Vulnerability” for the Data Model
5. Select “Percentage” for the Measures. This tells the section to display the percent of vulnerabilities in the system with a specified quality.
6. Select "Risk Rating" for the Dimensions.
7. Select "Risk Rating" and "Ascending" for the Sort.
8. Click Add
9. Click the Actions button associated with the section
10. Select Display
11. Enter “%” in the After Label field.
12. On the Appearance tab, enter "red" as the background section color and "white" as the text section color.
13. Click Update
14. Click the Actions button associated with the section
15. Select Filters
16. Select “Status” for the first attribute, “Not Equals To” for the operator, and “Fixed” for the value. This creates a conditional statement that only vulnerabilities that are still active should be counted in the total.
17. Click Update

7) Add an "open vulnerabilties by risk score" section.¶

1. Add a new row to the report below the existing sections.
2. Click the Add Section button and select Column from the menu
3. Enter “Open Vulnerabilities by Risk Score” for the Title
4. Select “Vulnerability” for the Data Model
5. Select “Count” for the Measures. This tells the section to display the total number (count) of vulnerabilities in the system.
6. Select "Risk Score" for the Dimensions and check the boxes to enable buckets and use custom ranges. This will divide the total number of vulnerabilities according to risk score ranges, like between 4 and 5.
7. Enter "10" for the number of buckets.
8. Set the From and To ranges for each row as 0 to 1, 1 to 2, 2 to 3, etc.
9. Select "Risk Score" and "Ascending" for the Sort.
10. Click Add
11. Click the Actions button associated with the section
12. Select Display
13. On the General tab, check "Drilldown" and "Show values". "Drilldown" will allow reviewers to click columns to view a list of all vulnerabilities of that risk score. "Show values" will display the total number of vulnerabilities of that risk score above the column.
14. Click the Appearance tab, and check "Conditional colors" under Options.
15. Use the + button to add a row until you have ten rows.
16. Enter the 0..1, 1..2, 2..3, etc. as the values and colors of your choice as the colors. Colors can be hex codes or color words.
17. Click Update
18. Click the Actions button associated with the section
19. Select Filters
20. Select “Status” for the first attribute, “Not Equals To” for the operator, and “Fixed” for the value. This creates a conditional statement that only vulnerabilities that are still active should be counted in the total.
21. Click Update

8) Add a "top vulnerabilities" section.¶

1. Add a new column to the report next to the existing section.
2. Click the Add Section button and select Table from the menu.
3. Enter “Top Vulnerabilities” for the Title
4. Select “Vulnerability” for the Data Model
5. Leave the Measures field empty.
6. For Dimensions, select "Title", "Risk Rating", and "Risk Score".
7. Select "Risk Scoring" and "Descending" for the Sort.
8. Click Add
9. Click the Actions button associated with the section
10. Select Display
11. On the Columns tab, set the "Title" width to 75% and rendering to "Drilldown". This will allow users to click on the vulnerabilities on the table to view them.
12. Disable the "Risk Score" column. Disabling the display of the risk score allows us to sort by it while keeping the table tidier with fewer columns.
13. Click Update.
14. Click the Actions button associated with the section
15. Select Filters
16. Select “Status” for the first attribute, “Not Equals To” for the operator, and “Fixed” for the value. This creates a conditional statement that only vulnerabilities that are still active should be counted in the total.
17. Click Update

9) Add a "new vulnerabilities by data center over time" section.¶

1. Add a new row to the report below the existing sections.
2. Click the Add Section button and select Line from the menu.
3. Enter “New Vulnerabilities Over Time” for the Title
4. Select “Vulnerability” for the Data Model
5. Select “Count” for the Measures. This tells the section to display the total number (count) of vulnerabilities in the system.
6. For Dimensions, click the attribute field and scroll to the bottom. Click "Show related attributes". Select Host attributes → Business Service attributes → and then Location.
7. Add "First Found" as another attribute to the Dimensions field and choose "Week" for the Transformation field. This will show new vulnerability amounts by week.
8. Select "First Found" and "Ascending" for the Sort.
9. Click Add
10. Click the Actions button associated with the section
11. Select Display
12. On the General tab, check "Smooth Line". This will smooth the lines on the graph.
13. On the Axes tab, set the X Axis to "First Found" and Group By to "Location".
14. Click Update
15. Click the Actions button associated with the section
16. Select Filters
17. Select “Status” for the first attribute, “Not Equals To” for the operator, and “Fixed” for the value. This creates a conditional statement that only vulnerabilities that are still active should be counted in the total.
18. Click Update

10) Save the report.¶

1. Click Done in the upper right corner of the report