Ask the stream a question.

The search bar

A search is a list of field:value terms. Every term must hold. Put a dash in front to require that it doesn’t:

action:auth.login_failed -outcome:success actor.ip|cidr:203.0.113.0/24

Modifiers work exactly as they do in a rule; the rule guide has the full list. A search holds up to 32 terms and 2,000 characters. Press / to jump to the search bar and Enter to run. An empty search reads every event in the range.

What every event carries

The What the stream holds panel counts the last seven days of events by source, action and outcome, so you can see what’s normal before asking what isn’t.

Anything richer

The search bar only joins terms with “and”. For “or”, lists of values, 1 of and all of, switch the query to YAML and write selections and a condition, as in a rule’s detection. Switching a search to YAML writes the search out for you. This is the detection behind the starter hunt for role and key changes:

roles:
  action:
    - iam.role_changed
    - iam.member_added
keys:
  action:
    - iam.api_key_created
    - iam.token_created
    - repo.key_added
condition: 1 of them

A hunt is held to the same matching budget as a workspace rule: 1,000 value comparisons per event and 2,000 compiled regex instructions. A hunt’s text is at most 16 KB. Check compiles a query and shows its cost without reading any events.

Counts, groups and events

• Range. Pick one from an hour to 400 days. Click a bar of the histogram, which splits the range into 48 slices, to zoom into it.
• Group by up to 5 fields to count matches per value, with when each was first and last seen. Sort by most common to see who dominates, or rarest to see who stands out. Past 1,000 distinct groups, the 500 most common and 500 least common come back, with the total.
• Events lists the newest 200 matches. Expand one to read the whole event.
• Pivot by clicking any value: add it to the search, exclude it, start a new search for it, group by its field, or copy it. Each pivot writes an exact-match term and runs again.

Events from a labelled drill are left out unless you tick Include drills, and the overview never counts them.

It says what it read

A hunt first asks the stream for events that could match, then decides each one with the TillTell rule matcher. What a hunt finds is exactly what the rule made from it would fire on. Each run is bounded:

When a run stops short, it says so. It shows how many candidates it checked out of how many there were and how far back it reached, and its counts and groups cover only that stretch. Scan further back continues from where it stopped. A run that checked every candidate says that too.

Questions worth asking again

Save a hunt with a name and a hypothesis: what you expect to find and why it matters. A saved hunt keeps its query, group-by, tags, range and whether it includes drills, and is shared with the workspace’s owners and admins. It records when it last ran and how many events matched, but only for runs exactly as saved. A workspace keeps up to 200 saved hunts, each with a name no other hunt in it uses, whatever the case. ⌘/Ctrl + S saves changes.

The Starters panel holds questions worth asking on the first day:

Keep watching for it

When a hunt finds something that should never happen quietly again, choose Make it a rule…. TillHunt runs the hunt once more and drafts a TillTell rule with the same detection and ATT&CK tags, at the level you pick. Its tests are made from the newest match and from an event the hunt passed over, cut down to the fields the detection reads. The draft opens in the rule editor, where you review it, adjust it and save. Like every new rule, it starts in shadow. A rule made from a saved hunt stays linked to it, and deleting the hunt leaves the rule running.

A hunt with no filter can’t become a rule, since it would fire on every event.

Hunting from a finding or an incident

On a TillTell finding, owners and admins can hunt this actor, this address, this session or this target, whichever the finding carries. The actors, addresses, sessions and targets of an incident link to a hunt the same way. Each opens TillHunt on an exact search from a day before to a day after, so you see what else happened around the moment that fired. Drill findings open with drills included.

Who can hunt, and the record it leaves

Searching the stream reads every product’s security events, so TillHunt is for owners and admins only. Every run lands in the workspace audit log with its query, range and counts, including the run behind a rule draft. Saving, changing and deleting a hunt are recorded too.

From the terminal

# what the stream holds, then the question
tilldev shield hunt overview
tilldev shield hunt run action:auth.login_failed --hours 168 --group-by actor.ip --rare

# YAML from a file, over a fixed window; then continue past where it stopped
tilldev shield hunt run --yaml hunt.yaml --from 2026-09-01T00:00:00Z --to 2026-09-08T00:00:00Z
tilldev shield hunt run --yaml hunt.yaml --from 2026-09-01T00:00:00Z --to 2026-09-08T00:00:00Z --before 2026-09-05T11:02:41.118Z,<event-id>

# compile without reading events; exits 1 on problems
tilldev shield hunt check 'actor.user_agent:*curl*'

# save it, run it as saved, turn it into a rule in shadow
tilldev shield hunt save "Failed sign-ins by address" action:auth.login_failed --group-by actor.ip --hours 168
tilldev shield hunt run --saved <hunt-id>
tilldev shield hunt rule "Password guessing from one address" --saved <hunt-id> --level high --create

The same operations are on the HTTP API under /api/shield/hunts, documented in the API reference.