PQL Reference

The following is the PQL reference for Case Creation.

Rule Anatomy

Every rule contains these components:

Writing Rules (Pipe Query Syntax)

Rules use a pipe query syntax where each stage is separated by |. The general format is:

filter <conditions> | time_window <duration> <type> | create_case group_by <fields> [when <threshold>]

Complete Examples

Simple rule — group all alerts by user in 4-hour windows:

time_window 4h hopping | create_case group_by incident.user

Filtered rule — detect rapid bulk downloads from sanctioned apps:

filter incident.dlp_user_activity = 'download' case_insensitive
AND incident.app_instance_is_sanctioned = true
| time_window 30m tumbling
| create_case group_by incident.user when group.evidence_count >= 30

Multi-condition rule — large file uploads to unsanctioned apps:

filter incident.file_size >= 104857600
AND incident.file_type in ['sql', 'bak', 'zip', 'dump'] case_insensitive
AND incident.dlp_user_activity in ['upload', 'share', 'send', 'uploadandshare'] case_insensitive
AND incident.app_instance_is_sanctioned != true
| time_window 1h tumbling
| create_case group_by incident.user

DLP policy match — detect PCI policy violations:

filter incident.dlp_policy_name contains 'PCI'
| create_case group_by incident.user when group.evidence_count >= 1

Combined conditions — high severity incidents matching a specific DLP rule:

filter incident.dlp_incident_severity = 'High'
AND incident.dlp_rule_names contains 'Name-CC-EXP'
| create_case group_by incident.user when group.evidence_count >= 1

Example Use Case

A user wants to write a Case Rule that excludes DLP incidents whose enforcement action is allow at the policy level (typically Real-Time Protection Inline policies that are informational/monitoring-only). The desired semantics lead to: don’t create a case if ALL DLP matches on the incident have action = ‘allow‘.

Problem:

• The enforcement action lives in the nested dlp_match_info[].dlp_action array, which is not exposed in the UDM as a top-level filterable field.
• Current PQL array operators express any-match (or its negation), not all-match.

Solution:
Expose dlp_action as a filterable UDM field and add only_contains operator to PQL grammar

incident.dlp_action only_contains ['allow', 'useralert', 'add_headers'] – lets you skip cases when every action is in any set you pick (e.g., all informational: allow / useralert / add_headers).

Solution Example:

filter NOT (incident.dlp_action only_contains ['allow'] case_insensitive)
| time_window 1h tumbling
| create_case group_by incident.user when group.evidence_count >= 1

Filter Conditions

Filters narrow down which alerts a rule processes. Filters are optional — omitting the filter stage means the rule matches all incoming alerts.

Operators

Modifiers

Boolean Logic

Combine conditions with AND and OR. Use parentheses for grouping:

filter incident.dlp_incident_severity = 'High'
AND (incident.dlp_rule_names contains 'PCI'
     OR incident.dlp_rule_names contains 'SSN')

Available Fields

All filterable and groupable fields use the incident. prefix. These fields are part of AISecOps’s Unified Data Model (UDM) and represent normalized DLP incident data.

File Fields

Application Fields

User Fields

DLP Policy Fields

Device Fields

Notes on Array Fields

Fields like dlp_rule_names, dlp_policy_name, and dlp_profile_name are arrays. When used with contains, the filter checks whether any element in the array matches the substring. For example:

filter incident.dlp_rule_names contains 'SSN'

This matches any incident where at least one triggered DLP rule name includes “SSN”.

Note: Array fields cannot be used in group_by clauses.

Time Windows

The time window defines how alerts are bucketed into time periods for grouping.

Syntax:

time_window <duration> <type>

Duration

Specified as a number followed by a unit suffix:

Window Types

How It Works

1. Each incoming alert’s timestamp is normalized to the window boundary
2. Alerts in the same window with the same grouping key are combined
3. Multiple windows can be active simultaneously (e.g., the current hour and the previous hour)

Example: With time_window 1h tumbling:

• Alert at 13:45:30 -> window [13:00:00, 14:00:00)
• Alert at 14:15:30 -> window [14:00:00, 15:00:00)

If the time window is omitted from the pipe query, the system uses a default time window.

Grouping (group_by)

The group_by clause defines which fields create distinct groups. Alerts with identical values for all group-by fields (within the same time window) are combined into one group.

Syntax:

create_case group_by <field1>, <field2>, ...

Examples

Choosing Grouping Fields:

• Broad grouping (fewer fields): Catches more related activity in each case but may be noisy. Example: group_by incident.user creates one case per user.
• Narrow grouping (more fields): Creates more targeted cases. Example: group_by incident.user, incident.app_name, incident.dlp_user_activity separates upload activity on Dropbox from download activity on Google Drive for the same user.

Restrictions:

• At least one field is required
• Array fields (dlp_rule_names, dlp_policy_name, dlp_profile_name) cannot be used in group_by
• Derived fields (computed from expressions) cannot be used in group_by

Case Creation Threshold

The threshold determines when a group has accumulated enough evidence to become a case.

Syntax:

create_case group_by <fields> when group.evidence_count >= <number>

If when is omitted, the default threshold is evidence_count >= 1 (a case is created as soon as the first matching alert arrives).

Examples

Choosing a Threshold:

• Low thresholds (1-5): Best for high-severity scenarios where even a single incident warrants investigation. Example: any SSN detection should create a case.
• Medium thresholds (10-30): Good balance for moderate-severity patterns. Example: bulk download detection where occasional downloads are normal.
• High thresholds (50-100+): Best for noisy, low-severity patterns where volume is the signal. Example: many small file uploads to unsanctioned apps.

Group Lifecycle

Understanding how groups progress helps in tuning rules:

active  -->  ready  -->  promoted (case created)
  ^                          |
  |                          v
  +---- need_update (late-arriving alerts after case creation)

• Active — Group is accumulating evidence (alerts are matching and being added)
• Ready — Group has met the case creation threshold
• Promoted — Group has been converted into a case for investigation
• Need Update — New alerts arrived after the group was already promoted; these are attached to the existing case

Default Rules

When a tenant is provisioned, AISecOps creates a default rule:

This rule groups all DLP incidents by user in 4-hour windows and creates a case for each user with at least one incident. It is disabled by default and must be explicitly enabled.

Out-of-the-Box Rule Templates

AISecOps ships with several pre-built rule templates that address common DLP scenarios:

Exfiltration Preparation

Large File Movement

Small File Volume

DLP Policy Detection

Limits and Constraints