Using CQL reports
CQL reports let you query your entities with Cortex Query Language (CQL) and visualize the raw results. Use them when you need to extract, analyze, or share detailed data that goes beyond pass/fail checks, or when you want a reusable report that refreshes on its own.
CQL reports give you more flexibility than Scorecards or Query builder:
View any expression result, such as the exact number of incidents, deployment counts, or custom data values for each entity. Scorecards and Query builder require expressions to evaluate to a boolean.
Build custom reports that aggregate and display data from entity metadata, integrations, and custom data.
Debug Scorecard results by surfacing the underlying data that drives rule outcomes.
Export filtered data for further analysis or sharing.
Creating a CQL report
Users with the Run Query Builder permission can create and run a CQL report. To run queries on third-party integrations, the Run Query Builder with Third-party Integrations permission is also needed.
To create a CQL report:
From the main sidebar, expand Tools, then select CQL reports.
In the upper-right corner of the CQL reports page, click Create CQL report.
Do one of the following:
Click Start from scratch to build your own report.
Select a template to start from a prebuilt report.
Templates include your organization's own and Cortex's built-in options, so your report follows best practices from the start.
Configure the report details:
In the Details section:
CQL report name - Enter a name for the report (required).
Description - Enter a description for the report. This helps others in your workspace understand the purpose of the report.
Enable auto refresh - Toggle on this setting if the report should be automatically evaluated on a specified interval.
Evaluation window - Set how often Cortex evaluates the report. Cortex evaluates the report every 24 hours by default. The shortest window you can set is 12 hours and the longest is 336 hours. Choosing a longer window can help you stay within your integrations' rate limits.
In the Apply to specific entities section:
Narrow the report's scope by selecting entity types from the Search entity types dropdown. Leave it blank to apply the report to all entities.
Advanced options - Refine your selection further by including or excluding groups. You can test and iterate on a CQL expression as you write it.
You can't query third-party integrations when refining the entity selection for a CQL report.
In the Columns section:
Click Add column to add new CQL expressions to the report. When you add or edit columns, choose how to define them: write a CQL expression in the Query builder, or select rules from your configured integrations in the Form builder. In the Add column side panel, do the following:
From the CQL tab:
Click Add CQL query to open the Query builder.
Add and test your query.
Click Save query.
Under Name, enter a name for the column (required).
Optionally, enter a description of the column.
Click Save column.
From the Form tab:
Select an integration from the Integration dropdown.
Select a rule from the Rule dropdown.
Under Name, enter a name for the column (required).
Optionally, enter a description of the column.
Click Save column.
If you want your report to be publicly available to other users in your workspace, toggle on Public.
Click Create.
To edit an existing CQL report:
Open the CQL report you want to edit.
In the upper-right corner of the page, click Edit.
Make any necessary changes, then click Save.
Viewing a CQL report
To view a CQL report, expand Tools from the main sidebar, then select CQL reports.
Sorting and filtering a CQL report
Every CQL report has a toolbar above the results table. Use it to narrow a report down to the entities and columns you care about.
You can sort by each column of the report, select which columns are displayed, search across the values in any of the report's columns, and filter by AWS account, AWS region, domain, entity, entity type, group, owner, or team.
Sorting the results
Click a column header to sort by that column, then click it again to reverse the direction.
You can also click the sort button in the toolbar, which is labeled with the field you're currently sorting by, e.g. Name. Select a column, then click the arrow next to your selection to switch between ascending and descending.
Choosing which columns appear
Click Display to show or hide columns. Click Show all to turn on every column, or Reset display to go back to the report's default columns. Click Done when you're finished.
Filtering the results
In the toolbar, click Filter.
Select a field from the panel on the left: AWS accounts, AWS regions, Domains, Entities, Entity types, Groups, Owners, or Teams.
From the dropdown, select the values you want to keep. Search for a specific value, click Select all, or turn on Show only selected to review what you've picked.
Repeat for as many fields as you need.
Click Apply.
The Filter button shows how many filters are active. To remove one filter, click the trash icon on its card. To clear all of them, click the X next to the filter count, or click Reset filters. Cancel discards any changes you haven't applied yet.
Sharing a CQL report
A report must be set to Public in order to share it.
You may need to share a CQL report with teams or leaders to provide detailed, custom insights into entity data, compliance, or operational metrics.
In the upper-right corner of the page, click Export CSV to download a CSV file of the report data:
Large reports can take a while to download. While the download is in progress, click Email me in the notification in the bottom-right corner of the page to have the CSV sent to your Cortex login email instead:
Refreshing a CQL report
Cortex doesn't refresh a CQL report on its own unless you turn on auto refresh. The top right of a report page shows when its data was last refreshed, or tells you the data has expired and needs a refresh.
To refresh a report manually:
Open the report.
Click the overflow menu icon in the upper-right corner of the page.
Click Refresh CQL report.
To enable auto refresh:
Auto refresh is off by default. You can turn it on while you create a CQL report, or edit an existing report to add it later.
Open the report.
In the upper-right corner of the page, click Edit.
In the Details section, toggle on Enable auto refresh.
Set the Evaluation window (in hours). Cortex evaluates the report every 24 hours by default. The shortest window you can set is 12 hours and the longest is 336 hours. Choosing a longer window can help you stay within your integrations' rate limits.
Click Save.
If a report contains expressions written with an outdated version of CQL, a warning banner at the top of the page tells you the report can't be refreshed. Update the outdated queries, then refresh the report.
Using CQL reports to debug Scorecards
You can use CQL reports to help interpret unexpected results from Scorecards.
For example, let's say you have a service that is failing the rule README created. However, you believe the service does have a README, and you aren't sure why it's failing this rule.
You can create a CQL report from scratch and add a new column for the README CQL expression to check for README.md in the git repo:
After saving the CQL report, you can view the results to see the contents of README files for each entity. In this report, you can see if the README contains an error such as "The result is too large to store," which would explain why the entity is failing that rule in the Scorecard.
Last updated
Was this helpful?