Skip to main content

Work in the notebook

A hunt opens on its Notebook: the Plan at the top, then the steps as an ordered list of cells you read top to bottom, each with what it found. On this page you read and approve the plan, add and arrange cells, run and edit them, review what Scout changed, read their output, and archive what you no longer need.

The Plan block​

The first cell is the hunt's Plan. It holds:

  • a status pill: Waiting for you, Scout is drafting, Scout is adding steps, Running, N failed, N steps not checked, All steps ran, In progress or Closed. N steps not checked counts steps that settled without checking anything: no source could run them (Not supported), or they timed out or were cancelled. All steps ran only shows when every step ran;
  • the question, which is the hunt's hypothesis. Click Edit to change it, or Suggest with Scout / Regenerate with Scout to have Scout draft it;
  • a byline and meta row that say where the hunt came from, such as from report or written by Scout from report with a link to the report or threat, plus the scope, owner and any ATT&CK techniques;
  • Steps: every runnable cell in notebook order. Each row shows its number, type and title, ✦ when Scout planned it, a risk tag and its state. Click a row to jump to its cell.
Risk tagWhat it means
read-onlyReads data. Changes nothing.
asks firstRuns live on endpoints, so it asks before it runs.
actionChanges something on an endpoint or tool. Always needs approval.
your decisionA decision point: the steps after it wait for you.

Steps from a playbook with several hypotheses are grouped into lanes (H1 · …). The list is open while the plan needs approval or Scout is writing; otherwise it folds to one line, such as 6 steps · 4 done · 1 needs you.

When the plan waits on you, Approve plan approves its checkpoint and every step that can be approved together. The line beside the button says what approving does at the hunt's Scout mode, for example Collaborator: approving lets Scout run the read-only steps. Endpoint steps and actions still ask in their own cell. See Approvals and Needs you.

Review what Scout changed​

Scout never changes a cell silently. Two kinds of cell carry a bar with Keep and Undo:

BarWhat it meansKeepUndo
New · ScoutScout wrote this cell. It has not run.Keeps the cell. Nothing runs until you run it.Removes the cell. It never ran, so nothing is lost.
Changed by ScoutScout rewrote the query or renamed the cell. Show change shows the old and new query line by line.Keeps Scout's version.Puts back the query and title from before Scout's change.

When Scout has written or changed several cells, the Plan block says so, for example Scout wrote 3 new cells and changed 1, with Keep all and Next to walk through them. Steps waiting for approval already have Approve and Reject, so they don't get a second pair of buttons. Keeping a new cell is remembered for you in this browser.

To stop Scout changing cells while you work, pause Scout.

Cells​

Each cell has a gutter on the left, with a run control and an execution mark such as [3] ✓, [5] ✕ or [*] for a cell that is running, and a body with the cell's type, title, who planned and ran it, its content and the output of its latest run.

The cell's header names who did what: ✦ Scout when Scout planned the cell, and ran by with the person (or Scout, or Auto-run) who ran it last. A query cell also has one chip that says where it runs and in which language, such as Federated: Okta · SQLite, Data lake · KQL or Live: and the endpoint. A cell that takes a value from an earlier cell shows a uses row, for example uses ← [2] Failed logins. Click the chip to jump to that cell.

CellWhat it holds
PlanThe question and the steps. See The Plan block.
SectionA heading that groups the cells beneath it until the next section. Scout adds one for each batch it plans or rewrites; click the title to rename yours.
QueryA query against your connections or the data lake.
Task, Checkpoint, Action, Watcher, AnalyticThe other step types, with the same controls the Flow view offers: Approve / Mark done on a task, Approve step / Refine / Abort on a checkpoint (under Your approval is needed), and so on.
NoteFree-form markdown between cells. Note opens a draft; nothing is saved until you click Save note.
Endpoint transcriptA console session saved from an endpoint with Save to hunt: its commands, times and outcomes, with the output tables when output was included. Read-only; it never runs. See Save a console session to a hunt.
Endpoint check, Endpoint snapshot, Endpoint action, Endpoint watchWork on one endpoint from inside the hunt. See Endpoint cells.
Telemetry viewA view of your shipped telemetry pinned to the hunt. See Telemetry view cells.
VerdictAlways last: a summary of the outcome, with Conclude. See Conclude a hunt.

The count above the cells names notes separately, for example 4 cells · 2 notes, or No runnable cells yet · 1 note.

Run a cell​

The gutter's run control is the cell's own run button: Run cell on a cell that hasn't run, Run cell again on one that has. On a stale cell it turns amber, and on a failed cell red; then it runs the cell and everything below it (Run again (and downstream)). The cell's ⋯ menu adds Run this cell only.

To run one cell:

  1. Hover or focus the cell.
  2. Click its run control in the gutter, or press ⌘⏎ / Ctrl+⏎.
  3. Watch the gutter: it shows [*] while the cell runs, then the outcome.

Each query step searches the hunt's time window, or the last 24 hours when the hunt has none. After a run, the result header says which window the step used, such as Ran over 2–9 Nov.

To run more, use Run ▾ in the hunt header: Run cell, Run from the focused cell, Run all or Run stale. See Run ▾. Steps that need approval pause a run; see Approvals and Needs you.

Queries with parameters​

A query cell that hasn't run and still contains a {{parameter}} shows an input for each one. Run (or Approve & run) stays off, with a hint such as Fill in instance_name to run, until you fill them in. The values are saved with the cell and used for the run.

When a run reaches a cell whose parameters are still empty, the cell isn't marked failed. It says Waiting for parameter values, the steps after it wait too, and Needs you lists it. Fill in the values and run the cell, and the hunt carries on from there.

Edit a query cell​

  1. Click Edit in the cell's header, or click the query text.
  2. Change the query in the editor. It's the same editor the query workspace uses. Drag the grip under it to make it taller; it remembers the height.
  3. Click Run to save and run it, or Save without running.
  4. Press Esc to leave without saving.

A new blank query cell opens in the language you last saved a query in.

If you type a description rather than a query into an empty query cell, the description becomes the cell's title and Scout writes the query into that cell. It doesn't run until you run it.

Edited since run. A cell you edit after it ran says Edited since run, and a cell whose inputs changed says Stale. Its old output stays visible, dimmed, under a line that says why, until you run it again. Run stale in Run ▾ re-runs every stale cell.

Out-of-date titles. If you change a query that has a meaningful title, the cell says The query was edited: this title may no longer describe it. Click Update title with Scout to have Scout retitle it, or Keep as is.

What a cell found​

The output under a runnable cell says what happened, in one word first:

OutputWhat you see
FailedThe error, with Run again (this cell only) and Fix with Scout. Cells that failed for the same reason say same error in cell N. To change the query yourself, use Edit.
N rowsA preview of the first three rows, flagged rows highlighted, and Open in Results for the full table in the Evidence view.
No rowsA one-line explanation. A clean run is a result, not an absence. Check why (also Check why no rows in the cell's ⋯) checks whether the query could have matched. On a query that ran on a connected tool, it explains that the query was translated into the tool's own calls, suggests removing comments and simplifying OR conditions, and shows the query as sent, with any parameter that wasn't filled in. On other queries it can't re-check, it suggests a wider time range or asking Scout why it found nothing.
RunningA progress bar; the gutter shows [*].
Not runNothing yet. On a concluded hunt, Not run (hunt closed).
Waiting for approvalA step Scout proposed. See Approvals and Needs you.
Rejected — not runSomeone declined this proposed cell, so it never ran. It doesn't count as failed.
Not decidedA checkpoint nobody answered before the hunt moved on.

Fix with Scout does not overwrite the failed cell: Scout writes a new cell that replaces it, badged v2 of N, and the original is marked replaced by N. Keep the original for the record or Archive it from the cell's ⋯ menu. Archived cells stay in place, dimmed, and drop out of counts, the Evidence view and the entity count (Hide archived at the top of the notebook hides them entirely). The Cell archived message has Undo, and an archived cell offers Restore in its header. Anyone who can edit the hunt can restore a cell.

Scout's read of a cell's results shows as two lines with More. More opens the full read and any steps Scout suggests next; Add as cell asks Scout to add that step after this cell.

Scout's discovery probes, the schema lookups it ran to learn a store, fold into one strip, N cells · Discovery, with Show to open them.

Checked on test data​

When Scout writes a lake query for a hunt with ATT&CK techniques, it first runs the query on public recordings of those techniques from the test lake. The cell shows the result as a badge in its header, so you know the query can find the attack before it runs on your data:

BadgeWhat it means
Checked on test data · finds the attack in N recordingsThe query returned rows on N recordings of the hunt's techniques
Checked on test data · no rowsThe query ran but found nothing in any recording. Check its fields, values and table.
Checked on test data · the query failedThe query didn't run on the recordings, for example because of an unknown column
Not checked on test data · only lake queries can beThe query targets a connection, not the lake

Hover the badge for the recordings it ran on, with the rows found in each, and when it was checked. The check runs on public test data only, never on your telemetry, and the rows it found are never evidence in your hunt. See Check a hunt query before it runs.

Add, move and remove cells​

  • Add cell sits just above the verdict, where new cells land. It offers Query, Note, Section, Endpoint and Telemetry view (where available), Scout cell (Scout reviews the hunt so far and proposes the next cells) and From Library…. Hover the gap between any two cells for a + with the first three cell types in place.
  • New cells go above the plan's closing checkpoint, such as Review the findings, not after it.
  • Hover or focus a cell for its header actions: Edit on a query cell, Open, and the cell menu (⋯). The menu offers Insert above… / Insert below…, Move up / Move down, Run this cell only, Show on canvas, then Archive and, for a cell that has never run, Delete…. Deleting asks first, names the cell, and removes it from the flow as well.
  • A query cell you cancel with nothing typed is removed for you. A new cell you save or run stays.
  • Open in a query cell's header opens it in a query tab that stays linked to the step. A strip above the results reads Hunt step with the step's title and Runs update this step, with Show in notebook. Edit and run the query there and the cell updates, with no duplicate step.

Add a note or a section​

  1. Click Note or Section under Add cell, or use Insert above… / Insert below… in a cell's ⋯ menu to put it at that spot.
  2. For a note, write in markdown and click Save note. Nothing is saved until you do.
  3. For a section, type its title. Click the title later to rename it.
KeysAction
j / kMove focus down / up through cells
a / bInsert a query cell above / below the focused cell (with nothing focused, at the end)
⌘⏎ / Ctrl+⏎Run the focused cell. The same keys run a query from inside the cell's editor. Outside an editor, ⇧⏎ works too.
EscLeave an edit

Next steps​