Document Security Decisions

You've just spent weeks hardening your application — you've patched vulnerabilities, configured encryption, and locked down access. Then you hit the wall every engineering team knows: the person who needs to understand what you did is not you. They're a new teammate, a security auditor, or another team on-call for a handoff. Without clear documentation, your careful security decisions look like guesswork. This lesson shows you how to document security decisions for handoffs so that your work is understood, trusted, and maintainable — even when you're no longer in the room.

The problem this lesson solves

Security work is invisible until it fails. If you don't document your decisions, the next person inherits a system they don't understand, and they'll likely undo your hard-won protections by accident. Let's be concrete: a junior engineer finds a restrictive firewall rule and "simplifies" it, assuming it's dead weight. Suddenly, your database is exposed. That's a security decision that wasn't documented, and the cost was a breach.

Documenting security decisions isn't busywork — it's a core part of the security lifecycle. It prevents errors, speeds up onboarding, helps audits, and ensures that the why behind your choices survives you. When you hand off a system, you're handing over trust. Documentation is how you make that trust explicit.

Core concept / mental model

Think of security decisions as contracts with the future. A security decision is any choice that affects the confidentiality, integrity, or availability of your system — like choosing to encrypt data at rest, using a specific authentication flow, or setting a token expiry. The documentation is the contract that explains the terms: what you decided, why, and under what conditions.

The why behind the decision matters more than the what

The what alone is fragile. If you write "MFA is enforced," that's a fact, but it doesn't explain why MFA is required for every admin. Without the why, a future developer might see MFA as an obstacle and remove it for "convenience." The why encodes your threat model and risk analysis.

Documentation as memory, not ceremony

A good security decision record (SDR) is a living artifact. It's not a final report you write at the end; it's a running log you maintain as you make decisions. Each entry captures what was decided, why, and what trade-offs were made. You can use a lightweight template to keep it consistent, and you can store it in version control or a wiki — as long as it's accessible to the team.

A simple diagram

Think of a security decision record as a map:

• Decision = the destination (what you chose)
• Context = the terrain (the system, threats, constraints)
• Rationale = the route you took and why (risk analysis, alternatives)
• Outcome = the landmarks (the results, measurements, and follow-ups)

How it works step by step

The process of documenting a security decision is straightforward once you have a template. Here's a repeatable method.

1. Identify the decision. What security choice did you make? It could be a design decision (e.g., encryption algorithm), a configuration choice (e.g., timeout length), or a process decision (e.g., how to rotate secrets).
2. Capture the context. What was the system state? What threats were you addressing? What constraints existed (time, budget, regulatory)?
3. State the decision clearly. Use imperative or declarative language: "We will use AES-256-GCM for all data at rest." Be specific — avoid ambiguity.
4. Explain the rationale. Why this choice over alternatives? This is where you connect the decision to your threat model. Did you choose a more expensive option because it mitigated a specific attack?
5. List alternatives considered. This isn't just a theoretical exercise; it shows future readers that you didn't miss an obvious solution. Include why you didn't pick each alternative.
6. Define the outcome and next steps. What did you implement? What metrics will you use to evaluate success? Are there follow-up tasks (e.g., "Rotate keys every 90 days")
7. Store and share. Put the record in your team's documentation repository, make it searchable, and link to it from code comments or issue trackers.

The key is to document during the decision, not after. Memory is unreliable; write it down when it's fresh.

Hands-on walkthrough

Let's practice. We'll write a security decision record in Markdown and store it in a docs/security/ folder in your project. We'll also add a short Python script to scan the folder for completeness — a simple check that each record has the required sections. This automates part of the process.

Step 1: Create the template

Save this as docs/security/decision-template.md in your project:

# Security Decision Record: [Title]

**Status:** [Draft | Accepted | Deprecated]
**Date:** YYYY-MM-DD
**Deciders:** [Names or team]

## Context

What is the system context? What threats and constraints are relevant?

## Decision

What did we decide? Be specific.

## Rationale

Why this decision? Link to threat model or risk assessment.

## Alternatives Considered

- Alternative A: Why not?
- Alternative B: Why not?

## Consequences

What are the trade-offs? What follow-up actions are needed?

Step 2: Fill in a real decision

Now we'll create a record for a handoff. Below is an example about choosing token expiration times.

# Security Decision Record: Token Expiry for API Access

**Status:** Accepted
**Date:** 2025-06-10
**Deciders:** Security Team, Backend Team

## Context

We expose a public API for our SaaS. Short-lived tokens reduce the impact of leaked credentials but increase user friction due to more frequent login. Industry OWASP guidance recommends access tokens last no longer than 15 minutes, but our mobile app users have high session churn.

## Decision

Access tokens will expire after 15 minutes. Refresh tokens will expire after 7 days, with a mandatory re-authentication after 30 days of inactivity.

## Rationale

Balances security (limits window of misuse) with usability (refresh tokens avoid repeated logins). Aligns with OWASP recommendations.

## Alternatives Considered

- Access tokens expired after 1 hour: Reduced security; a stolen token stays valid longer.
- No refresh tokens: User experience suffers; users must log in every 15 minutes, which would likely reduce engagement.

## Consequences

- Refresh tokens must be stored securely on the client.
- Requires a revocation mechanism for refresh tokens.
- Set up monitoring for expired token usage patterns.

Step 3: Validate your records with Python

Now the automation part. We'll write a small script to check that all records in a folder have the required sections. Save this as docs/security/validate-records.py:

import pathlib
import sys

REQUIRED_SECTIONS = ["## Context", "## Decision", "## Rationale", "## Alternatives Considered", "## Consequences"]


def validate_record(file_path: pathlib.Path) -> list[str]:
    """Return list of missing sections in a record file."""
    text = file_path.read_text(encoding="utf-8")
    missing = [section for section in REQUIRED_SECTIONS if section not in text]
    return missing


def main(directory: str) -> None:
    files = list(pathlib.Path(directory).glob("*.md"))
    if not files:
        print("No markdown files found.")
        sys.exit(1)

    issues_found = False
    for file in files:
        missing = validate_record(file)
        if missing:
            issues_found = True
            print(f"{file.name}: missing {', '.join(missing)}")

    if issues_found:
        print("\nSome records are incomplete. Please fix them.")
        sys.exit(1)
    else:
        print("All records look complete!")


if __name__ == "__main__":
    main("docs/security")

Run it from your project root:

python docs/security/validate-records.py

You'll see something like:

All records look complete!

Or, if a record is missing a section:

decision-example.md: missing ## Alternatives Considered

Some records are incomplete. Please fix them.

This script gives you a quick safety net to enforce documentation standards across your team.

Compare options / when to choose what

Documentation formats and tools vary. You need to pick what fits your team's culture and workflow. Here's a comparison of common approaches.

Rule of thumb: Start simple — Markdown in your repo. It's free, versioned, and enforceable via pull request review. Add automation later if needed.

Troubleshooting & edge cases

Here are common problems you'll encounter and how to solve them.

"But we don't have time to document"

If you skip documentation, you'll spend more time explaining your decisions later. A 10-minute write-up now saves hours of meetings later. Keep records short — a paragraph each for context, decision, and rationale.

"Our documentation is outdated"

Make documentation part of the definition of done. When you change a security setting, update the relevant record in the same pull request. Add a check like the script above to catch incomplete records.

"What if the decision is sensitive?"

If a decision reveals too much about your security posture (e.g., specific encryption keys), store the record in a private repo or document with access controls. But don't hide the decision itself — obscure sensitive details, keep the rationale visible.

"We have dozens of old decisions"

Don't panic. Prioritize the most recent, most impactful decisions. Start documenting from today forward, then gradually backfill the ones that are still relevant.

"Our team uses a wiki, not git"

That's fine. The content matters more than the tool. But version control has advantages: you can see who changed what and when. If you're on a wiki, make sure there's a dedicated space and naming convention.

What you learned & what's next

You now understand why documenting security decisions is crucial for handoffs. You've seen a mental model of decisions as contracts, learned a step-by-step method, and practiced creating a markdown record plus a validation script. You can apply this to any decision: encryption, auth, access control, or incident response.

Next up: The next lesson in the Security foundations track focuses on translating security decisions into effective incident response plans. With your decisions documented, you'll be ready to build playbooks and ensure your team can respond consistently when something goes wrong.