Investigation Notebooks
Record an investigation as a timeline of searches, alerts, notes and pivt analysis, share it with teammates and turn it into a case's investigation record.
Start a notebook to keep a running record of your investigation. While it is active, nano captures your searches and the alerts and detections you work with; you can add notes, entities, IOCs, timeline markers, and pivt analysis.
Every case has a notebook, which is the case's investigation timeline. You can also keep standalone notebooks for hunts that aren't (yet) a case.
Availability: notebooks are part of Cases, included with nano Self-run. pivt features need an AI provider configured and AI assistance turned on in AI & pivt settings.
Start a notebook
Start a notebook from the notebook panel, give it a title, choose its visibility and, optionally, capture the search you're on as its first entry. The new notebook becomes your active notebook, and captures go to it until you switch, pause or close it.
A notebook's status is one of:
| Status | Meaning |
|---|---|
active | Open and capturing |
paused | Open, not capturing |
closed | Finished |
merged | Merged into another notebook |
Permissions: notebooks:view, notebooks:create, notebooks:edit, notebooks:delete and notebooks:share. A case's notebook follows the case's permissions: editing it needs cases:edit.
What gets captured
With an active notebook, nano adds entries automatically for:
- Searches you run, with the query and result summary.
- Alerts you view or action (acknowledge, close, disposition).
- Detection rules you view or change.
You add the rest yourself: notes, entities, IOCs, timeline markers and links to alerts and rules, with the @ commands below. pivt adds suggestions, summaries and chat replies as their own entries.
@ commands
Type @ in the notebook input to open the command menu.
| Command | What it adds |
|---|---|
@search <description> | pivt turns your description into an nPL query. |
@pivot | pivt suggests follow-up queries from the investigation so far. |
@summarize | pivt summarizes the investigation so far. |
@alert | Links an alert (pick from a list). |
@detection | Links a detection rule (pick from a list). |
@ip, @user, @host, @hash, @domain, @email, @url, @file, @process | An entity reference, such as @ip 203.0.113.10 or @user bob.wilson. |
@ioc <value> | Marks a value as an indicator of compromise. |
@timeline <text> | A timeline marker, optionally with a time. |
@mention | Mentions a teammate to bring them in. |
These are notebook entries. The pivt panel has its own command set; see pivt @ commands.
Queries pivt writes
pivt writes nPL against OCSF 1.9 paths, the same as you would. For "PowerShell with encoded commands, by host and user":
class_uid=1007 process.name="powershell.exe" process.cmd_line="*-enc*" | stats count by device.hostname, actor.user.nameA @pivot from a suspicious source IP might suggest:
class_uid=3002 src_endpoint.ip="203.0.113.10" | stats count by user.name, statusReview a generated query before you rely on it. For the paths each class uses, see OCSF field reference.
pivt chat
The notebook's chat lets you ask pivt questions with the notebook as context. pivt can run searches and add results, suggestions and replies to the timeline.
To use it you need melod:notebook, notebooks:view and notebooks:edit. pivt answers with the permissions you have: it can only run searches if you have search:execute.
Notebooks and cases
The case's notebook is its investigation record:
- Created with the case. A notebook is created when a case is assigned to an analyst, when a case is created with an assignee, or immediately when auto-investigation is on. Reassigning the case transfers the notebook.
- Case events are mirrored. Status changes, assignment changes and merges appear in the notebook timeline, with the before and after values.
- One timeline. The case's Investigation tab shows the notebook timeline: captured searches, notes, pivt entries and case events together.
- Summaries use the case. pivt summaries of a case notebook include the case's title, severity, status, disposition and description.
From a standalone notebook you can:
- Escalate to a case (
notebooks:editandcases:create): creates a case assigned to you, with this notebook as its investigation notebook. - Merge other notebooks into it: their entries are copied in and the source notebooks are archived.
- Unlink a notebook from its case (also needs
cases:editon the case).
Automated case investigation writes into the case notebook too. See Case Management.
pivt's standalone wizards — detection generation, rule tuning, dashboard generation and similar — are separate from notebooks. They open in their own pages and don't write to a notebook.
Share a notebook
| Visibility | Who can see it |
|---|---|
private (default) | You, plus anyone you share it with |
shared | Members of the groups you choose |
public | Everyone in your organization |
Only the owner manages sharing. Share with individual users at one of two levels:
| Permission | Allows |
|---|---|
view | Read the timeline |
edit | Add and change entries |
References
A notebook can reference alerts, detection rules, saved searches and cases. GET /api/notebooks/by-reference lists the notebooks you can see that reference a given item.
Notebook API
| Method and path | Purpose |
|---|---|
GET, POST /api/notebooks | List or create notebooks |
GET /api/notebooks/active | Your active notebook |
GET, PUT, DELETE /api/notebooks/{id} | Read, update or delete a notebook |
GET, POST /api/notebooks/{id}/entries | List or add entries |
PUT, DELETE /api/notebooks/{id}/entries/{entry_id} | Change or remove an entry |
POST /api/notebooks/{id}/share | Set visibility |
GET, POST /api/notebooks/{id}/shares, DELETE …/shares/{share_id} | Manage user shares |
GET, POST /api/notebooks/{id}/references, DELETE …/references/{ref_id} | Manage references |
GET /api/notebooks/by-reference | Notebooks that reference an alert, rule, saved search or case |
POST /api/notebooks/{id}/escalate | Escalate to a case |
POST /api/notebooks/{id}/merge | Merge notebooks into this one |
POST /api/notebooks/{id}/unlink | Detach from its case |
POST /api/notebooks/{id}/chat, …/chat/stream | pivt chat |
Practices
- Start early. Start the notebook when you start looking, so the first searches are captured.
- Mark what matters. Use
@iocfor confirmed indicators and@timelinefor the moments a later reader needs. - Write down why. A short note on why you ruled something in or out saves the next analyst from repeating the work.
- Summarize before handoff. Run
@summarizebefore a shift change or escalation, then read and correct it.
Troubleshoot
Need help with these checks? Contact support with the affected deployment, request ID and time with timezone.
Searches are not being captured
Check that the notebook is active. Captures stop when you pause or close it and move to another notebook when you switch.
Notebook chat returns 503
The AI service is unavailable. The rest of the notebook remains usable; record notes and searches while chat is unavailable.
What's next
Alerts & Incident Response
Triage nano alerts from detection rules: alert states, acknowledging and closing with a disposition, bulk actions, filters, metrics and troubleshooting.
Dashboards
Build nano dashboards by hand, from search results or with the AI wizard: chart types, drilldown, variables, auto-refresh, sharing and troubleshooting.