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