Skip to main content

Decision Records - Methodology

Purpose​

This page documents key security and architectural decisions made in the Scheol Security Lab.

The objective is to:

  • capture the reasoning behind decisions
  • provide context for design choices
  • support reviewability and auditability

This avoids treating the architecture as a black box and helps explain why things are the way they are.

What is a Decision Record?​

A decision record documents:

  • a specific architectural or security choice
  • the context and constraints
  • the reasoning behind the decision
  • the impact and trade-offs

It is not a technical configuration log, but a governance artefact.

When to Create a Decision Record​

A decision record should be created when:

  • a security-relevant trade-off is made
  • a risk is accepted or temporarily tolerated
  • an architectural constraint impacts security posture
  • a non-standard or transitional setup is used

Typical examples in Scheol Lab include:

  • co-location of services on VPS-01
  • temporary absence of centralised logging
  • phased deployment of identity and access controls

Decision Record Structure​

Each decision record should include:

1. Title​

Clear and concise description of the decision.

2. Context​

  • current situation
  • constraints (technical, time, resources)
  • related risks

3. Decision​

  • what has been decided
  • scope of the decision

4. Rationale​

  • why this option was chosen
  • alternatives considered (optional but recommended)

5. Security Impact​

  • positive effects
  • introduced risks or weaknesses

6. Mitigation / Safeguards​

  • compensating controls
  • temporary protections

7. Status​

  • Active / Deprecated / Replaced

8. Review Trigger​

  • when this decision should be revisited

Example (Simplified)​

Decision: Co-location of Gitea and public websites on VPS-01

  • Context: limited infrastructure, need for rapid deployment
  • Decision: host both services on a single VPS instance
  • Rationale: resource constraints and simplicity
  • Security Impact: increased attack surface and lateral movement risk
  • Mitigation: container isolation, restricted access, monitoring
  • Status: Active (transitional)
  • Review Trigger: migration to dedicated instances

Relationship with Other Sections​

Decision records are linked to:

  • Applied Architecture → where decisions are implemented
  • Risk Register → where risks are identified and evaluated
  • Residual Gaps → where limitations are tracked
  • Traceability Matrix → where decisions may influence controls

They provide the missing context between design and risk.

Usage Principles​

Decision records should be:

  • concise (no unnecessary detail)
  • honest (including limitations and trade-offs)
  • focused on reasoning, not implementation steps

They should evolve over time as:

  • decisions are revisited
  • constraints change
  • architecture matures

Known Limitations​

At the current stage:

  • decision records are not yet systematically created
  • historical decisions are only partially documented
  • linkage with risks and controls is still limited

This will be progressively improved.

Current Maturity​

At the current stage, decision documentation is considered early and mostly implicit.

Established​

  • awareness of the need to document security decisions
  • identification of key architectural trade-offs
  • initial informal documentation of major constraints

In Progress​

  • formalisation of decision records for key components
  • improved linkage between decisions, risks and controls
  • better visibility of security trade-offs

Planned / Next Phase​

  • systematic use of decision records for major changes
  • integration with traceability and audit documentation
  • improved consistency and lifecycle tracking of decisions

This page is expected to evolve into a key governance artefact.