Report templates

A hunt report template is an ordinary Markdown file that defines what your hunt reports contain. Its ## headings become the report's sections, and the prose under each heading tells Scout what belongs in that section.

Nothing in your template is copied into a report. It is instruction, not content.

Every organization starts on the Huntbase default template, Threat hunt report. Supplying your own makes it the default for every hunt in that organization, which is how you make Scout's reports match the format your team already reviews, files, or hands to a client.

Whoever generates a report can still pick another template for that report: your organization's, Threat hunt report, or the Incident / hunt investigation report, which is built on the analyst's investigation timeline, notes and tags. See Choose a template.

The 30-second version

This is a complete, working template:

## Executive Summary

State the verdict first, then what was established and whether anyone must act
today. Plain language — no technique IDs, no tool names.

## What We Found

One item per finding: the observation, the systems affected, when it happened,
and your confidence. Order by significance.

## Recommended Actions

Concrete follow-ups, each traceable to evidence in this hunt. Leave empty when
nothing needs doing.

Headings become sections in the order you write them; the prose becomes the guidance for each. A plain Markdown file with no special syntax is a valid template — everything below is refinement.

How your file is read

What you write	What it becomes
# Heading	The document title. Only the first one counts.
## Heading	A section.
### Heading	A subsection of the ## above it.
#### Heading and deeper	Left as-is inside the parent section's guidance.
Prose under a heading	Guidance for the writer for that section.
<!-- … -->	A note to yourself. Stripped — the writer never sees it.
A paragraph starting Example:	Lifted out of the guidance (see Illustrations).
A fenced code block	Left alone. A # inside it is not a heading.

Section order in the report follows section order in your file.

Sections are suggestions, not slots to fill

This is the most important thing to understand about the format.

Scout omits a section when the hunt produced nothing that belongs in it, and records why. It does not manufacture content to fill the space. A report from a quiet hunt is legitimately shorter than a report from a busy one, and the report view lists what was left out and the reason for each.

So you can include aspirational sections without damage. A template with a "Malware Analysis" section produces that section on hunts that found malware and omits it on hunts that did not. What you must not do is write guidance that pressures the writer to produce something regardless — see What not to write.

Edit your organization's template

You need to be an owner or admin of the organization.

1. Open Settings, pick the organization from the Organization dropdown, and click Report template.
2. The badge next to the heading tells you where you stand: Huntbase default means nothing is stored and reports use the packaged template; Custom · v3 means version 3 of your own template is active.
3. Click Start from the Huntbase default to load the packaged template into the editor as a starting point. Editing an existing section's guidance is lower-risk than adding sections.
4. Write your template in the Template markdown box. The Sections this produces panel below updates as you type.
5. Click Validate to re-check on demand, then Save as new version.

Discard changes returns the editor to the active template. Saving is blocked only while the template cannot be parsed at all, or while nothing has changed.

The sections preview

The preview is the real answer to "what will my reports look like?", because the section set is the template. Each row shows the section's heading, its key, and how much guidance you have given it:

Shown	Meaning
Heading and key	The heading text, and the stable id derived from it
required	The section is asked for on every report
A field name badge	The section is bound to structured report data
120 chars of guidance	How much instruction the writer will receive. "No guidance" means the writer gets only the heading.
prose / table / list / kv	How bound data is presented

Warnings and errors

What you see	What it means
Warnings	Something was ignored and fell back to its default — an unknown directive key, a bad value, a duplicate section key, an unclosed example block. Warnings do not block saving; the template works as written. Read them anyway, because a silently-defaulted setting is not doing what you intended.
This template can't be parsed	The template is rejected and cannot be saved. The most common cause is a file with no ## heading.
The saved template no longer parses	Your stored template has become unparseable. Reports fall back to the Huntbase default until you fix it.

You will never lose a report to a template mistake — an unparseable template falls back to the packaged one rather than failing the report.

Version history

Saving never overwrites the previous version. Each save deactivates the old one and keeps it, because every report records the template that produced it and old reports have to stay explainable.

Load into editor brings an old version's Markdown back so you can save it forward as a new version. Revert to Huntbase default puts new reports back on the packaged template; your saved versions stay in the history, and reports already generated are unaffected.

Writing guidance that works

Guidance is read by a model that has the hunt's evidence in front of it and must decide what to say. Write it the way you would brief a competent analyst who has never seen your reporting standards.

• Say what belongs, in what order. "Lead with the verdict, then the affected systems, then confidence" beats "Summarise the findings."
• Say what to do when there is nothing. Every section will eventually meet a hunt with no material for it. "Say plainly when none were observed — it is a meaningful result" prevents both padding and silent omission.
• Name the audience. "Write for someone who will read nothing else" changes the output far more than "keep it brief."
• Draw the line between observation and inference. Sections that mix them are where reports go wrong. If you want them separated, say so.
• Say what does not belong. Exclusions are as useful as inclusions: "no technique IDs in this section", "only indicators this hunt observed", "do not enrich from general knowledge."
• Be specific about form when you care. "One row per finding", "one sentence", "under 200 words". Vague length guidance produces vague length.

Two or three tight paragraphs per section is the right size. Guidance longer than the section it governs starts to compete with the evidence for the writer's attention.

What not to write

Worked examples in the guidance. The single biggest failure mode. A fully-formed sample finding — "we identified command-and-control infrastructure communicating with three internal hosts" — is the likeliest thing in your whole template to be reproduced verbatim in a real report as a real finding. Describe the shape you want instead of demonstrating it.

Demands for data you do not collect. A section requiring endpoint process telemetry, on a deployment with no endpoint coverage, is omitted on every report. That is correct behaviour, but you have added noise rather than structure. Check your coverage first.

Pressure for volume. "List at least five findings", "always include detection rules", "this section must not be empty" all push toward invention. Ask for what the evidence supports.

Meta-commentary and transitions. "The next section covers our detailed analysis" is guidance to a human reading your template, not to a report writer. Its only effect is to dilute the instruction around it.

Two sections that want the same content. Overlapping sections produce either duplication or an arbitrary split. Merge them, or state the boundary explicitly in both.

Illustrations are handled separately

A section whose prose substantially restates its own guidance is treated as having no real content: it is omitted with a reason, and the report records why. That is a backstop against a model paraphrasing your instructions back at you — but it also means guidance written as sample output rather than as instruction can cause the section to be dropped.

If you do include an illustration, mark it, either as a paragraph starting Example: or with an explicit block:

<!-- hb:example -->
An IOC row for an observed C2 domain, the hosts that contacted it, and the
confidence in the attribution.
<!-- /hb:example -->

Marked illustrations are pulled out of the guidance and shown to the writer under an explicit illustration-only label, which makes reuse of their contents much less likely. Unmarked prose that reads like a finding gets no such protection.

Directives

Directives are optional. They are HTML comments, so they stay invisible wherever your template is rendered. Put one directly under the heading it configures.

## Key Findings
<!-- hb:section key=key_findings required=true render=table max_words=400 -->

Key	Values	Default	Effect
key	identifier	slug of the heading	Stable id for the section. Set it if you may rename the heading later.
required	true / false	false	Ask for this section on every report. Use sparingly — only where absence would be a defect.
render	prose / table / list / kv	prose	How bound data is presented. A table shows only a summary of a rich item: bound recommended actions render their step-by-step instructions in prose but not in table.
on_omit	hide / note	hide	When omitted: drop the section, or state that it was not assessed and why. note suits sections where silence is ambiguous — an IOC section, for instance.
max_words	positive integer	none	Soft word budget.
bind	a field name (below)	none	Render this section from structured report data instead of prose.
pass	evidence / synthesis	derived from bind	Which writing pass fills the section.

Name and version the template itself with a file-level directive:

<!-- hb:template id=acme-soc version=3 -->

Both appear in the reference recorded on every report generated from the template, so bump version when you change it materially — old reports stay explainable.

Bind a section to report data

A bound section is built from typed report data rather than retyped by the model, so its values are guaranteed to match what the hunt actually produced. Use it for anything tabular or enumerable:

key_findings, entities_of_interest, mitre_techniques, detection_candidates, recommended_actions, follow_up_hunts, lessons_learned, telemetry_gaps, recommendations

Four more render the analyst's own records as written. Scout never rewrites them:

Field	Renders
investigation_timeline	The hunt's investigation timeline, oldest first, in UTC, leaving out events marked False positive
affected_systems	Each system named on the timeline, with when it was first and last seen
compromised_accounts	Each account named on the timeline, with when it was first and last seen
analyst_notes	The hunt's notes with their authors

The shipped Incident / hunt investigation report uses all four. For example:

## Timeline of Attacker Activity
<!-- hb:section key=attack_timeline bind=investigation_timeline render=table on_omit=note -->

A bound section renders even if the writer skips it — the data is the content, so it cannot be lost to the writer forgetting the section. A bound section whose data turns out empty is treated as an omission rather than left as a bare heading.

An unrecognised bind value is ignored with a warning and the section is written as prose, so a template written against a newer build still works on an older one.

The two writing passes

You rarely need to think about this. A report is written in two passes: the evidence pass writes the analytical sections from the hunt's evidence, then the synthesis pass writes the parts that summarise the whole report — the executive summary, the risk assessment, the verdict — from the first pass's output rather than from the raw data.

The order is the point. A summary written alongside the findings can only restate what the hunt set out to test; written afterwards, it reports what was actually established.

Sections bound to executive_summary, risk_assessment or conclusion are assigned to the synthesis pass automatically, so a template that never mentions passes still splits correctly — including one that renames every heading. Override it with pass=synthesis when a section summarises the report in your own words:

## Bottom Line for Leadership
<!-- hb:section key=bottom_line pass=synthesis -->

Limits

• Maximum template size: 64 KB
• Maximum sections: 40 — beyond that, later sections are dropped with a warning
• A template with no ## heading is rejected

What is checked regardless of your template

Every generated report is checked before it is stored, independently of your template, and anything found is recorded on the report so a short or hedged report reads as honest rather than broken:

• Indicators — addresses, hashes, email addresses, URLs — are matched against what the hunt actually observed. Ones it never saw are removed from the indicator list, and occurrences in prose are marked [unverified] rather than deleted, so nothing disappears silently and nothing is silently trusted. Treat an [unverified] value as unconfirmed: do not put it in a blocklist without checking it first.
• Citations — sections stating specifics without citing a hunt node are flagged, and citations to nodes outside the hunt are removed.
• Techniques and detections — malformed MITRE technique IDs are dropped, and detection proposals carrying neither a rule nor guidance are flagged.
• Premises and durations — specifics from the hunt's hypothesis that the report restates without any evidence behind them, and durations that appear nowhere in the evidence, are flagged unverified. These are flagged only, never removed.
• Draft reports — a report generated while the hunt is still open is flagged as a draft.

Findings from these checks appear at the top of the report when they affect how it should be read, and at the foot when they are routine bookkeeping such as a count of omitted sections. None of it is configurable from a template, and none of it can be switched off by one.

tip

Change one thing, generate a report, read it, then change the next. A template edit is only really validated by a report written against it.

Next steps

• Hunt reports — generating, reading and downloading reports
• Organization management — roles that can edit the template
• Settings overview — the rest of the settings surface