Write It Up

It is 16:40 and you have the answer. Two machines, one loader, a domain that stopped resolving on Tuesday, and a reasonably confident story about how it got in. The ticket wants a closing comment. Somebody will ask about this in a fortnight, somebody else will hit the same tooling next quarter, and the version of this investigation that exists in your head expires around the time you go home.

This is the step everyone skips, and skipping it has a specific cost that is easy to name: the next analyst rediscovers what you established. Not the conclusion, which they can read in the ticket, but the reasoning behind it, which nobody can reconstruct. A write-up that works is one where the platform itself carries the finding forward, so nobody has to remember to look.

What will I know by the end?

How to record a conclusion so it applies automatically wherever the file turns up next, how to turn the indicators you established into a report that keeps matching, what counts as an indicator and what deliberately does not, and how to hand the finding to an executive, a colleague, or another system.

Why this works

Three ideas carry this one, and the first is what separates a write-up here from a write-up in a ticketing system.

A conclusion recorded on the entity travels with it. An opinion set on a file applies wherever that file turns up next, for whoever finds it, without anyone searching for your ticket. The record and the finding are the same object, which is why this step is not administration.

A report keeps matching in both directions. Indicators you establish today are checked against everything your environments already hold and everything that arrives afterward. So the write-up is not a description of what happened; it is a detection that runs from now on.

The reasoning is the part that cannot be reconstructed. The conclusion is one word and the next analyst can read it in the ticket. Why you reached it, what you ruled out, and what nearly changed your mind are what disappear when you go home, which is why the comment field is the highest-value thing on this page.

This is also the one page here that no automation finishes for you. Backstory investigates and returns a report, but it does not set opinions, build your threat report, or write the YARA rule, so this step stays yours regardless of how the investigation was run.

Step 1: Record the conclusion on the entities themselves

Before any document, set opinions. This takes five minutes and it is the part with the most leverage, because it changes what everybody else sees rather than what one person can find.

An opinion is your team's own verdict, recorded in Stairwell and kept alongside the automated one. Inside your environment it takes precedence, and it travels: the file you marked Malicious shows your conclusion when a colleague reaches it from a completely different direction, including inside somebody else's variant list.

• Malicious on what you established. Marking it makes that the verdict readers of your environment see.
• Trusted or Benign on what you cleared. This also stops the notifications those files were generating and takes them out of threat report match counts, which is how an investigation makes the next one quieter instead of noisier.
• Grayware for the dual-use tool that was not the intrusion and is not welcome either.

Opinions apply to hostnames and IP addresses as well as files, from the same control on their panels. A conclusion about infrastructure is worth as much as a conclusion about a binary and is recorded the same way. See Network Intelligence.

Write the comment every time. The value of a conclusion is mostly in the reasoning, and the reasoning is the part that decays fastest. Name what you established, what you established it from, and what you did not check. The History tab keeps who decided, when, in which environment, and what the previous value was, which is what makes the record defensible rather than merely convenient.

If you judged a cluster in the Variants pane, you can set opinions there without leaving the investigation, which is usually faster than opening each file.

Step 2: Who is this for?

Four audiences, four different artifacts, and the mistake is producing one artifact and hoping. Decide before you write.

Most real write-ups need the first two. The third comes up when the incident was visible. The fourth comes up once and then forever, because it gets automated.

Step 3: Turn what you found into a threat report

Write your own report. This is what converts an investigation into coverage, and it is the difference between a finding and a durable one.

A threat report is a named set of indicators that Stairwell matches against the files you have already collected as well as everything that arrives afterwards. The vendor reports you subscribe to work that way, and yours works exactly the same way. So the hashes you established this afternoon keep matching backwards across your own history and forwards across everything that arrives next month, without anyone remembering to re-run a search.

From the Threat Reports page, use Add threat report. It has two paths.

Create, when the indicators are in your head and your notes. Give it a name, a description, and paste the indicators into the Add IOCs field. You can attach a sample file and a YARA rule file at the same time, which is worth doing when you have either: the sample makes the report self-contained for whoever reads it next, and the rule generalizes past the exact hashes.

Upload, when the intelligence already exists as a document. It takes a .txt, .json, or .stix file, or a URL pointing at one, plus a name and a report source. This is the path for a vendor PDF's indicator list, a CERT advisory, or output from another platform.

Write the description as though the reader has no context, because in six months that reader is you. What the campaign or incident was, when you worked it, what the indicators are drawn from, and what you concluded. A report named investigation-4471 with an empty description is a list of hashes nobody trusts enough to act on.

Step 4: What counts as an indicator?

Hashes, hostnames, IP addresses, and YARA rule names. That is the set, and the boundaries of it are worth understanding before you assemble your list.

Filenames are not indicators, and this is deliberate. Stairwell used to surface corpus files that shared a filename with a report and stopped, because filename matching produced phantom matches. In the case that ended the practice, a report showed seven matches in a customer environment while none of the report's hashes matched a file there at all. All seven were files that shared two filenames with the report, and both filenames belonged to legitimate libraries that the malware in question impersonated. Two of the seven were first seen years before the campaign existed.

The lesson generalizes past the feature. A filename is chosen by whoever wrote the file, and an attacker chooses one precisely because it looks innocent. So a filename is not evidence, it is not treated as evidence, and it should not be the load-bearing detail in your write-up either. Put the filenames in your prose, where they help a colleague search their own logs, and keep them out of your indicator list.

Two more things to get right while you are assembling it.

• Rank your own indicators by strength. A hash is a statement about one exact file. A hostname or address may be shared hosting that ten thousand unrelated things also use. Say which is which in the description, because the person reading a match on your report is going to want to know.
• Leave out the infrastructure you know is noisy. A content delivery network or a public resolver in your indicator list produces matches on everything and teaches your team to ignore the report.

Step 5: Subscribe, tune, and notify

A report that nothing subscribes to matches nothing. Three moves finish the job.

Subscribe the environments that should be covered. Coverage is per environment, which is how a service provider runs one report across many customers without mixing their data, and how you scope a finding to the fleet it concerns.

Expect to tune it, and tune it narrowly. If one of your own indicators turns out to match legitimate software, silence that indicator for that report in that environment rather than unsubscribing. Right-click the indicator in the report's IOC list and choose Silence hash, Silence hostname, or Silence IP address, with a comment. Unsilence reverses it. Narrow is the whole point: an over-broad silence is how a real match gets missed later. The Alert Is a Legitimate IT Tool covers that decision properly.

Configure a trigger, so a match reaches a person by email or webhook rather than waiting to be noticed in the UI. A report nobody is notified about is a report somebody has to remember to check.

Step 6: Hand it to a human who does not use Stairwell

If the investigation ran in Backstory, the document already exists. The report toolbar's download button produces one self-contained HTML file that renders exactly as it appears in the app and opens in any browser with nothing installed. Nothing is fetched from anywhere, so it works as an email attachment, on an air-gapped machine, and as an evidence artifact filed against a ticket. See Sharing a Backstory Report.

For a colleague who does use Stairwell, send the link instead. They land on the live investigation, can click through to the evidence, and can record their own verdict if they disagree with yours. The link is not a bypass: whoever opens it still needs access to the investigation's environment.

Treat the downloaded file as sensitive. It contains machine names, file paths, hashes, and your incident narrative, and unlike the link it carries no access check with it.

Machine-readable output for a ticketing system or a SOAR playbook goes through the API, which returns the verdict and summary, the immediate actions as a flat list, the full report, and the classified remediation export.

What makes a write-up other people can act on?

The mechanics above are the easy half. These are the habits that decide whether anyone can use what you wrote, and every one of them is a sentence you either write or do not.

• Separate what you established from what you inferred. Both belong in the write-up. Mixing them is what gets the whole document discounted when one inference turns out wrong.
• State presence and timing as presence and timing. A sighting records that a file was on a machine at a path from a date. It is not a record of execution, and Stairwell is not inline and not a network enforcement point. Where you have execution evidence, say where it came from. Where you have presence, say presence. This single discipline is what makes a security write-up survive review.
• Name the assets, the dates, and the environments. "Two machines" is a summary. The asset names with first-seen and last-seen is a finding somebody can act on tonight.
• Say what you did not check. Fleet coverage as a number, the machines with no forwarder, the file types outside the collected set, the log source that had already rolled over. An answer with its limits attached is more useful than a broader one without them, and it is the version that holds up in a fortnight.
• Record the negatives. "Run-to-Ground on the loader returned nothing else on any other machine" is a real finding and it is what shrinks an incident. Nobody writes it down, and the next analyst redoes it.
• Leave the query. The one-line search that found it, pasted into the ticket, is the cheapest thing in this list and often the most reused. See StairQL and Example Queries.

What should I read next?

• What Is a Threat Report?, for what a report does once it exists and what counts as a match.
• Setting Opinions, for the values, what each one changes, and the audit trail.
• Sharing a Backstory Report, for the three shareable forms of a finished investigation.
• Executive Exposure Assessment, for the version of this written for someone who reads one paragraph.