diff --git a/docs/assets/operation_center/events/qb-aggregation.gif b/docs/assets/operation_center/events/qb-aggregation.gif new file mode 100644 index 0000000000..8999583ddd Binary files /dev/null and b/docs/assets/operation_center/events/qb-aggregation.gif differ diff --git a/docs/assets/operation_center/events/qb-aggregation.png b/docs/assets/operation_center/events/qb-aggregation.png new file mode 100644 index 0000000000..a85b09f343 Binary files /dev/null and b/docs/assets/operation_center/events/qb-aggregation.png differ diff --git a/docs/assets/operation_center/events/qb-bar-chart.png b/docs/assets/operation_center/events/qb-bar-chart.png new file mode 100644 index 0000000000..43121e0681 Binary files /dev/null and b/docs/assets/operation_center/events/qb-bar-chart.png differ diff --git a/docs/assets/operation_center/events/qb-clauses.gif b/docs/assets/operation_center/events/qb-clauses.gif new file mode 100644 index 0000000000..ecc4a52313 Binary files /dev/null and b/docs/assets/operation_center/events/qb-clauses.gif differ diff --git a/docs/assets/operation_center/events/qb-clauses.png b/docs/assets/operation_center/events/qb-clauses.png new file mode 100644 index 0000000000..d4367b9a4b Binary files /dev/null and b/docs/assets/operation_center/events/qb-clauses.png differ diff --git a/docs/assets/operation_center/events/qb-export.png b/docs/assets/operation_center/events/qb-export.png new file mode 100644 index 0000000000..b890d4829c Binary files /dev/null and b/docs/assets/operation_center/events/qb-export.png differ diff --git a/docs/assets/operation_center/events/qb-pie-chart.png b/docs/assets/operation_center/events/qb-pie-chart.png new file mode 100644 index 0000000000..eeb5e3ee55 Binary files /dev/null and b/docs/assets/operation_center/events/qb-pie-chart.png differ diff --git a/docs/assets/operation_center/events/qb-results.png b/docs/assets/operation_center/events/qb-results.png new file mode 100644 index 0000000000..119237015d Binary files /dev/null and b/docs/assets/operation_center/events/qb-results.png differ diff --git a/docs/assets/operation_center/events/qb-run.gif b/docs/assets/operation_center/events/qb-run.gif new file mode 100644 index 0000000000..98db15faba Binary files /dev/null and b/docs/assets/operation_center/events/qb-run.gif differ diff --git a/docs/assets/operation_center/events/query-builder.png b/docs/assets/operation_center/events/query-builder.png new file mode 100644 index 0000000000..230d15a628 Binary files /dev/null and b/docs/assets/operation_center/events/query-builder.png differ diff --git a/docs/xdr/features/investigate/query_builder.md b/docs/xdr/features/investigate/query_builder.md new file mode 100644 index 0000000000..99e1d2b35e --- /dev/null +++ b/docs/xdr/features/investigate/query_builder.md @@ -0,0 +1,126 @@ +# Query Builder (beta) + +Start exploring your data with the Query Builder. Hunt for threats, get analytics, create reports. The Query Builder is a simple form which allows you to build queries to explore your data. +Using this form, you can now aggregate your data to extract new insights. The Query Builder also offers the possibility to visualize data through different kinds of charts. + +At the moment, only the `Events` table is available but more tables are coming. + +![query builder](/assets/operation_center/events/qb-run.gif){: style="max-width:100%"} + +## Build your query + +Select a table to query in the `From` clause and use `Add clause` button to refine your query. + +![clauses](/assets/operation_center/events/qb-clauses.gif){: style="max-width:100%"} + +The Query Builder comes with the following clauses: + +| Clause | Description | +| --- | --- | +| SELECT | Choose columns you want to display | +| AGGREGATION | Aggregate rows with `average` / `count` / `min` / `max` / `sum` / `unique count` | +| WHERE | Define query conditions | +| GROUP BY | Group rows by identical data | +| ORDER BY | Order rows by a specific value | +| LIMIT | Limit the number of rows in results | + +### Aggregation + +Create an aggregation by using the `Aggregate` clause. Select a type of aggregation, a column and a label for your aggregation. + +![aggregation](/assets/operation_center/events/qb-aggregation.gif){: style="max-width:100%"} + +The following aggregation types are available. + +| Aggregation type | Description | +| --- | --- | +| Average | Average of a set | +| Count | Count the number of rows in a set | +| Min | Find the minimum value in a set | +| Max | Find the maximum value in a set | +| Sum | Sum of a set| +| Unique count | Count unique values of a set | + +### Operators + +Use the following operators to define your conditions in the `WHERE` clause. + +| Operator | Description | +| --- | --- | +| is | Equals (case-sensitive) | +| is not | Not equals (case-sensitive) | +| starts with | Starts with the specified value (case-sensitive) | +| does not start with | Does not start with the specified value (case-sensitive) | +| ends with | Ends with the specified value (case-sensitive) | +| does not end with | Does not end with the specified value (case-sensitive) | +| contains | Contains the specified value (case-sensitive) | +| does not contain | Does not contain the specified value (case-sensitive) | +| exists | Has a value | +| does not exists | Does not have a value | +| within | Within the specified date range | +| < | Strictly less than | +| <= | Less than or equal to | +| > | Strictly more than | +| >= | More than or equal to | + +## Run your query + +Click on `Run query` to perform a search. + +![results](/assets/operation_center/events/qb-results.png){: style="max-width:100%"} + +You can display your results in a table or select a chart type (Pie chart or Vertical bar chart). + +!!! warning + Due to the important amount of logs ingested, the Query Builder has **rate limits** to protect the platform's health. + + There are 3 **rate limits**: + + 1. **Maximum number of processed rows:** At the moment the maximum value is 10 000. + 2. **Maximum number of query:** 10 query executions are allowed per minute. + 3. **Query timeout:** A query will timeout automatically after 10 minutes. + + About the **maximum number of processed rows** limit, the Query Builder will display partial results in case this limit is reached. + +## Chart visualization + +### Pie chart + +![pie chart](/assets/operation_center/events/qb-pie-chart.png){: style="max-width:100%"} + +Use the pie chart to show how a total amount is divided between distinct groups. We have limited the max number of values in pie chart to 40 to ensure a correct display. + +- In `Label` field, select the column you want to use as a label. +- In `Value` field, select the column you want to use as a value. + +If possible, we will try to automatically select adequate columns. + +### Vertical chart + +![bar chart](/assets/operation_center/events/qb-bar-chart.png){: style="max-width:100%"} + +Use the vertical bar chart to compare values between different groups. We have limited the max number of values in vertical chart to 80 to ensure a correct display. + +- In `X-axis`, select the column you want to use. This column can be of any type. +- In `Y-axis`, select the column you want to use. This column must be a numeric value. + +## Save your query + +You can save your query to re-execute it later. +Choose a title for your query and click on the `Save` button. + +Your last result is also saved and will be displayed when you open your saved query. + +!!! note + - Saved queries are visible to all users of your community.
+ - In MSSP multi-tenancy, saved queries are not visible in sub-communities. + +## Export your results + +You can export your results in JSON Lines format. Export file will have `.jsonl` extension. + +![export](/assets/operation_center/events/qb-export.png){: style="max-width:100%"} + +JSON Lines is a convenient format for storing structured data that may be processed one record at a time. It works well with unix-style text processing tools and shell pipelines. + +See [JSON Lines documentation](https://jsonlines.org/) for more details. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index b42a5461cb..ae443ce6ed 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -233,6 +233,7 @@ nav: - Cases: xdr/features/investigate/cases.md - Events Query Language: xdr/features/investigate/events_query_language.md - Querying Events: xdr/features/investigate/querying_events.md + - Query Builder (beta): xdr/features/investigate/query_builder.md - Report: - Dashboards: xdr/features/report/dashboards.md - Automate: