1# security-requirement-extraction — templates and worked examples
2 
3## Templates
4 
5### Template 1: Security Requirement Model
6 
7```python
8from dataclasses import dataclass, field
9from enum import Enum
10from typing import List, Dict, Optional, Set
11from datetime import datetime
12 
13class RequirementType(Enum):
14    FUNCTIONAL = "functional"
15    NON_FUNCTIONAL = "non_functional"
16    CONSTRAINT = "constraint"
17 
18 
19class Priority(Enum):
20    CRITICAL = 1
21    HIGH = 2
22    MEDIUM = 3
23    LOW = 4
24 
25 
26class SecurityDomain(Enum):
27    AUTHENTICATION = "authentication"
28    AUTHORIZATION = "authorization"
29    DATA_PROTECTION = "data_protection"
30    AUDIT_LOGGING = "audit_logging"
31    INPUT_VALIDATION = "input_validation"
32    ERROR_HANDLING = "error_handling"
33    SESSION_MANAGEMENT = "session_management"
34    CRYPTOGRAPHY = "cryptography"
35    NETWORK_SECURITY = "network_security"
36    AVAILABILITY = "availability"
37 
38 
39class ComplianceFramework(Enum):
40    PCI_DSS = "pci_dss"
41    HIPAA = "hipaa"
42    GDPR = "gdpr"
43    SOC2 = "soc2"
44    NIST_CSF = "nist_csf"
45    ISO_27001 = "iso_27001"
46    OWASP = "owasp"
47 
48 
49@dataclass
50class SecurityRequirement:
51    id: str
52    title: str
53    description: str
54    req_type: RequirementType
55    domain: SecurityDomain
56    priority: Priority
57    rationale: str = ""
58    acceptance_criteria: List[str] = field(default_factory=list)
59    test_cases: List[str] = field(default_factory=list)
60    threat_refs: List[str] = field(default_factory=list)
61    compliance_refs: List[str] = field(default_factory=list)
62    dependencies: List[str] = field(default_factory=list)
63    status: str = "draft"
64    owner: str = ""
65    created_date: datetime = field(default_factory=datetime.now)
66 
67    def to_user_story(self) -> str:
68        """Convert to user story format."""
69        return f"""
70**{self.id}: {self.title}**
71 
72As a security-conscious system,
73I need to {self.description.lower()},
74So that {self.rationale.lower()}.
75 
76**Acceptance Criteria:**
77{chr(10).join(f'- [ ] {ac}' for ac in self.acceptance_criteria)}
78 
79**Priority:** {self.priority.name}
80**Domain:** {self.domain.value}
81**Threat References:** {', '.join(self.threat_refs)}
82"""
83 
84    def to_test_spec(self) -> str:
85        """Convert to test specification."""
86        return f"""
87## Test Specification: {self.id}
88 
89### Requirement
90{self.description}
91 
92### Test Cases
93{chr(10).join(f'{i+1}. {tc}' for i, tc in enumerate(self.test_cases))}
94 
95### Acceptance Criteria Verification
96{chr(10).join(f'- {ac}' for ac in self.acceptance_criteria)}
97"""
98 
99 
100@dataclass
101class RequirementSet:
102    name: str
103    version: str
104    requirements: List[SecurityRequirement] = field(default_factory=list)
105 
106    def add(self, req: SecurityRequirement) -> None:
107        self.requirements.append(req)
108 
109    def get_by_domain(self, domain: SecurityDomain) -> List[SecurityRequirement]:
110        return [r for r in self.requirements if r.domain == domain]
111 
112    def get_by_priority(self, priority: Priority) -> List[SecurityRequirement]:
113        return [r for r in self.requirements if r.priority == priority]
114 
115    def get_by_threat(self, threat_id: str) -> List[SecurityRequirement]:
116        return [r for r in self.requirements if threat_id in r.threat_refs]
117 
118    def get_critical_requirements(self) -> List[SecurityRequirement]:
119        return [r for r in self.requirements if r.priority == Priority.CRITICAL]
120 
121    def export_markdown(self) -> str:
122        """Export all requirements as markdown."""
123        lines = [f"# Security Requirements: {self.name}\n"]
124        lines.append(f"Version: {self.version}\n")
125 
126        for domain in SecurityDomain:
127            domain_reqs = self.get_by_domain(domain)
128            if domain_reqs:
129                lines.append(f"\n## {domain.value.replace('_', ' ').title()}\n")
130                for req in domain_reqs:
131                    lines.append(req.to_user_story())
132 
133        return "\n".join(lines)
134 
135    def traceability_matrix(self) -> Dict[str, List[str]]:
136        """Generate threat-to-requirement traceability."""
137        matrix = {}
138        for req in self.requirements:
139            for threat_id in req.threat_refs:
140                if threat_id not in matrix:
141                    matrix[threat_id] = []
142                matrix[threat_id].append(req.id)
143        return matrix
144```
145 
146### Template 2: Threat-to-Requirement Extractor
147 
148```python
149from dataclasses import dataclass
150from typing import List, Dict, Tuple
151 
152@dataclass
153class ThreatInput:
154    id: str
155    category: str  # STRIDE category
156    title: str
157    description: str
158    target: str
159    impact: str
160    likelihood: str
161 
162 
163class RequirementExtractor:
164    """Extract security requirements from threats."""
165 
166    # Mapping of STRIDE categories to security domains and requirement patterns
167    STRIDE_MAPPINGS = {
168        "SPOOFING": {
169            "domains": [SecurityDomain.AUTHENTICATION, SecurityDomain.SESSION_MANAGEMENT],
170            "patterns": [
171                ("Implement strong authentication for {target}",
172                 "Ensure {target} authenticates all users before granting access"),
173                ("Validate identity tokens for {target}",
174                 "All authentication tokens must be cryptographically verified"),
175                ("Implement session management for {target}",
176                 "Sessions must be securely managed with proper expiration"),
177            ]
178        },
179        "TAMPERING": {
180            "domains": [SecurityDomain.INPUT_VALIDATION, SecurityDomain.DATA_PROTECTION],
181            "patterns": [
182                ("Validate all input to {target}",
183                 "All input must be validated against expected formats"),
184                ("Implement integrity checks for {target}",
185                 "Data integrity must be verified using cryptographic signatures"),
186                ("Protect {target} from modification",
187                 "Implement controls to prevent unauthorized data modification"),
188            ]
189        },
190        "REPUDIATION": {
191            "domains": [SecurityDomain.AUDIT_LOGGING],
192            "patterns": [
193                ("Log all security events for {target}",
194                 "Security-relevant events must be logged for audit purposes"),
195                ("Implement non-repudiation for {target}",
196                 "Critical actions must have cryptographic proof of origin"),
197                ("Protect audit logs for {target}",
198                 "Audit logs must be tamper-evident and protected"),
199            ]
200        },
201        "INFORMATION_DISCLOSURE": {
202            "domains": [SecurityDomain.DATA_PROTECTION, SecurityDomain.CRYPTOGRAPHY],
203            "patterns": [
204                ("Encrypt sensitive data in {target}",
205                 "Sensitive data must be encrypted at rest and in transit"),
206                ("Implement access controls for {target}",
207                 "Data access must be restricted based on need-to-know"),
208                ("Prevent information leakage from {target}",
209                 "Error messages and logs must not expose sensitive information"),
210            ]
211        },
212        "DENIAL_OF_SERVICE": {
213            "domains": [SecurityDomain.AVAILABILITY, SecurityDomain.INPUT_VALIDATION],
214            "patterns": [
215                ("Implement rate limiting for {target}",
216                 "Requests must be rate-limited to prevent resource exhaustion"),
217                ("Ensure availability of {target}",
218                 "System must remain available under high load conditions"),
219                ("Implement resource quotas for {target}",
220                 "Resource consumption must be bounded and monitored"),
221            ]
222        },
223        "ELEVATION_OF_PRIVILEGE": {
224            "domains": [SecurityDomain.AUTHORIZATION],
225            "patterns": [
226                ("Enforce authorization for {target}",
227                 "All actions must be authorized based on user permissions"),
228                ("Implement least privilege for {target}",
229                 "Users must only have minimum necessary permissions"),
230                ("Validate permissions for {target}",
231                 "Permission checks must be performed server-side"),
232            ]
233        },
234    }
235 
236    def extract_requirements(
237        self,
238        threats: List[ThreatInput],
239        project_name: str
240    ) -> RequirementSet:
241        """Extract security requirements from threats."""
242        req_set = RequirementSet(
243            name=f"{project_name} Security Requirements",
244            version="1.0"
245        )
246 
247        req_counter = 1
248        for threat in threats:
249            reqs = self._threat_to_requirements(threat, req_counter)
250            for req in reqs:
251                req_set.add(req)
252            req_counter += len(reqs)
253 
254        return req_set
255 
256    def _threat_to_requirements(
257        self,
258        threat: ThreatInput,
259        start_id: int
260    ) -> List[SecurityRequirement]:
261        """Convert a single threat to requirements."""
262        requirements = []
263        mapping = self.STRIDE_MAPPINGS.get(threat.category, {})
264        domains = mapping.get("domains", [])
265        patterns = mapping.get("patterns", [])
266 
267        priority = self._calculate_priority(threat.impact, threat.likelihood)
268 
269        for i, (title_pattern, desc_pattern) in enumerate(patterns):
270            req = SecurityRequirement(
271                id=f"SR-{start_id + i:03d}",
272                title=title_pattern.format(target=threat.target),
273                description=desc_pattern.format(target=threat.target),
274                req_type=RequirementType.FUNCTIONAL,
275                domain=domains[i % len(domains)] if domains else SecurityDomain.DATA_PROTECTION,
276                priority=priority,
277                rationale=f"Mitigates threat: {threat.title}",
278                threat_refs=[threat.id],
279                acceptance_criteria=self._generate_acceptance_criteria(
280                    threat.category, threat.target
281                ),
282                test_cases=self._generate_test_cases(
283                    threat.category, threat.target
284                )
285            )
286            requirements.append(req)
287 
288        return requirements
289 
290    def _calculate_priority(self, impact: str, likelihood: str) -> Priority:
291        """Calculate requirement priority from threat attributes."""
292        score_map = {"LOW": 1, "MEDIUM": 2, "HIGH": 3, "CRITICAL": 4}
293        impact_score = score_map.get(impact.upper(), 2)
294        likelihood_score = score_map.get(likelihood.upper(), 2)
295 
296        combined = impact_score * likelihood_score
297 
298        if combined >= 12:
299            return Priority.CRITICAL
300        elif combined >= 6:
301            return Priority.HIGH
302        elif combined >= 3:
303            return Priority.MEDIUM
304        return Priority.LOW
305 
306    def _generate_acceptance_criteria(
307        self,
308        category: str,
309        target: str
310    ) -> List[str]:
311        """Generate acceptance criteria for requirement."""
312        criteria_templates = {
313            "SPOOFING": [
314                f"Users must authenticate before accessing {target}",
315                "Authentication failures are logged and monitored",
316                "Multi-factor authentication is available for sensitive operations",
317            ],
318            "TAMPERING": [
319                f"All input to {target} is validated",
320                "Data integrity is verified before processing",
321                "Modification attempts trigger alerts",
322            ],
323            "REPUDIATION": [
324                f"All actions on {target} are logged with user identity",
325                "Logs cannot be modified by regular users",
326                "Log retention meets compliance requirements",
327            ],
328            "INFORMATION_DISCLOSURE": [
329                f"Sensitive data in {target} is encrypted",
330                "Access to sensitive data is logged",
331                "Error messages do not reveal sensitive information",
332            ],
333            "DENIAL_OF_SERVICE": [
334                f"Rate limiting is enforced on {target}",
335                "System degrades gracefully under load",
336                "Resource exhaustion triggers alerts",
337            ],
338            "ELEVATION_OF_PRIVILEGE": [
339                f"Authorization is checked for all {target} operations",
340                "Users cannot access resources beyond their permissions",
341                "Privilege changes are logged and monitored",
342            ],
343        }
344        return criteria_templates.get(category, [])
345 
346    def _generate_test_cases(
347        self,
348        category: str,
349        target: str
350    ) -> List[str]:
351        """Generate test cases for requirement."""
352        test_templates = {
353            "SPOOFING": [
354                f"Test: Unauthenticated access to {target} is denied",
355                "Test: Invalid credentials are rejected",
356                "Test: Session tokens cannot be forged",
357            ],
358            "TAMPERING": [
359                f"Test: Invalid input to {target} is rejected",
360                "Test: Tampered data is detected and rejected",
361                "Test: SQL injection attempts are blocked",
362            ],
363            "REPUDIATION": [
364                "Test: Security events are logged",
365                "Test: Logs include sufficient detail for forensics",
366                "Test: Log integrity is protected",
367            ],
368            "INFORMATION_DISCLOSURE": [
369                f"Test: {target} data is encrypted in transit",
370                f"Test: {target} data is encrypted at rest",
371                "Test: Error messages are sanitized",
372            ],
373            "DENIAL_OF_SERVICE": [
374                f"Test: Rate limiting on {target} works correctly",
375                "Test: System handles burst traffic gracefully",
376                "Test: Resource limits are enforced",
377            ],
378            "ELEVATION_OF_PRIVILEGE": [
379                f"Test: Unauthorized access to {target} is denied",
380                "Test: Privilege escalation attempts are blocked",
381                "Test: IDOR vulnerabilities are not present",
382            ],
383        }
384        return test_templates.get(category, [])
385```
386 
387### Template 3: Compliance Mapping
388 
389```python
390from typing import Dict, List, Set
391 
392class ComplianceMapper:
393    """Map security requirements to compliance frameworks."""
394 
395    FRAMEWORK_CONTROLS = {
396        ComplianceFramework.PCI_DSS: {
397            SecurityDomain.AUTHENTICATION: ["8.1", "8.2", "8.3"],
398            SecurityDomain.AUTHORIZATION: ["7.1", "7.2"],
399            SecurityDomain.DATA_PROTECTION: ["3.4", "3.5", "4.1"],
400            SecurityDomain.AUDIT_LOGGING: ["10.1", "10.2", "10.3"],
401            SecurityDomain.NETWORK_SECURITY: ["1.1", "1.2", "1.3"],
402            SecurityDomain.CRYPTOGRAPHY: ["3.5", "3.6", "4.1"],
403        },
404        ComplianceFramework.HIPAA: {
405            SecurityDomain.AUTHENTICATION: ["164.312(d)"],
406            SecurityDomain.AUTHORIZATION: ["164.312(a)(1)"],
407            SecurityDomain.DATA_PROTECTION: ["164.312(a)(2)(iv)", "164.312(e)(2)(ii)"],
408            SecurityDomain.AUDIT_LOGGING: ["164.312(b)"],
409        },
410        ComplianceFramework.GDPR: {
411            SecurityDomain.DATA_PROTECTION: ["Art. 32", "Art. 25"],
412            SecurityDomain.AUDIT_LOGGING: ["Art. 30"],
413            SecurityDomain.AUTHORIZATION: ["Art. 25"],
414        },
415        ComplianceFramework.OWASP: {
416            SecurityDomain.AUTHENTICATION: ["V2.1", "V2.2", "V2.3"],
417            SecurityDomain.SESSION_MANAGEMENT: ["V3.1", "V3.2", "V3.3"],
418            SecurityDomain.INPUT_VALIDATION: ["V5.1", "V5.2", "V5.3"],
419            SecurityDomain.CRYPTOGRAPHY: ["V6.1", "V6.2"],
420            SecurityDomain.ERROR_HANDLING: ["V7.1", "V7.2"],
421            SecurityDomain.DATA_PROTECTION: ["V8.1", "V8.2", "V8.3"],
422            SecurityDomain.AUDIT_LOGGING: ["V7.1", "V7.2"],
423        },
424    }
425 
426    def map_requirement_to_compliance(
427        self,
428        requirement: SecurityRequirement,
429        frameworks: List[ComplianceFramework]
430    ) -> Dict[str, List[str]]:
431        """Map a requirement to compliance controls."""
432        mapping = {}
433        for framework in frameworks:
434            controls = self.FRAMEWORK_CONTROLS.get(framework, {})
435            domain_controls = controls.get(requirement.domain, [])
436            if domain_controls:
437                mapping[framework.value] = domain_controls
438        return mapping
439 
440    def get_requirements_for_control(
441        self,
442        requirement_set: RequirementSet,
443        framework: ComplianceFramework,
444        control_id: str
445    ) -> List[SecurityRequirement]:
446        """Find requirements that satisfy a compliance control."""
447        matching = []
448        framework_controls = self.FRAMEWORK_CONTROLS.get(framework, {})
449 
450        for domain, controls in framework_controls.items():
451            if control_id in controls:
452                matching.extend(requirement_set.get_by_domain(domain))
453 
454        return matching
455 
456    def generate_compliance_matrix(
457        self,
458        requirement_set: RequirementSet,
459        frameworks: List[ComplianceFramework]
460    ) -> Dict[str, Dict[str, List[str]]]:
461        """Generate compliance traceability matrix."""
462        matrix = {}
463 
464        for framework in frameworks:
465            matrix[framework.value] = {}
466            framework_controls = self.FRAMEWORK_CONTROLS.get(framework, {})
467 
468            for domain, controls in framework_controls.items():
469                for control in controls:
470                    reqs = self.get_requirements_for_control(
471                        requirement_set, framework, control
472                    )
473                    if reqs:
474                        matrix[framework.value][control] = [r.id for r in reqs]
475 
476        return matrix
477 
478    def gap_analysis(
479        self,
480        requirement_set: RequirementSet,
481        framework: ComplianceFramework
482    ) -> Dict[str, List[str]]:
483        """Identify compliance gaps."""
484        gaps = {"missing_controls": [], "weak_coverage": []}
485        framework_controls = self.FRAMEWORK_CONTROLS.get(framework, {})
486 
487        for domain, controls in framework_controls.items():
488            domain_reqs = requirement_set.get_by_domain(domain)
489            for control in controls:
490                matching = self.get_requirements_for_control(
491                    requirement_set, framework, control
492                )
493                if not matching:
494                    gaps["missing_controls"].append(f"{framework.value}:{control}")
495                elif len(matching) < 2:
496                    gaps["weak_coverage"].append(f"{framework.value}:{control}")
497 
498        return gaps
499```
500 
501### Template 4: Security User Story Generator
502 
503```python
504class SecurityUserStoryGenerator:
505    """Generate security-focused user stories."""
506 
507    STORY_TEMPLATES = {
508        SecurityDomain.AUTHENTICATION: {
509            "as_a": "security-conscious user",
510            "so_that": "my identity is protected from impersonation",
511        },
512        SecurityDomain.AUTHORIZATION: {
513            "as_a": "system administrator",
514            "so_that": "users can only access resources appropriate to their role",
515        },
516        SecurityDomain.DATA_PROTECTION: {
517            "as_a": "data owner",
518            "so_that": "my sensitive information remains confidential",
519        },
520        SecurityDomain.AUDIT_LOGGING: {
521            "as_a": "security analyst",
522            "so_that": "I can investigate security incidents",
523        },
524        SecurityDomain.INPUT_VALIDATION: {
525            "as_a": "application developer",
526            "so_that": "the system is protected from malicious input",
527        },
528    }
529 
530    def generate_story(self, requirement: SecurityRequirement) -> str:
531        """Generate a user story from requirement."""
532        template = self.STORY_TEMPLATES.get(
533            requirement.domain,
534            {"as_a": "user", "so_that": "the system is secure"}
535        )
536 
537        story = f"""
538## {requirement.id}: {requirement.title}
539 
540**User Story:**
541As a {template['as_a']},
542I want the system to {requirement.description.lower()},
543So that {template['so_that']}.
544 
545**Priority:** {requirement.priority.name}
546**Type:** {requirement.req_type.value}
547**Domain:** {requirement.domain.value}
548 
549**Acceptance Criteria:**
550{self._format_acceptance_criteria(requirement.acceptance_criteria)}
551 
552**Definition of Done:**
553- [ ] Implementation complete
554- [ ] Security tests pass
555- [ ] Code review complete
556- [ ] Security review approved
557- [ ] Documentation updated
558 
559**Security Test Cases:**
560{self._format_test_cases(requirement.test_cases)}
561 
562**Traceability:**
563- Threats: {', '.join(requirement.threat_refs) or 'N/A'}
564- Compliance: {', '.join(requirement.compliance_refs) or 'N/A'}
565"""
566        return story
567 
568    def _format_acceptance_criteria(self, criteria: List[str]) -> str:
569        return "\n".join(f"- [ ] {c}" for c in criteria) if criteria else "- [ ] TBD"
570 
571    def _format_test_cases(self, tests: List[str]) -> str:
572        return "\n".join(f"- {t}" for t in tests) if tests else "- TBD"
573 
574    def generate_epic(
575        self,
576        requirement_set: RequirementSet,
577        domain: SecurityDomain
578    ) -> str:
579        """Generate an epic for a security domain."""
580        reqs = requirement_set.get_by_domain(domain)
581 
582        epic = f"""
583# Security Epic: {domain.value.replace('_', ' ').title()}
584 
585## Overview
586This epic covers all security requirements related to {domain.value.replace('_', ' ')}.
587 
588## Business Value
589- Protect against {domain.value.replace('_', ' ')} related threats
590- Meet compliance requirements
591- Reduce security risk
592 
593## Stories in this Epic
594{chr(10).join(f'- [{r.id}] {r.title}' for r in reqs)}
595 
596## Acceptance Criteria
597- All stories complete
598- Security tests passing
599- Security review approved
600- Compliance requirements met
601 
602## Risk if Not Implemented
603- Vulnerability to {domain.value.replace('_', ' ')} attacks
604- Compliance violations
605- Potential data breach
606 
607## Dependencies
608{chr(10).join(f'- {d}' for r in reqs for d in r.dependencies) or '- None identified'}
609"""
610        return epic
611```
612