◇ OpenCyber Academy
Engineering · Chapter 39 · English

Chapter 39 — Digital forensics and malware analysis: maintainability

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 — Digital forensics and malware analysis: maintainability

Lesson map

Lesson 39 published. Map, example, EX115.

flowchart TD
  N0["Learning outcomes"]
  N1["39.1 Why maintainability matters"]
  N2["39.2 Code structure"]
  N3["39.3 Documentation set"]
  N4["39.4 Handover"]
  N5["39.5 Technical debt"]
  N6["39.6 Dependency stability"]
  N7["39.7 Readability"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7
  N7 --> EX["Worked example"]
  EX --> Q["Exercise EX115"]

Logical drawing

flowchart LR
  N0["Learning outcomes"]
  N1["39.1 Why maintainability matters"]
  N2["39.2 Code structure"]
  N3["39.3 Documentation set"]
  N4["39.4 Handover"]
  N5["39.5 Technical debt"]
  N6["39.6 Dependency stability"]
  N7["39.7 Readability"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> Q["EX115"]

[Learning outcomes]
    |
    v
[39.1 Why maintainability matters]
    |
    v
[39.2 Code structure]
    |
    v
[39.3 Documentation set]
    |
    v
[39.4 Handover]
    |
    v
[39.5 Technical debt]
    |
    v
[39.6 Dependency stability]
    |
    v
[39.7 Readability]
    |
    v
[Worked example] --> [Exercise EX115]

Learning outcomes

You will (1) design EvidenceDesk for long-term maintenance; (2) document code and decisions; (3) plan handover to Northfield's IT staff; (4) manage technical debt.

39.1 Why maintainability matters

Evidence records must remain usable for years, long after Priya graduates. A system only its author understands is a liability for the lab and, eventually, for the courts that rely on its records.

Appeals and reviews can come many years after the original case. If nobody can explain how a record was produced or check the chain, the evidence's reliability can be challenged even when nothing went wrong. Priya therefore treats maintainability as a requirement with its own tests, such as whether someone new can make a release, rather than as an aspiration added at the end.

39.2 Code structure

Small modules with single purposes: records, chain, verify, ingest, export. Each module has a short description at the top explaining what it does and what it must never do (for example, "verify never writes to evidence paths").

Splitting by purpose means a change to the PDF layout lives in the export module and cannot accidentally alter how chain links are computed. The 'must never do' lines turn assumptions into checks: a test scans the verify module for file-writing calls and fails if any appear. A new developer can read the top of each module and understand the system's shape in under an hour.

39.3 Documentation set

Architecture overview, decision records, operating procedures, validation report, and a developer guide explaining how to run tests and make a release.

Each document serves a different reader. The architecture overview helps a developer find their way; decision records explain why things are as they are; procedures guide daily staff; the validation report supports court use; the developer guide makes releases repeatable. Priya keeps them in the same repository as the code, so a change and its documentation can be reviewed together.

39.4 Handover

Northfield's IT officer shadows Priya for two weeks, then makes a small change and release under her review, proving the process works without her.

The small change chosen is adding an optional field for the name of the courier who transported an item, which touches records, export and tests without risking the chain. The IT officer writes the code, runs the suite, updates the schema document and produces a release following the guide. Every point where they had to ask Priya a question becomes an edit to the documentation, so the next person does not need to ask.

39.5 Technical debt

Shortcuts taken during the project — a hard-coded path, a missing test — are listed in a debt register with risk and planned fix, not hidden.

Each entry records what was skipped, why, what could go wrong, and when it should be fixed. The hard-coded path, for instance, would break if the lab moved storage, so it is scheduled before any planned move. Keeping the register visible lets the lab weigh debt against new features honestly, and an auditor can see that known weaknesses were managed rather than ignored.

39.6 Dependency stability

Using only the standard library limits upgrade work to Python itself, which Priya pins and tests before each upgrade.

Third-party packages can change behaviour, be abandoned, or be compromised, and each one is another thing to review and keep updated. Python's standard library already provides hashing, JSON handling and file access. Before moving to a new Python version, Priya runs the full test suite and the published vectors on the candidate version and records the result alongside the change. The pinned version is recorded in every release note.

39.7 Readability

Clear names and simple logic beat clever code; a reviewer should understand any function in a few minutes.

Priya rewrites one function that computed chain links in a single dense line into four named steps: serialise, concatenate, hash, compare. It runs no slower and a reviewer now spots its purpose at once. Names follow the domain, such as custody_event and acquisition_digest, so code reads like the procedures staff already know. Comments explain why, not what. Reviewers reject code they cannot follow quickly.

39.8 Deprecation

Features no longer used are removed through a recorded change, with records they produced kept readable.

An early version supported a barcode format the lab no longer uses. Removing the reader simplifies intake, but older records still contain those barcodes, so the export module must keep displaying them. The change record states what was removed, why and from which release, and a test confirms that old records still export correctly after removal. The removed code stays in version history, so anyone can still see how those old barcodes were once read.

Knowledge base

Common questions from examiners — why a copy was blocked, how to file an exception — are collected in a short internal FAQ that the IT officer maintains after handover.

Worked example

The IT officer's first change after handover adds a new imager version parser. He follows the developer guide, adds a sample log test, runs vectors and the integration suite, and releases 1.4.0. One step in the guide was unclear; he edits it as part of the same change.

Synthetic case. The handover is invented.

Errors and limits

Documentation decays; tie updates to every release checklist.

Exercises

Synthesis

Maintainable forensic software outlives its author through structure, documentation and proven handover.

Continue studying — chapter 39 of 50

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