Chapter 39 — Network and communications security: maintainability | Engineering Network and communications security

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 39 — Network and communications security: maintainability

Lesson map

Lesson 39 published. Map, example, EX115.

flowchart TD
  N0["Learning outcomes"]
  N1["39.1 Documentation set"]
  N2["39.2 Simplicity over cleverness"]
  N3["39.3 Knowledge transfer"]
  N4["39.4 Vendor and lifecycle"]
  N5["Decision records"]
  N6["Synthesis"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6
  N6 --> EX["Worked example"]
  EX --> Q["Exercise EX115"]

Logical drawing

flowchart LR
  N0["Learning outcomes"]
  N1["39.1 Documentation set"]
  N2["39.2 Simplicity over cleverness"]
  N3["39.3 Knowledge transfer"]
  N4["39.4 Vendor and lifecycle"]
  N5["Decision records"]
  N6["Synthesis"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> Q["EX115"]

[Learning outcomes]
    |
    v
[39.1 Documentation set]
    |
    v
[39.2 Simplicity over cleverness]
    |
    v
[39.3 Knowledge transfer]
    |
    v
[39.4 Vendor and lifecycle]
    |
    v
[Decision records]
    |
    v
[Synthesis]
    |
    v
[Worked example] --> [Exercise EX115]

Learning outcomes

You will (1) design for long-term maintenance; (2) document thoroughly; (3) reduce dependency on individuals.

39.1 Documentation set

Kofi leaves the council a documentation set designed for the engineers who will run the network after he leaves. It contains an architecture overview, the zone model, the needed-flows list, the policy templates and per-site files, operational runbooks, the regression test suite and the decision records. Each document names an owner and a review date, so responsibility is clear and stale documents are noticed. Everything is stored in version control alongside the configurations, which means documentation and configuration change together and their history can be compared when something goes wrong.

39.2 Simplicity over cleverness

Throughout the design, Kofi faced choices between clever configurations and plain ones, and he chose plain. Every branch policy comes from one template; object names follow one convention that states zone, role and site; exceptions live in a single listed file rather than scattered across rules. A clever arrangement might save a few rules, but it costs understanding, and an engineer who misunderstands a configuration is likely to break it. The test Kofi applies is whether someone joining the team in three years could explain each rule after reading the documentation for an afternoon.

39.3 Knowledge transfer

Documents alone rarely transfer knowledge. For the last three office migrations, the two council engineers lead the work themselves while Kofi observes and answers questions only when asked. This builds their confidence and, just as importantly, exposes places where the documentation assumed knowledge they did not have. Each gap found, such as a missing step for loading certificates, is corrected immediately in the runbook. By the end, the engineers have carried out complete migrations without help, which is stronger evidence of maintainability than any amount of written material.

39.4 Vendor and lifecycle

Equipment has a life cycle that outlasts any project. Kofi records the firmware update schedule for each device model, the vendor's announced end-of-support dates, the support contract terms and the spare equipment plan. He adds the end-of-support dates to the council's budget calendar, so replacement can be funded a year ahead rather than discovered when security updates stop. Firmware updates follow the change process and are tested in the lab first. Without this record, maintenance would depend on someone remembering vendor announcements, which is not a reliable control.

Decision records

A decision record captures one significant design choice: the context, the options considered, the option chosen, the reasons and the expected consequences. Kofi writes one for each major choice, such as firewalls at every office rather than only at the centre, IKEv2 with certificates rather than shared keys, and a jump host for supplier access. Each record is short, usually under a page. Years later, an engineer wondering why something was built a certain way can read the reasoning instead of guessing, and can tell whether the original conditions still hold before changing it. This prevents well-meant changes that quietly undo earlier protections.

Worked example

An engineer from another council team uses only the documentation to add a new subnet at a branch, completing it correctly in under an hour.

Synthetic case. The test is synthetic.

Errors and limits

Documentation written at the end of a project is usually incomplete; write it alongside the work.

Exercises

EX115 — Document list. List five documents in the set. Rubric: 3 = five;; 2 = four;; 1 = fewer;; 0 = none.
EX116 — Knowledge transfer method. How did Kofi transfer knowledge? Rubric: 3 = engineers led migrations with observation;; 2 = training;; 1 = vague;; 0 = none.
EX117 — Maintainability test. How was documentation tested? Rubric: 3 = outside engineer completed a task using it;; 2 = tried;; 1 = vague;; 0 = none.

Synthesis

Maintainable designs are simple, documented and owned by the people who will run them.

Continue studying — chapter 39 of 50

← Chapter 38 (draft) · Course chapter index · Chapter 40 (draft) →