◇ OpenCyber Academy
Technical · Chapter 16 · English

Chapter 16 — Technical documentation and safety

Open, free learning for anyone who wants to protect people and technology. No account is required to read this text or its worked answers.

Chapter 16 — Technical documentation and safety

Lesson map

Lesson 16 published. Map, example, EX061.

flowchart TD
  N0["Learning outcomes and connection"]
  N1["16.1 Diagnose the unsafe draft"]
  N2["16.2 A reviewable runbook card"]
  N3["16.3 Offline state-machine check"]
  N4["Subject synthesis"]
  N0 --> N1 --> N2 --> N3 --> N4
  N4 --> EX["Worked example"]
  EX --> Q["Exercise EX061"]

Logical drawing

flowchart LR
  N0["Learning outcomes and connection"]
  N1["16.1 Diagnose the unsafe draft"]
  N2["16.2 A reviewable runbook card"]
  N3["16.3 Offline state-machine check"]
  N4["Subject synthesis"]
  N0 --> N1 --> N2 --> N3 --> N4 --> Q["EX061"]

[Learning outcomes and connection]
    |
    v
[16.1 Diagnose the unsafe draft]
    |
    v
[16.2 A reviewable runbook card]
    |
    v
[16.3 Offline state-machine check]
    |
    v
[Subject synthesis]
    |
    v
[Worked example] --> [Exercise EX061]

Learning outcomes and connection

The learner will write a runbook that separates observation, proposal, approval, execution, verification, rollback and handoff. Chapter 15 produced an uncertain timeline; that uncertainty must appear in preconditions and stop conditions, not disappear when somebody writes imperative prose. The student can repair an unsafe procedure and peer-review it against a service outcome. The safety structure is an original exercise informed by incident governance in NIST SP 800-61 Rev. 3 and recovery testing in NIST SP 800-184.

16.1 Diagnose the unsafe draft

The fictional K16 draft reads: “Revoke svc-book for all services, restart the worker, delete old logs to reduce noise, announce resolved.” Every clause fails a different test. Revocation has no trigger, target scope, decision authority, duration or expected effect; it may stop legitimate R40/R41 operations. A restart can erase volatile state and replay queued jobs. Deleting logs destroys source material and obscures provenance. “Resolved” has no database, service or negative-control evidence. The draft also conflates a recommendation with permission to act. A safe revision need not always select the narrowest control—urgency may justify a broader one—but it must make the risk/authority tradeoff explicit and measurable.

Start a runbook with a purpose and applicability statement: “Only for a confirmed, continuing unwanted write on a validated route in the named service; otherwise preserve and investigate.” Then list the case version and exact evidence IDs that support the trigger. A high-severity label alone is insufficient. State who can authorize access and who can approve an operational change. The identity owner may know session semantics, the application owner may know routing, the DB owner may know authoritative state and the incident lead may coordinate the decision. One person's technical ability to run a command is not the same as authorization to run it.

Next specify a change contract: target identity/session and route, protected resource, intended duration/expiry, versioned configuration, operator, approver, maintenance window if relevant, and a tested rollback method. Avoid writing a live command in the public classroom example. Make all checks observable: source-linked continuing harm, known in-range telemetry control, no new unauthorized R42 write over a bounded interval, approved R40/R41 processing, patron read correctness and audit continuity. A 403 or policy-match event alone does not show that a database mutation stopped. The “no new write” result needs an authoritative DB check and a stated coverage interval. Recovery needs an isolated restore test before any production claim.

The stop condition must be checked before and during a change. Stop if the session map is unvalidated, the evidence source is unhealthy, the target cannot be scoped, the authorized operator or approver is absent, the rollback object is missing, or the legitimate service acceptance check fails. Stopping is a recorded state, not a silent exception. If a change has already occurred and the business negative check fails, follow the approved rollback path, reconcile queued work and record the residual risk; do not assume rollback of a rule undoes database writes.

16.2 A reviewable runbook card

Field K16 classroom version Required real owner evidence
Trigger A future, source-validated continuing unwanted R42 write; K15 does not establish it DB receipt, mapped route/session, timing and case approval
Evidence pointer K12 raw manifest, K13 flags, K14 packet, K15 timeline v1 Immutable source IDs and access receipts
Proposed option Targeted temporary write restriction on confirmed session/route Identity/application owners validate match and bypass paths
Approvals Pending Incident lead plus affected service/control owners
Before state R40/R41 legitimate write and patron read, R42 authoritative state Owner-backed baseline and source-health controls
After/negative tests No new R42 write; R40/R41 and patron read still correct DB and service receipts in bounded windows
Stop/rollback Halt on missing mapping, unhealthy telemetry or service failure; restore prior control version under owner approval Versioned rollback artifact, operator, rehearsal and reconciliation
Communication “Proposed, pending,” then “executed,” then “verified” only with separate receipts Named recipient, time, unresolved risks and follow-up

This card is deliberately incomplete. No actual operator, expiry or production ticket is supplied; therefore it is not executable. A runbook is also a knowledge-transfer artifact. The next shift needs the current case version, which observations are still open, which systems were actually changed, when the next review is due, and how to reach the decision owner. Do not put secrets in the handoff or copy entire customer records into a general channel.

16.3 Offline state-machine check

The following code tests the words “approved” and “verified” as distinct states. It does not call a service and cannot authorize action. The exercise input deliberately lacks a validated mapping, so the control stops before execution.

required = {"harm_observed", "mapping_validated", "owner_approved", "baseline_saved"}
ticket = {"harm_observed": False, "mapping_validated": False,
          "owner_approved": False, "baseline_saved": True}
missing = sorted(k for k in required if not ticket[k])
print("state:", "STOP" if missing else "READY_FOR_OPERATOR")
print("missing:", missing)
variant = dict(ticket, harm_observed=True, mapping_validated=True,
               owner_approved=True)
print("variant_state:", "STOP" if any(not variant[k] for k in required)
      else "READY_FOR_OPERATOR")
print("variant_executed:", False)

The variant reaches READY_FOR_OPERATOR only in the toy state machine; it has not executed anything or verified an outcome. A peer should challenge the Boolean labels: what constitutes “mapping validated,” who signed it, what expires, and where is the receipt? A checkbox without a cited source can be false assurance. If the production source becomes unavailable between approval and action, the operator must re-evaluate the precondition rather than trusting an old screenshot.

Exercises — subject 16

EX061 — Unsafe-procedure repair. Annotate the four original commands with risk, missing precondition, required owner and a safer, conditional replacement. Do not produce executable production commands. Evidence: redlined runbook. Rubric: 2 = all four with safety and source retention, 1 = incomplete rollback/verification, 0 = keeps log deletion or unconditional revocation.

EX062 — State-machine transcript. Run §16.3 and record four exact output lines. Change only baseline_saved to False in the variant copy and state the new variant_state and why approval alone is not readiness. Evidence: original/variant transcript. Rubric: 2 = exact results and dependency rationale, 1 = correct state only, 0 = mistakes READY for execution.

EX063 — Stop and rollback drill. In a paper simulation, assume a targeted rule was separately approved and applied, but R40 processing fails while a portal health page remains green. Write the stop notification, rollback evidence, queue reconciliation request and residual-risk statement. Evidence: time-stamped transition ledger with simulated status. Rubric: 2 = owner-led rollback plus authoritative business check, 1 = restores rule without reconciling work, 0 = announces resolved.

EX064 — Peer handoff. Produce a one-page shift handoff with case version, input/source IDs, pending approvals, changed-versus-proposed inventory, next safe read-only test, escalation owner, privacy limit and review time. Have another learner identify one ambiguity and revise the version. Evidence: v1/v2 handoff. Rubric: 2 = auditable version change and explicit uncertainty, 1 = summary without decision gate, 0 = states an unexecuted control happened.

Subject synthesis

Technical documentation is part of the control system: it makes unsafe assumptions visible before they become service changes. K16 ends with a proposed runbook and a stop-state, not a production action. Chapter 17 uses the same acceptance conditions to compare alternatives in an isolated laboratory.

Continue studying — chapter 16 of 18

← Chapter 15 · Course chapter index · Chapter 17 →

Continue to the next authored lesson.

Worked answers

EX061 — Model redline. Replace “revoke all svc-book” with a proposal for a versioned, expiring, route/session-scoped control only if a validated continuing harmful action, owner approval and a rollback artifact exist. Replace “restart worker” with read-only worker/queue inspection and a service-owner plan for preserving volatile state before any authorized restart. Replace “delete old logs” with preserve originals, access receipts, retention check and minimized derived views; log deletion is not an evidence-cleanup shortcut. Replace “announce resolved” with a status that separately names security effect, authoritative R42 result, legitimate R40/R41 state, patron correctness and remaining unknowns. Every change is pending a named decision owner. Exact command syntax is neither necessary nor safe for this paper exercise.

EX062 — Model state transcript.

state: STOP
missing: ['harm_observed', 'mapping_validated', 'owner_approved']
variant_state: READY_FOR_OPERATOR
variant_executed: False

If baseline_saved becomes False only in the variant copy, variant_state becomes STOP, because the required prior-state baseline is missing even if harm, mapping and approval booleans are True. The original state is unaffected. READY_FOR_OPERATOR is a toy review state, not an execution receipt or service verification; actual sign-offs must cite owner evidence and not just toggle a Boolean.

EX063 — Model stop/rollback ledger. “12:10 simulated approval for a scoped rule; 12:11 simulated application with control version K16-R1 and prior version K16-R0 preserved; 12:12 R40 worker check fails although static portal health is green: STOP, notify incident lead, identity/app/worker owners and preserve the failed test source. Under the preapproved rollback contract, restore K16-R0; obtain a control-plane receipt and recheck the exact worker path, R40/R41 authoritative state, R42 bounded write state and patron read. Ask the job owner to reconcile queued/retried tasks and the DB owner to check whether any writes occurred during the interval. Rollback of a rule does not undo those writes. Residual risk and incident status remain open until source-linked acceptance results arrive.” Times are classroom markers; no production action occurred.

EX064 — Model handoff. A full-score v1 names K16, current evidence versions K12/K13/K14/K15, case clock, pending incident/service-owner approvals, proposed targeted restriction versus no executed production change, missing DB and session mapping, read-only source-health and outcome requests, expiry/rollback owner still to be assigned, privacy-minimized request, and next review time. A peer may notice that “DB receipt” lacks a bounded route and interval. V2 adds r-601, the requested interval and DB custodian while retaining v1. Changing the note without a version marker fails the auditability criterion.