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:
- Security control story — a new protective capability (rate limiting, input validation, audit logging). Written from the system's or security role's perspective.
- Vulnerability remediation story — fixing a specific finding. Must reference the finding ID and include a regression test criterion.
- 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.
- 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.
1---2name: security-story-writing3description: 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".4license: MIT5---67# Security Story Writing89Convert 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.1011## Story Types1213Pick the right shape for the input:14151. **Security control story** — a new protective capability (rate limiting, input validation, audit logging). Written from the system's or security role's perspective.162. **Vulnerability remediation story** — fixing a specific finding. Must reference the finding ID and include a regression test criterion.173. **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.184. **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.1920## Templates2122### Security control story23```markdown24### [ID] [Control title]25**As** [the system / a security role], **I want** [security control], **so that** [risk is mitigated].26**Threat:** [STRIDE category or threat-model reference]27**Compliance:** [framework + control number, if applicable]2829#### Acceptance Criteria30- Given [precondition], when [attack vector attempted], then [system prevents/detects and logs/alerts]31- Given [precondition], when [normal operation], then [control is active without breaking the user flow]3233#### Security Regression Test34- Automated test proving [the attack] fails, runs in CI from this sprint onward35```3637### Vulnerability remediation story38```markdown39### [ID] Fix: [finding title]40**Finding:** [scanner/report ID, severity, CVSS if available]41**Affected:** [component, endpoint, or file]4243#### Acceptance Criteria44- Given the conditions in the finding, when [the exploit is attempted], then it fails45- The fix introduces no functional regression in [affected flows]46- A regression test reproducing the original exploit is added to CI47```4849### Feature story with security criteria50```markdown51### [ID] [Feature title]52**As a** [user], **I want to** [action], **so that** [business value].53**Security consideration:** [what could go wrong — one line, STRIDE reference if a threat model exists]5455#### Acceptance Criteria56- [Functional criteria as usual]57- **Security:** [the specific security property, testable — e.g. "responses never include other users' data, verified by an authorization test"]58```5960## Quality Bar (apply before delivering)6162- **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.63- **INVEST-compliant**: independently schedulable, estimable, sized for one sprint. Split stories that bundle multiple controls.64- **Traceable**: remediation stories cite the finding; compliance stories cite the control number; threat-derived stories cite the threat model entry.65- **Negative path included**: at least one criterion describes what happens when the attack is attempted, not only the happy path.6667## Examples6869- "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)70- "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)7172## Guidelines7374- Severity drives priority: Critical/High vulnerabilities are P0/P1 and should not wait for "a security sprint" — recommend they enter the current sprint.75- 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).76- 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.
timwukp