security-story-writing

name	security-story-writing
description	Writes security user stories and security-aware acceptance criteria that fit a Scrum backlog, converting threats, scan findings, and compliance requirements into INVEST-compliant stories with Given/When/Then criteria and regression tests. Use this (not general story writing) whenever the story or criteria concern a security control, vulnerability, or compliance requirement. Triggers on: "write a security story", "security acceptance criteria", "acceptance criteria for rate limiting/auth/validation", "Given/When/Then for this security control", "turn this vulnerability into a backlog item", "convert these scan findings to stories".
license	MIT
metadata	{"author":"Community","version":"1.0.0","category":"secure-sdlc"}

Security Story Writing

Convert security work — threats from a threat model, SAST/DAST findings, pen-test results, compliance controls — into stories a Scrum team can estimate, schedule, and verify like any other backlog item.

Story Types

Pick the right shape for the input:

1. Security control story — a new protective capability (rate limiting, input validation, audit logging). Written from the system's or security role's perspective.
2. Vulnerability remediation story — fixing a specific finding. Must reference the finding ID and include a regression test criterion.
3. Feature story with security criteria — a normal feature story that gains explicit security acceptance criteria. Use when security is a property of the feature, not separate work.
4. Compliance story — implementing a named control from a framework (PCI-DSS requirement, MAS TRM section). Must cite the specific control number so auditors can trace it.

Templates

Security control story

### [ID] [Control title]
**As** [the system / a security role], **I want** [security control], **so that** [risk is mitigated].
**Threat:** [STRIDE category or threat-model reference]
**Compliance:** [framework + control number, if applicable]

#### Acceptance Criteria
- Given [precondition], when [attack vector attempted], then [system prevents/detects and logs/alerts]
- Given [precondition], when [normal operation], then [control is active without breaking the user flow]

#### Security Regression Test
- Automated test proving [the attack] fails, runs in CI from this sprint onward

Vulnerability remediation story

### [ID] Fix: [finding title]
**Finding:** [scanner/report ID, severity, CVSS if available]
**Affected:** [component, endpoint, or file]

#### Acceptance Criteria
- Given the conditions in the finding, when [the exploit is attempted], then it fails
- The fix introduces no functional regression in [affected flows]
- A regression test reproducing the original exploit is added to CI

Feature story with security criteria

### [ID] [Feature title]
**As a** [user], **I want to** [action], **so that** [business value].
**Security consideration:** [what could go wrong — one line, STRIDE reference if a threat model exists]

#### Acceptance Criteria
- [Functional criteria as usual]
- **Security:** [the specific security property, testable — e.g. "responses never include other users' data, verified by an authorization test"]

Quality Bar (apply before delivering)

• Testable: every criterion can be verified by a test or demonstrated in review. "Is secure" fails this bar; "locks the account after 5 consecutive failed logins within 15 minutes" passes.
• INVEST-compliant: independently schedulable, estimable, sized for one sprint. Split stories that bundle multiple controls.
• Traceable: remediation stories cite the finding; compliance stories cite the control number; threat-derived stories cite the threat model entry.
• Negative path included: at least one criterion describes what happens when the attack is attempted, not only the happy path.

Examples

• "As the authentication service, I want to lock accounts after 5 consecutive failed login attempts within 15 minutes, so that brute-force attacks are prevented." (control story; criteria cover the lockout, the unlock path, and the audit log entry)
• "As the transfer API, I want all amount and account inputs validated server-side against strict schemas, so that injection and tampering attempts are rejected." (control story derived from a Tampering threat)

Guidelines

• Severity drives priority: Critical/High vulnerabilities are P0/P1 and should not wait for "a security sprint" — recommend they enter the current sprint.
• When converting a batch of scan findings, group by root cause (e.g. one story for "parameterize all queries in module X", not 14 stories for 14 query sites).
• Don't write security theater: if a requested control doesn't mitigate a real threat for this system, say so and propose what actually would.