Course outline
Secure Software Development
Basic: outcomes, models, and decisions
Intermediate: implementation boundaries and verification
Advanced: components, evidence, and response

Secure Software Development / Basic: outcomes, models, and decisions / Lesson 6

Record security decisions for useful review

Explain a design choice through context, alternatives, evidence, and residual risk.

About 4 min readContent reviewed
On this page

Lesson goals

  • Write a decision record that another reviewer can challenge.
  • Separate an accepted tradeoff from a verified control or permanent exemption.

Record the decision while the context is available

A design record explains why the team chose a particular boundary or control. For the workshop service, the choice between streamed exports and stored downloads changes lifetime, authorization, and recovery questions. Capture the problem, assumptions, constraints, alternatives, and selected approach before memory is replaced by folklore. The record should be short enough to maintain but specific enough to explain the tradeoff. Avoid a document that says only industry standard or approved by security. A reviewer needs the reasoning and evidence, not an unexplained appeal to authority.

Compare alternatives against protected outcomes

A useful comparison considers which option reduces contact exposure, supports the user workflow, and can be verified under the available architecture. An apparently simpler option may push authority into an unreviewed client or create long-lived artifacts. The first example is a fictional decision record with an explicit unverified assumption. It does not prescribe streamed exports for every product. Real constraints such as accessibility, interrupted downloads, dataset size, and background processing can justify another choice when its controls and limitations are reviewed. Preserve rejected alternatives only when they explain the final reasoning.

json A fictional security decision record 
{"decision":"LAB-ADR-03","context":"small-organizer-export","options":["stream-per-request","store-for-later"],"selected":"stream-per-request","reason":"avoid-long-lived-contact-artifact-in-this-scenario","assumptions":["bounded-export-size"],"unverified":["actual-handler-scope"],"reviewTrigger":"background-export-added"}

This non-runnable record distinguishes an architectural choice from evidence of correct implementation. The local identifier is not a standard control number. Its review trigger prevents the choice from being treated as timeless policy.

Track claims independently from approval

A reviewer can approve a design direction while requesting implementation evidence before release. Store claim status separately from document approval. The program checks that a decision package retains an unverified storage claim even though the design is approved. It is a bookkeeping model, not a release authority. In a real review, attach the observed case, source revision, and actual environment for each verified claim. Do not let a signature, meeting, or completed form transform a planned test into an executed result. Approval and empirical evidence have different meanings.

python Preserve an unverified boundary after design approval 
record = {"designApproved": True, "claims": {"field-projection":"local-verified", "storage-scope":"not-executed"}}
unverified = [name for name, state in record["claims"].items() if state != "local-verified"]
assert record["designApproved"] is True
assert unverified == ["storage-scope"]
assert bool(unverified) is True
print("approval preserves the unverified claim")
Expected output
approval preserves the unverified claim

The complete program evaluates declared classroom statuses. It does not assess a real control or grant release permission. Local-verified is meaningful only when the underlying observation and limitation are recorded elsewhere in the package.

Give exceptions a bounded lifecycle

An accepted residual risk needs an accountable owner, rationale, scope, and review trigger. If a temporary integration limitation is accepted, identify what is still unknown and which compensating control actually reduces exposure. Do not call a control compensating merely because it exists nearby. An unrelated audit log does not prevent unauthorized contact disclosure. Keep exceptions visible in release evidence and revisit them when assumptions change or the review date arrives. Avoid permanent blanket exemptions that expand silently to new endpoints or consumers without the original risk decision being reconsidered.

Use change triggers to keep reasoning current

A decision becomes stale when its assumptions stop matching the product. New data categories, larger exports, another tenant model, or a background retrieval path should trigger targeted review. Link the updated record to the change and preserve enough history to explain the migration. Do not rewrite an old record to pretend the new design was always intended. A maintained decision log helps future engineers understand why a check exists and when it can safely change. It supports review and accountability while remaining distinct from a certification of the deployed system.

Common errors and fixes

Approved is treated as every claim verified

Why it happens
Design consent is conflated with empirical evidence.
How to fix it
Track claim observations and missing boundaries separately.
Prevent it next time
Review approval state and evidence state as distinct fields.

A temporary exception becomes permanent

Why it happens
No scope or review trigger is recorded.
How to fix it
Assign an owner, bounded applicability, and reconsideration point.
Prevent it next time
Include exceptions in change and release review.

The record says only use best practice

Why it happens
The actual alternatives and constraints are missing.
How to fix it
Explain the protected outcome and why the selected option fits this context.
Prevent it next time
Require reasoning that another reviewer can challenge.

Check your understanding

1. A design approval exists but the actual handler scope is untested. What belongs in the release package?

Show worked solution

Include the approved design record and explicitly pending handler-scope claim, with its owner and planned evidence. If a release exception is considered, record the accountable risk decision and actual compensating controls. Do not mark the handler verified merely because the architecture was approved.

2. The product adds background export downloads. How should LAB-ADR-03 change?

Show worked solution

Trigger review of storage lifetime, result authorization, subject changes, and cleanup assumptions. Compare the new alternatives and record the revised decision with evidence needs. Preserve the old rationale as history rather than retroactively claiming that a streamed-export design already addressed background artifacts.

Key takeaways

  • A decision record explains context and tradeoffs.
  • Approval, verification, and accepted exception are different states.
  • Change triggers keep architectural reasoning useful.

Official references