Question on transaction stage in XQL

[JadenEvanger]

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?

[A.Elzedy · Accepted solution]

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:

1. Filter: Find all events related to "Powershell"

2. Select fields: Pick the important information you want to see

3. 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.