In this section

KQL Foundations: make-graph, graph-match and Variable-Length Paths

Module 0

Introduction

Some questions are about relationships rather than rows: which process started which, which account signed in to which machine, which machine connected to which. A table can hold relationships, one row per pair, and a join can follow them one step at a time.

When the question is about paths, a chain of relationships of some length, a graph answers it more directly. KQL builds a graph from a table with make-graph and searches it for patterns with graph-match.

This lesson turns the month's process starts into a graph of which program started which, searches it with patterns of one hop, two hops and any length, uses a property on the edges, builds a second graph of Linux administrators and the servers they reach, and answers the same two-hop question with a join to see what the graph adds.

Beyond the first hop it counts paths rather than listing them, so the graph's interesting corners stay for Module 9.

Rows9,578 processstartssummarized toEdges58 parent-to-childpairsbuilt intoGraph49 programs,58 edgesmatched byPatternexplorer.exe, thenany path to any program

Process starts summarized into relationships, built into a graph, and searched with a pattern.

This is the ground Module 9 builds on. Every query on the page runs in your browser against the same month.

01

Relationships as Edges

One row per pair, with what the pair has in common

A graph is built from edges, and an edge is a pair: a source, a target and whatever properties the pair should carry. The process table records each start with the program that started it, so summarizing by the pair of names turns 9,578 starts into the month's set of parent-to-child relationships, each with a count:

let Edges = DeviceProcessEvents
    | summarize Starts = count()
        by Parent = tolower(InitiatingProcessFileName), Child = tolower(FileName);
Edges
| summarize Edges = count(), Starts = sum(Starts),
    Once = countif(Starts == 1), Hundred = countif(Starts >= 100)

The let builds the edge table; the summarize below it describes the edges:

Edges  Starts  Once  Hundred
-----  ------  ----  -------
58     9578    15    17

58 distinct parent-to-child pairs account for all 9,578 starts. 17 pairs happened a hundred times or more, the shell starting browsers and Office, the service host starting services. 15 happened exactly once. That shape is typical: a small set of common relationships carries almost all the activity, and a long tail of rare ones carries almost none of it and most of what an investigator wants to see.

Summarizing before building a graph is a decision about what the graph means. Here an edge is a relationship between two program names across the whole estate, with how often it happened.

That throws away which device, which user and when, which keeps the graph small and makes it a map of how programs relate in this organization. A different question would keep different columns: the device in the edge key for a per-machine tree, or the first time seen as a property for questions about order.

The names were lowered with tolower() on both sides so that WINWORD.EXE and winword.exe become one node. That is the cleaning lesson again, one level up: a graph built on raw values splits one program into two nodes, and every path through it splits too.

The edge table is still an ordinary table, so everything from the earlier lessons applies to it. It can be filtered, counted and joined. The graph operators add one thing: the ability to ask about paths through it.

02

Building the Graph

make-graph, and nodes from edge endpoints

make-graph takes an edge table, names the source and target columns with an arrow between them, and builds a graph. with_node_id names the property that will hold each node's identifier, here the program name. graph-to-table reads the graph back as a table, of nodes or of edges, which is how its size can be checked:

let Edges = DeviceProcessEvents
    | summarize Starts = count()
        by Parent = tolower(InitiatingProcessFileName), Child = tolower(FileName);
Edges
| make-graph Parent --> Child with_node_id = Name
| graph-to-table nodes
| summarize Nodes = count()

The graph is built and its nodes are read back and counted:

Nodes
-----
49

49 nodes and 58 edges. Nobody supplied a table of nodes. Microsoft documents that make-graph creates a node for every source and target that appears in the edges, so every program that started or was started is a node. A node table can be added with with ... on, giving nodes properties of their own, such as a program's publisher or an account's department, and Module 9 does exactly that.

A graph built by make-graph must be followed by a graph operator, graph-match or graph-to-table; it is not a table and cannot be summarized or filtered directly. That is a useful constraint. The table work, deciding what an edge is and what it carries, happens before make-graph, and the path work happens after it, so a query reads in two clear halves.

The two counts are the graph's first check, the same check every lesson has used. Edges read back from the graph match the edges in the table, so nothing was lost in building it. Nodes are fewer than twice the edges because most programs appear in several relationships: explorer.exe is the parent in many edges and is one node.

Graph-to-table also has a practical use beyond checking: it turns the graph, or the result of a pattern, back into rows that the rest of KQL can work on. A query can build a graph, match a pattern and then summarize, join or chart what it found, so a graph is one stage of a query rather than a separate kind of query.

A graph of 49 nodes is small. Real estates produce graphs of thousands of nodes even when summarized this way, which is part of why a graph is useful: nobody can read thousands of relationships, but a pattern can search them.

03

A Single-Edge Pattern

graph-match with a condition on a node

graph-match searches a graph for a pattern. A pattern is written as nodes in parentheses joined by edges drawn as arrows, with names for the parts the where and project clauses need. The simplest pattern is one edge. Here it is anchored on the shell, explorer.exe, which starts what users start by hand:

let Edges = DeviceProcessEvents
    | summarize Starts = count()
        by Parent = tolower(InitiatingProcessFileName), Child = tolower(FileName);
Edges
| make-graph Parent --> Child with_node_id = Name
| graph-match (p)-[e]->(c)
    where p.Name == 'explorer.exe'
    project Child = c.Name, Starts = e.Starts
| order by Starts desc

Each match is one edge out of explorer.exe, projected with the child's name and the edge's count:

Child           Starts
--------------  ------
chrome.exe      759
winword.exe     729
msedge.exe      706
outlook.exe     669
excel.exe       666
powershell.exe  662
onedrive.exe    648
cmd.exe         451
pwsh.exe        302
rundll32.exe    117
mshta.exe       67

explorer.exe started 11 different programs in the month: browsers, Office applications, OneDrive, and the interpreters, PowerShell in both its versions, the command shell and mshta. The edge property Starts came through from the edge table, which is how a pattern can report the weight of each relationship it found.

A single-edge pattern answers the same question a where on the edge table would, and that is the right way to read it: a graph pattern is a filter over relationships. What makes the graph worth building is the next step, because the interesting question about an interpreter is never that the shell started it. It is what the interpreter started next.

Patterns can also be written in the other direction, with the arrow pointing left, which asks what started a given program. Both directions are the same graph read from different ends, and Module 9's process-tree lesson uses both: down from a suspicious parent, and up from a suspicious child to find how it came to run.

The names in a pattern, p, e and c here, are only labels for this query. They carry no meaning to the engine, so they should carry meaning to the reader: p for the parent, c for the child, e for the edge between them.

In longer patterns, good labels are the difference between a pattern that can be checked by reading it and one that has to be run to be understood.

The where clause in a pattern can test any node or edge property, and it can test several at once. That is what lets a pattern be specific: not every edge out of explorer, but every edge out of explorer into an interpreter, or every edge whose count is below a threshold, which Section 05 uses.

04

Paths of More Than One Hop

Two hops, and any length

Add a node and an edge to the pattern and it matches two-hop chains: the shell, a child, and what that child started. The chains are counted here rather than listed:

let Edges = DeviceProcessEvents
    | summarize Starts = count()
        by Parent = tolower(InitiatingProcessFileName), Child = tolower(FileName);
Edges
| make-graph Parent --> Child with_node_id = Name
| graph-match (p)-->(m)-->(c)
    where p.Name == 'explorer.exe'
    project Middle = m.Name, End = c.Name
| summarize Chains = count(), Middles = dcount(Middle), Ends = dcount(End)

Each match is one chain from explorer.exe through a middle program to an end program, and the summarize counts them:

Chains  Middles  Ends
------  -------  ----
32      5        24

32 distinct two-hop chains pass through 5 of the shell's 11 children to 24 different programs. Only 5 children go on to start anything at all; the browsers and OneDrive are dead ends in this graph.

25 of the 32 chains run through two interpreters, the command shell and PowerShell, and the rest through Office applications starting helpers such as the print host, which is exactly why an analyst follows interpreters first.

A path of any length within bounds is written with an asterisk on the edge: -[*1..4]-> matches paths of one to four edges. This finds every program reachable from the shell within four steps:

let Edges = DeviceProcessEvents
    | summarize Starts = count()
        by Parent = tolower(InitiatingProcessFileName), Child = tolower(FileName);
Edges
| make-graph Parent --> Child with_node_id = Name
| graph-match (p)-[*1..4]->(c)
    where p.Name == 'explorer.exe'
    project Reached = c.Name
| summarize Programs = dcount(Reached)

The variable-length edge matches every path from one to four hops, and the summarize counts distinct programs reached:

Programs
--------
30

30 programs are reachable from explorer.exe within four hops, out of 49 in the graph. That is the question a graph answers most naturally and a join answers worst: everything reachable, at any depth up to a limit, in one pattern.

Microsoft documents the min..max form for variable-length edges and does not document a maximum, and in practice the limit is the size of the result, because the number of paths grows quickly with each hop.

Bounds matter in both directions. A minimum of 1 includes the direct children; a minimum of 2 would ask only for programs reached indirectly, which is a different and often more interesting question. A maximum set too low misses deep chains, and one set too high returns paths through every common program in the estate. Choosing the bounds is choosing the question, and the query should say why.

Those 32 chains and 30 programs are where a hunt through this graph would begin, and they include some of the month's most interesting paths. Module 9 reads them; this lesson only counts them.

05

Properties on the Path

A condition on the edges themselves

A pattern can test edge properties as well as nodes. The rare relationships, the edges that happened once in the month, are often the ones worth reading first, and a pattern can find them directly:

let Edges = DeviceProcessEvents
    | summarize Starts = count()
        by Parent = tolower(InitiatingProcessFileName), Child = tolower(FileName);
Edges
| make-graph Parent --> Child with_node_id = Name
| graph-match (p)-[e]->(c)
    where e.Starts == 1
    project Parent = p.Name
| summarize RareEdges = count(), Parents = dcount(Parent)

The where tests the Starts property on the edge, and the summarize counts the matches and their parents:

RareEdges  Parents
---------  -------
15         4

15 edges happened exactly once, started by 4 different parents, the same 15 the edge table's count found in the first section. Combined with a path, a condition like this becomes powerful: every hop rare, or every hop on the same device, or every hop after a given time.

Those are questions about the shape of a path, and they are hard to write as joins because each hop would need its own join and its own condition.

The properties a pattern can test are only the ones the edge table kept. This graph's edges carry a count and nothing else, so a pattern cannot ask about devices, users or times. Section 01's decision about what to summarize is therefore a decision about which questions the graph can answer later, and Module 9's lesson on building a graph spends most of its time on it.

A rare edge is a place to look, not a finding. Some of the 15 are the unusual but legitimate: an installer run once, an administrator's one-off tool. Some are not. Telling them apart needs the details the graph summarized away, which means going back to the rows: which device, which account, what command line. The graph narrows the search; the rows decide.

This is also where the graph meets the earlier lessons. The rarest relationships are a distribution's tail, as in the fourth lesson, and reading them is reading the evidence inside a group, as make_set did there. A graph is another way to arrive at the same small set of things worth reading.

06

Who Reached Which Server

A second graph, from parsed text

Graphs are not only for processes. The accepted SSH logons parsed in the sixth lesson make a graph of administrators and the Linux servers they reached, with the number of logons on each edge:

let Logons = Syslog
    | where ProcessName == 'sshd' and SyslogMessage startswith 'Accepted'
    | parse SyslogMessage with 'Accepted ' Method ' for ' User ' from ' Source
        ' port ' Port:int *
    | summarize Logons = count() by User, Computer;
Logons
| make-graph User --> Computer with_node_id = Name
| graph-match (u)-[e]->(h)
    project User = u.Name, Host = h.Name, Logons = e.Logons
| summarize Hosts = dcount(Host), Logons = sum(Logons) by User

The edges are built from parsed Syslog text, and the pattern reads every account-to-server edge back, summed per account:

User        Hosts  Logons
----------  -----  ------
m.webb      8      157
t.ashworth  8      153
p.greaves   8      160

Three accounts reached the Linux servers by SSH in the month, and each reached all 8 of them, with between 153 and 160 logons each. The graph is complete: every administrator to every server.

That is a baseline in the shape of a graph, and a useful one, because the question an investigator asks of it is what would break the shape: a fourth account, an administrator reaching a server from an address no administrator normally uses, a server reached by an account that is not an administrator.

The edge table was built from free text, which shows how the lessons stack. parse turned sentences into columns, summarize turned rows into relationships, make-graph turned relationships into a graph, and graph-match searched it. Each step is one of the module's lessons, and the whole is four operators long.

A graph like this one also has room to grow. Adding the source address as a third kind of node, with edges from address to account, would let a single pattern follow an address to an account to a server, which is the shape of lateral movement and the subject of Module 9's lesson on connections between machines.

The logon count on each edge is what makes the graph more than a list of who can reach what. An edge with hundreds of logons is routine administration; an edge with one is an exception worth a glance, and a pattern can filter on it exactly as Section 05 filtered the process graph on its starts.

Accounts and servers are both nodes here, identified only by name. Nothing in the graph says which nodes are people and which are machines; the direction of the edges does, which is worth keeping in mind when patterns get longer and the arrows less obvious.

07

Graph or Join

The same question, two ways

A two-hop question can also be answered with a join: the edges out of explorer.exe joined to all edges on the child of the first matching the parent of the second:

let Edges = DeviceProcessEvents
    | summarize Starts = count()
        by Parent = tolower(InitiatingProcessFileName), Child = tolower(FileName);
Edges
| where Parent == 'explorer.exe'
| join kind=inner (Edges) on $left.Child == $right.Parent
| summarize Chains = count()

The left side keeps the shell's edges, and the inner join attaches every edge that continues each one:

Chains
------
32

32 chains, the same as the two-hop pattern. For a fixed, short path the two are equivalent, and the join is the more familiar tool. The difference appears as soon as the length of the path is part of the question.

Three hops is two joins; any number up to four is four separate queries unioned together; every path where each hop is rare is a join per hop with a condition each. The variable-length pattern did all of that in one line, and choosing between the tools comes down to a short climb:

Graph or join
1One fixed hop?
a parent and its childrenjoin, or a one-edge pattern
2Two or three fixed hops?
a chain of known lengtheither; a pattern reads more clearly
3Any number of hops?
everything reachable from a nodegraph-match with -[*min..max]->
4A condition on the path itself?
every hop rare, every hop same devicegraph-match, where on the edges
5Only counts per pair?
no path at allsummarize, no graph needed
Reach for a graph when the length of the path is part of the question.

The last rung is a reminder that not every relationship question needs a graph: a count of logons per account and server is a summarize. And the things a graph cannot do are as important as the things it can:

Three things a graph does not do for you
A graph shows what happened.
It shows which relationships exist; order and time are gone unless kept as properties.keep FirstSeen on edges
Node names are identities.
cmd.exe on fifteen devices is one node here.key nodes on what you mean
More hops find more.
More hops find more of everything, ordinary paths included.constrain the path
A graph is only as precise as the edges it was built from.

The first and second rows come from the same decision, what an edge is. A graph built from names across an estate is a map of habits, not a record of events, and Microsoft documents graph-match for Sentinel without listing Defender's Advanced Hunting among the places it applies, so a query meant for both should be checked there first.

What Module 9 builds

Module 9

9.1 to 9.4

relationships as a graph, building a graph, finding patterns, paths of any length

9.5 to 9.7

process trees as graphs, identity paths, connections between machines

9.8

graph or join

Module 9 builds on this lesson: relationships as a graph, building one with node tables, patterns, paths of any length, process trees, identity paths, connections between machines, and graph or join.

The habits to carry into it: decide what an edge is before building, clean node identifiers, check the graph's size against its table, anchor patterns on a known node, constrain paths with conditions, and go back to the rows to decide.

Do

Practice

Read the first hop for where to go next
prepared evidence

The prepared evidence below is the first hop from the shell: the 11 programs explorer.exe started in the month, with the number of starts on each edge. Pick the children that run commands or scripts, say what a two-hop pattern adds to this table, and decide what a low count does and does not mean. Try each question before opening its answer, and say which column decided it.

Read the counts with the interpreters in mind. A shell that starts PowerShell hundreds of times a month is an organization whose staff and tools use PowerShell, which is common and says nothing alone. The useful reading is relative: which interpreters appear at all, how often compared with each other, and which of them the two-hop count says went on to start something.

The table is deliberately the first hop and no further. Everything the questions ask about is a decision about where the next hop should go, which is the decision an analyst makes every time a graph returns more paths than can be read.

Then run the queries on this page and change them. Anchor the one-hop pattern on services.exe instead of explorer.exe and compare its children, then change the variable-length edge to -[*1..2]-> and see how many programs fall out of reach.

A graph is built from an edge table, and the edge table decides what the graph can answer. make-graph builds it, graph-match searches it with patterns of fixed or variable length, and conditions on nodes and edges make the patterns specific. For a fixed short path a join gives the same answer; when the path's length is part of the question, the graph is the tool.

The last lesson is about running queries fast and trusting what they return: filtering first, what operators cost, and checking an answer before it is used.