Chapter 16 — Technical documentation and safety
Lesson map
Lesson 16 published. Map, example, EX061.
flowchart TD
N0["Learning outcomes"]
N1["16.1 Runbooks"]
N2["16.2 Safety rules"]
N3["16.3 Handling labels in documents"]
N4["16.4 Currency"]
N5["16.5 Writing style"]
N6["16.6 Testing documentation"]
N7["16.7 Version history"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7
N7 --> EX["Worked example"]
EX --> Q["Exercise EX061"]
Logical drawing
flowchart LR
N0["Learning outcomes"]
N1["16.1 Runbooks"]
N2["16.2 Safety rules"]
N3["16.3 Handling labels in documents"]
N4["16.4 Currency"]
N5["16.5 Writing style"]
N6["16.6 Testing documentation"]
N7["16.7 Version history"]
N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> Q["EX061"]
[Learning outcomes]
|
v
[16.1 Runbooks]
|
v
[16.2 Safety rules]
|
v
[16.3 Handling labels in documents]
|
v
[16.4 Currency]
|
v
[16.5 Writing style]
|
v
[16.6 Testing documentation]
|
v
[16.7 Version history]
|
v
[Worked example] --> [Exercise EX061]
Learning outcomes
You will (1) write runbooks for CTI tasks; (2) document safety and handling rules; (3) keep documentation current; (4) write so others can act without you.
16.1 Runbooks
A runbook describes a routine task step by step: "Importing the ESX daily collection", "Requesting a DNS block", "Handling a credential-exposure notice". Each has purpose, prerequisites, steps, checks and what to do if something fails.
Runbooks let someone other than Tomás perform a task the same way when he is away. The credential-exposure runbook is the one tested in the worked example, which showed that one unclear step can stop a colleague. Each runbook links to the job documentation for any automated parts it relies on.
16.2 Safety rules
A one-page rule sheet: no contact with suspicious infrastructure; no testing of exposed passwords; TLP respected; personal data minimised; suspicious files handed to qualified staff; RFC 5737 addresses and .example domains in training material.
The sheet gathers rules that appear across the book into one page that new students can read on their first day. Each rule links to the runbook step where it applies, such as never pasting passwords into a ticket. The sheet is reviewed whenever a failure review shows a rule was unclear.
16.3 Handling labels in documents
Runbooks themselves are usually internal (TLP:AMBER) because they reveal how defences work. Examples inside them use synthetic values.
A runbook explains which logs are searched and how block lists are loaded, which would help an attacker plan around them. Labelling it AMBER keeps it within Ashgrove and the clients who need it. Synthetic examples mean the runbook can be used for training without exposing real indicators or hostnames. Some runbooks, such as credential-exposure handling, also contain personal-data steps, which is another reason to keep them internal. The label is printed at the top of every page.
16.4 Currency
Each document shows owner, last review date and next review. Changes in tools trigger reviews.
A runbook that still describes an old parser or a retired tool will mislead whoever follows it. The resolver format change in the Tuesday case triggered a review of the DNS import runbook. Owners receive a reminder when the next review date arrives, and the review result is recorded in the document. An overdue review is flagged in the team's monthly meeting. The owner either confirms the document still matches the tools or updates it the same week.
16.5 Writing style
Short numbered steps, one action each; screenshots only where needed; commands in code blocks; expected results stated after each step.
One action per step lets a reader check each result before moving on. Stating the expected result tells them at once when something has gone wrong. Commands in code blocks can be copied exactly, which avoids typing errors in hostnames and file paths. Screenshots go out of date quickly when tools change, so text is preferred. Each runbook starts with a single sentence saying when it should be used. Warnings, such as never pasting passwords, appear just before the step they apply to.
16.6 Testing documentation
A colleague follows the runbook without help. Wherever they hesitate, the text is unclear.
The colleague's hesitation in the worked example came at 'notify the identity team', where the channel was not named. Tomás watched the test without helping and noted each pause in the runbook. After the step was rewritten, the next test ran without questions, which is the test's pass condition. The colleague chosen is someone who has not done the task before, so gaps in the text are not filled from memory. Tests are repeated with a new colleague after every substantial change. The tester's name and date are recorded in the runbook's history.
16.7 Version history
Keep documents in the team's repository so changes are tracked and reversible.
The repository shows who changed a runbook, when and why, through each commit message. If a change makes a procedure worse, the earlier version can be restored. Tomás's scripts and their documentation sit in the same repository, so code and runbook changes can be reviewed together. Runbook commits are reviewed by a second team member before they are merged. Tomás writes commit messages that state which step changed and why. The repository's history then serves as a record for audits. Older versions remain readable for anyone checking how a past incident was handled.
16.8 Incident notes
During incidents, write timestamped notes in a shared document; they later become the basis for review.
Timestamped notes record decisions and checks while they are fresh, before memory changes them. They let the incident lead see what has been done without interrupting people. After the incident, the review uses them to rebuild the order of events, and gaps in them become lessons for the next incident. Each note starts with a UTC time and the author's initials. Tomás writes what was checked and what was found, not his opinions. The shared document is restricted to the incident team and the supervisor.
16.9 Accessibility
Plain language helps colleagues whose first language differs and newcomers alike.
Several help-desk staff speak English as a second language, and new placement students arrive each year. Short sentences and common words help both groups follow a runbook under pressure. Tomás avoids unexplained abbreviations and links each technical term to the team's short glossary. Tomás tests readability by asking a help-desk colleague to explain a runbook step back to him. Where the colleague's explanation differs from the intended meaning, he rewrites the step in simpler words. He avoids idioms, which can confuse readers whose first language is not English. The glossary gets new entries when a term causes confusion.
Glossary
A short glossary defines TLP, ATT&CK, STIX, indicator and runbook terms once, so documents stay brief and consistent for every reader.
Worked example
Tomás writes the runbook for credential-exposure notices. His colleague tests it and stops at "notify the identity team" — which channel? Tomás adds: "open a restricted ticket in the Identity queue; never paste passwords; attach the list as an encrypted file". The next test runs without questions.
Synthetic case. The runbook test is invented.
Errors and limits
Documentation cannot replace judgment; runbooks state when to escalate.
Exercises
- EX061 — Runbook parts. List five parts of a runbook. Rubric: 3 = purpose, prerequisites, steps, checks, failure actions; 2 = three; 1 = one; 0 = none.
- EX062 — Runbook label. Why are runbooks usually internal? Rubric: 3 = reveal defensive workings; 2 = partial; 1 = public; 0 = none.
- EX063 — Hesitation test. How was the credential runbook improved? Rubric: 3 = specified restricted ticket, no passwords, encrypted attachment; 2 = partial; 1 = vague; 0 = none.
- EX064 — Safety sheet. Name four rules on the safety sheet. Rubric: 3 = four valid; 2 = three; 1 = one; 0 = none.
Synthesis
Write tested, current, plain runbooks; keep safety rules visible; label documents appropriately.
Continue studying — chapter 16 of 18
← Chapter 15 (draft) · Course chapter index · Chapter 17 (draft) →