Question on transaction stage in XQL

JadenEvanger — Wed, 04 Jun 2025 19:11:54 GMT

It doesn't appear that the documentation on the transaction stage in XQL is very clearly documented. Does anyone know what the transaction stage really does? Does, and what it uses to "find transactions"?

Does it just find instances of contiguous events with the same value in the fields provided?

Re: Question on transaction stage in XQL

A.Elzedy — Tue, 24 Jun 2025 19:20:56 GMT

Hi Jaden,

--I know you probably already know this stuff, but writing it down in case someone else stumbles across this later--

Think of a transaction as a way to group related events together that happen around the same time or involve the same things (like the same computer, user, or process).

Instead of looking at individual events scattered across your data, transactions help you see the full story by connecting events that belong together.

Why Use it?

Real-world example: Imagine you want to track what happens when a specific program runs on a computer. Without transactions, you might see:

Event 1: Program started
Event 2: Program accessed a file
Event 3: Program made a network connection
Event 4: Program ended

With transactions, you can group all these events together to see the complete picture of what that program did during its lifetime.

How Query Works

Let's break down an example:

dataset = xdr_data
| filter causality_actor_process_image_name contains "Powershell"
| fields _time, agent_hostname, causality_actor_process_os_pid, 
         actor_process_image_name, actor_process_command_line,
         actor_effective_username, actor_process_os_pid
| transaction agent_hostname, causality_actor_process_os_pid span=1H maxevents=50

What's happening step by step:

Filter: Find all events related to "Powershell"
Select fields: Pick the important information you want to see
Transaction: Group events together based on:
- agent_hostname (which computer)
- causality_actor_process_os_pid (which specific process)
- span=1H (only group events that happen within 1 hour of each other)
- maxevents=50 (don't include more than 50 events per group)

In simple terms:

The query says: "Show me everything the Powershell process did on each computer, but group the activities together if they happened within 1 hour of each other, and don't show me more than 50 events per group."

Key Transaction Parameters

span=1H (Time Window)

Groups events that happen within 1 hour of each other
Like saying "these events are related because they happened close in time"
You could use: 30M (30 minutes), 2H (2 hours), 1D (1 day), etc.

maxevents=50 (Event Limit)

Prevents any single transaction from having too many events
Keeps your results manageable
Default is 100 if you don't specify

Transaction Fields (agent_hostname, causality_actor_process_os_pid)

These are the "keys" that determine which events belong together
Events with the same hostname AND same process ID get grouped together
Like saying "group events from the same computer and same process"

What You Get Back

When you run a transaction query, XQL adds these helpful fields:

_start_time: When the first event in the group happened
_end_time: When the last event in the group happened
_duration: How long the transaction lasted (in seconds)
_num_of_rows: How many events are in this group
_transaction_id: A unique ID for this group

When to Use Transactions

Use transactions when you want to:

See the complete lifecycle of a process or user session
Understand what happened during a security incident
Track user behavior over time
Analyze application workflows
Investigate suspicious activity patterns

Don't use transactions when you:

Just want to count events or get statistics
Need to see individual events separately
Are looking for simple yes/no answers

Common Patterns

Track User Sessions

| transaction user_name, source_ip span=30M

"Group activities by user and IP address within 30-minute windows"

Follow Process Activity

| transaction hostname, process_id span=2H maxevents=100

"Group events by computer and process within 2-hour windows"

Investigate Security Incidents

| transaction user_name, asset_name span=1D

"Group daily activity by user and computer"

Remember: Transactions help you see the big picture by connecting related events, making it easier to understand what really happened in your environment.

topic Re: Question on transaction stage in XQL in Cortex XSIAM Discussions