Guides
Start typing to search…

Creating Detections

This guide walks through creating and configuring detections with Query Federated Detections

Creating Detections

This guide walks through creating and configuring detections in the Query.ai interface.

Prerequisites

  • Access to Query.ai with Detections feature enabled
  • Familiarity with FSQL query syntax
  • Understanding of your data sources and security monitoring requirements

Creating a Detection

1. Navigate to Detections

  1. Log into Query.ai
  2. Navigate to Detections from the main menu
  3. Click Create New Detection

2. Configure Detection Settings

Basic Information

Name (required)

  • Maximum 25 characters
  • Should clearly describe what the detection monitors
  • Example: "Failed SSH Logins"

Description (optional)

  • Maximum 350 characters
  • Provide context about what this detection monitors and why
  • Example: "Detects multiple failed SSH login attempts from the same source IP within a 15-minute window"

Scheduled State (required)

  • Active: Detection will execute on schedule
  • Paused: Detection will not execute automatically (can still be run manually)

Severity (required)

  • CRITICAL: Immediate threat requiring urgent response
  • HIGH: Significant security concern requiring prompt attention
  • MEDIUM: Notable security event requiring investigation
  • LOW: Minor security event for awareness

3. Write Detection Query

FSQL Query (required)

Write an FSQL query that identifies the security condition you want to detect.

Example - Failed Login Attempts:

QUERY authentication.*
WITH authentication.status_id = FAILURE
FROM 'Active Directory', 'Okta'
AFTER 15m

Example - Unusual Data Transfer:

QUERY network_activity.*
WITH network_activity.traffic.bytes > 1000000000 AND network_activity.status_id = SUCCESS
FROM 'Network Logs'
AFTER 1h

Example - Privilege Escalation:

QUERY process_activity.*
WITH process_activity.process.name IIN 'sudo', 'su', 'runas' AND process_activity.status_id = SUCCESS
FROM 'EDR Logs'
AFTER 30m

Query CoPilot (Beta)

Click Query CoPilot to open an AI assistant that helps build FSQL queries:

  1. Describe what you want to detect in natural language
  2. CoPilot generates an FSQL query
  3. Review and refine the query
  4. Copy the query into the Detection Query field

Note: Query CoPilot requires authentication and opens in a nested drawer. You must manually copy the generated query.

Test Query

Before saving, test your query to ensure it works correctly:

  1. Click Test Query
  2. System validates FSQL syntax
  3. Query executes against live data sources
  4. Results show match count per data source
  5. Any errors are displayed

Important: Testing is optional but strongly recommended to verify query behavior before scheduling.

4. Configure Trigger Conditions

Define when the detection should trigger an alert using natural language:

"Trigger this detection when the number of events found [operator] [threshold]"

Operators

is not zero (any matches)

  • Triggers if query returns any results
  • No threshold input required
  • Use for: Detecting presence of specific events

is zero (no matches)

  • Triggers if query returns no results
  • No threshold input required
  • Use for: Detecting absence of expected events (e.g., missing heartbeats)

is equal to

  • Triggers if match count equals exact threshold
  • Requires threshold input
  • Use for: Detecting specific count of events

is not equal to

  • Triggers if match count does not equal threshold
  • Requires threshold input
  • Use for: Detecting unexpected count variations

is greater than

  • Triggers if match count exceeds threshold
  • Requires threshold input
  • Use for: Detecting excessive activity

is greater than or equal to

  • Triggers if match count meets or exceeds threshold
  • Requires threshold input
  • Use for: Detecting minimum activity levels

is fewer than

  • Triggers if match count is below threshold
  • Requires threshold input
  • Use for: Detecting insufficient activity

is fewer than or equal to

  • Triggers if match count is at or below threshold
  • Requires threshold input
  • Use for: Detecting maximum activity levels

Threshold

For operators that require a threshold:

  • Enter a non-negative integer
  • Minimum value: 0
  • Represents the number of matching events

Examples:

  • "greater than 5" - Triggers when 6 or more matches found
  • "equal to 0" - Triggers when no matches found
  • "fewer than 10" - Triggers when 9 or fewer matches found

5. Configure Match Eagerness

Determines when detection evaluates during query execution:

Exhaustive (default)

  • Waits for query to complete across all data sources
  • Provides accurate total count
  • Use when: Exact count is required for threshold evaluation
  • Slower but more accurate

Eager

  • Evaluates as soon as threshold is met
  • Stops search immediately when threshold reached
  • Use when: Speed is more important than exact count
  • Faster but may not reflect total matches
  • Reduces costs for expensive searches

Example: With threshold "greater than 5" and Eager mode:

  • Search stops at 6th match
  • Alert dispatched immediately
  • Total matches may be higher but aren't counted

6. Set Detection Schedule

Choose how often the detection runs:

Hourly

Runs every hour at specified minute past the hour.

Minute options: :00, :05, :10, :15, :20, :25, :30, :35, :40, :45, :50, :55

Example: Selecting :15 runs at 00:15, 01:15, 02:15, etc. (UTC)

Use for: High-frequency monitoring of critical security events

Daily

Runs once per day at specified time.

Configuration: Select hour and minute (UTC timezone)

Example: 10:00 UTC runs once daily at 10:00 AM UTC

Use for: Daily security posture checks, compliance monitoring

Weekly

Runs once per week on specified day and time.

Configuration:

  • Select day of week (Sunday through Saturday)
  • Select hour and minute (UTC timezone)

Example: Monday at 09:00 UTC runs every Monday at 9:00 AM UTC

Use for: Weekly security reviews, periodic compliance checks

Important: All times are in UTC timezone. Convert local times to UTC when scheduling.

7. Configure Alert Destinations

Select where alerts should be sent when detection triggers.

Selecting Destinations

  1. Click the Alert Destinations dropdown
  2. Select one or more configured destinations
  3. Selected destinations appear as chips with platform icons
  4. Remove destinations by clicking the X on the chip

No Destinations Available

If no destinations are configured:

  • Message displays: "No alert destinations configured. Create one to get started."
  • Click Create New Destination to configure a destination
  • New destination automatically selected after creation

Creating New Destination

  1. Click Create New Destination
  2. Nested drawer opens for destination configuration
  3. Configure destination settings (see Alert Destinations)
  4. Save destination
  5. Return to detection configuration with new destination selected

Note: Detection form state is preserved during destination creation.

8. Save Detection

Form Actions

Next (Detection Configuration tab)

  • Advances to Alert Configuration tab
  • Disabled if Detection Configuration is invalid
  • Validates all required fields before proceeding

Back (Alert Configuration tab)

  • Returns to Detection Configuration tab
  • Preserves all form state

Save

  • Saves detection and keeps drawer open
  • Disabled if form is invalid or unchanged
  • Displays success message on completion
  • Resets form dirty state

Finish

  • Closes drawer
  • Disabled if unsaved changes exist
  • Prompts for confirmation if form is dirty

Cancel/Close

  • Closes drawer without saving
  • Label changes to "Cancel" when form has unsaved changes
  • Prompts for confirmation if unsaved changes exist

Form Validation

The form validates:

  • Name: Required, max 25 characters
  • FSQL Query: Required, must pass syntax validation
  • Scheduled State: Required
  • Severity: Required
  • Frequency: Required
  • Schedule fields: Required based on frequency selection
  • Alert Destinations: Optional (detection can exist without destinations)

Validation occurs:

  • On blur for each field
  • Before advancing to Alert Configuration tab
  • Before saving

Inline error messages display below invalid fields.

Detection Configuration Examples

Example: Critical Failed Logins

Name: "Critical Failed Logins"

Description: "Detects 10+ failed login attempts from same IP within 15 minutes"

Severity: HIGH

Query:

QUERY authentication.*
WITH authentication.activity_id = LOGON_FAILED AND %ip = '1.2.3.4'
AFTER 15m
FROM 'Active Directory', 'Okta', 'AWS CloudTrail'

Trigger: "is greater than 10"

Eagerness: Eager (stop at 11 matches for fast alerting)

Schedule: Hourly at :00

Destinations: Slack, PagerDuty

Best Practices

Query Design

  1. Be Specific: Target specific event types and data sources
  2. Use Time Windows: Always include AFTER clause for time-bound searches
  3. Test Thoroughly: Test queries before scheduling to verify behavior
  4. Optimize Performance: Use filters to reduce data scanned

Threshold Configuration

  1. Start Conservative: Begin with higher thresholds and adjust based on results
  2. Consider Environment: Adjust thresholds for your environment's normal activity
  3. Use Eager Mode: For cost-sensitive detections where exact count isn't critical
  4. Monitor False Positives: Review and tune thresholds to reduce noise

Scheduling

  1. Match Criticality: High-severity detections should run more frequently
  2. Avoid Overlap: Stagger detection schedules to distribute load
  3. Consider Data Lag: Account for data ingestion delays in time windows
  4. Use UTC: All schedules use UTC timezone

Alert Routing

  1. Multiple Destinations: Send critical alerts to multiple destinations
  2. Severity-Based Routing: Route different severities to different teams
  3. Escalation Paths: Configure escalation in destination platforms
  4. Test Destinations: Verify alert delivery before activating detection

Next Steps

Updated 2 days ago