diff --git a/docs/tutorials/compliance/threatscore.md b/docs/tutorials/compliance/threatscore.md new file mode 100644 index 0000000000..b6a5c3f970 --- /dev/null +++ b/docs/tutorials/compliance/threatscore.md @@ -0,0 +1,483 @@ +# Prowler ThreatScore Documentation + +## Introduction + +The **Prowler ThreatScore** is a comprehensive compliance scoring system that provides a unified metric for assessing your organization's security posture across compliance frameworks. It aggregates findings from individual security checks into a single, normalized score ranging from 0 to 100. + +### Purpose +- **Unified View**: Get a single metric representing overall compliance health +- **Risk Prioritization**: Understand which areas pose the highest security risks +- **Progress Tracking**: Monitor improvements in compliance posture over time +- **Executive Reporting**: Provide clear, quantifiable security metrics to stakeholders + +## How ThreatScore Works + +The ThreatScore calculation considers four critical factors for each compliance requirement: + +### 1. Pass Rate (`rate_i`) +The percentage of security checks that passed for a specific requirement: +``` +Pass Rate = (Number of PASS findings) / (Total findings) +``` + +### 2. Total Findings (`total_i`) +The total number of checks performed (both PASS and FAIL) for a requirement. This represents the amount of evidence available - more findings provide greater confidence in the assessment. + +### 3. Weight (`weight_i`) +A numerical value (1-1000) representing the business importance or criticality of the requirement within your organization's context. + +### 4. Risk Level (`risk_i`) +A severity rating (1-5) indicating the potential impact of non-compliance with this requirement. + +## Score Interpretation Guidelines + +| ThreatScore | Interpretation | Recommended Actions | +|------------------|----------------|-------------------| +| 90-100% | Excellent | Maintain current controls, focus on continuous improvement | +| 80-89% | Good | Address remaining gaps, prepare for compliance audits | +| 70-79% | Acceptable | Prioritize high-risk failures, develop improvement plan | +| 60-69% | Needs Improvement | Immediate attention required, may not pass compliance audit | +| Below 60% | Critical | Emergency response needed, potential regulatory issues | + +## Mathematical Formula + +The ThreatScore uses a weighted average formula that accounts for all four factors: + +``` +ThreatScore = (Σ(rate_i × total_i × weight_i × risk_i) / Σ(total_i × weight_i × risk_i)) × 100 +``` + +### Formula Properties +- **Normalization**: Always produces a score between 0 and 100 +- **Evidence-weighted**: Requirements with more findings have proportionally greater influence +- **Risk-sensitive**: Higher risk requirements impact the score more significantly +- **Business-aligned**: Weight values allow customization based on organizational priorities + +## Parameters Explained + +### Weight Values (1-1000) + +The weight parameter allows customization of ThreatScore calculation based on organizational priorities and regulatory requirements. + +#### Weight Assignment Guidelines + +| Weight Range | Priority Level | Use Cases | +|--------------|----------------|-----------| +| 1-100 | Low | Optional or nice-to-have controls | +| 101-300 | Medium | Standard security practices | +| 301-600 | High | Important security controls | +| 601-850 | Critical | Regulatory compliance requirements | +| 851-1000 | Maximum | Mission-critical security controls | + +#### Weight Selection Strategy +1. **Regulatory Mapping**: Assign higher weights to controls required by industry regulations +2. **Business Impact**: Consider the potential business impact of control failures +3. **Risk Tolerance**: Align weights with organizational risk appetite +4. **Stakeholder Input**: Involve compliance and business teams in weight decisions + +### Risk Levels (1-5) + +Risk levels represent the potential security impact of non-compliance with a requirement. + +| Risk Level | Severity | Impact Description | +|------------|----------|-------------------| +| 1 | Very Low | Minimal security impact, informational | +| 2 | Low | Limited exposure, low probability of exploitation | +| 3 | Medium | Moderate security risk, potential for limited damage | +| 4 | High | Significant security risk, high probability of impact | +| 5 | Critical | Severe security risk, immediate threat to organization | + +#### Risk Level Assessment Criteria +- **Confidentiality Impact**: Data exposure potential +- **Integrity Impact**: Risk of unauthorized data modification +- **Availability Impact**: Service disruption potential +- **Compliance Impact**: Regulatory violation consequences +- **Exploitability**: Ease of exploitation by threat actors + +## Security Pillars and Subpillars + +Prowler organizes security requirements into a hierarchical structure of pillars and subpillars, providing a comprehensive framework for security assessment and compliance evaluation. + +### Security Pillars Overview + +The ThreatScore calculation considers requirements organized within the following security pillars: + +#### 1. IAM (Identity and Access Management) + +**Purpose**: Controls who can access what resources and under what conditions + +**Subpillars**: + +- **1.1 Authentication**: Verifying user and system identities +- **1.2 Authorization**: Controlling access to resources based on authenticated identity +- **1.3 Privilege Escalation**: Preventing unauthorized elevation of permissions + +#### 2. Attack Surface + +**Purpose**: Minimizing exposure points that could be exploited by threat actors across network, storage, and application layers + +**Subpillars**: + +- **2.1 Network**: Network infrastructure security, segmentation, firewall rules, VPC configurations, and traffic controls +- **2.2 Storage**: Data storage systems security, database security, file system permissions, backup security, and storage encryption +- **2.3 Application**: Application-level controls and configurations, application security settings, code security, runtime protections + +#### 3. Logging and Monitoring + +**Purpose**: Ensuring comprehensive visibility and audit capabilities + +**Subpillars**: + +- **3.1 Logging**: Capturing security-relevant events and activities +- **3.2 Retention**: Maintaining logs for appropriate time periods +- **3.3 Monitoring**: Active surveillance and alerting on security events + +#### 4. Encryption + +**Purpose**: Protecting data confidentiality through cryptographic controls + +**Subpillars**: + +- **4.1 In-Transit**: Encrypting data during transmission +- **4.2 At-Rest**: Encrypting stored data + +### Pillar Hierarchy and ThreatScore Impact + +#### Hierarchy Structure +``` +Security Framework +├── 1. IAM +│ ├── 1.1 Authentication +│ ├── 1.2 Authorization +│ └── 1.3 Privilege Escalation +├── 2. Attack Surface +│ ├── 2.1 Network +│ ├── 2.2 Storage +│ └── 2.3 Application +├── 3. Logging and Monitoring +│ ├── 3.1 Logging +│ ├── 3.2 Retention +│ └── 3.3 Monitoring +└── 4. Encryption + ├── 4.1 In-Transit + └── 4.2 At-Rest + +Example Requirement Structure: +├── Pillar: 1. IAM +│ ├── Subpillar: 1.1 Authentication +│ │ ├── Requirement: MFA Implementation +│ │ │ ├── Check 1: Admin accounts use MFA +│ │ │ ├── Check 2: Regular users use MFA +│ │ │ └── Check 3: Service accounts use MFA +│ │ └── [Additional Requirements] +│ └── [Additional Subpillars: Authorization, Privilege Escalation] +``` + +#### Weight and Risk Assignment by Pillar + +Different pillars typically receive different weight and risk assignments based on their security impact: + +| Pillar | Typical Weight Range | Typical Risk Range | Rationale | +|--------|---------------------|-------------------|-----------| +| 1. IAM | 800-1000 | 4-5 | Critical for access control, high impact if compromised | +| 2. Attack Surface | 500-900 | 3-5 | Highly dependent on exposure and criticality across network, storage, and application layers | +| 3. Logging and Monitoring | 600-800 | 3-4 | Important for detection and compliance, moderate direct impact | +| 4. Encryption | 700-950 | 4-5 | Essential for data protection, regulatory compliance | + +**Subpillar Weight Considerations**: + +- **2.1 Network (Attack Surface)**: 500-800, Risk 3-4 - Network perimeter defense +- **2.2 Storage (Attack Surface)**: 600-900, Risk 4-5 - Data exposure impact +- **2.3 Application (Attack Surface)**: 400-700, Risk 2-4 - Varies by application criticality + +### Pillar-Specific Scoring Considerations + +#### High-Impact Pillars (1. IAM, 4. Encryption) + +- **Characteristics**: Direct impact on data protection and access control +- **ThreatScore Impact**: Failures in these pillars significantly lower overall score +- **Weight Strategy**: Assign maximum weights (800-1000) to critical requirements +- **Risk Strategy**: Most requirements rated 4-5 due to severe consequences + +#### Variable-Impact Pillar (2. Attack Surface) + +- **Characteristics**: Impact varies significantly across subpillars (Network, Storage, Application) +- **ThreatScore Impact**: Depends on specific subpillar and business context +- **Weight Strategy**: + - 2.1 Network subpillar: 500-800 (perimeter defense importance) + - 2.2 Storage subpillar: 600-900 (data exposure risk) + - 2.3 Application subpillar: 400-700 (application-specific criticality) +- **Risk Strategy**: Wide range (2-5) based on exposure, data sensitivity, and business criticality + +#### Monitoring Pillar (3. Logging and Monitoring) + +- **Characteristics**: Essential for compliance and incident response +- **ThreatScore Impact**: Moderate influence, critical for audit requirements +- **Weight Strategy**: Consistent weights (600-800) across logging, retention, and monitoring subpillars +- **Risk Strategy**: Moderate risk levels (3-4) with emphasis on compliance impact + +### Cross-Pillar Dependencies + +#### Authentication ↔ Authorization (IAM) + +- Strong authentication enables effective authorization controls +- Weight both subpillars highly as they're interdependent + +#### Logging ↔ Monitoring (Logging and Monitoring) + +- Logging provides the data that monitoring systems analyze +- Balance weights to ensure both data collection and analysis are prioritized + +#### In-Transit ↔ At-Rest (Encryption) + +- Comprehensive data protection requires both encryption types +- Consider data flow patterns when assigning relative weights + +### Pillar Coverage in ThreatScore + +#### Complete Coverage Benefits + +- **Comprehensive Assessment**: All security domains represented in score +- **Balanced View**: Prevents over-emphasis on single security aspect +- **Regulatory Alignment**: Covers requirements across major compliance frameworks + +#### Partial Coverage Considerations + +- **Focused Assessment**: Target specific security domains +- **Resource Optimization**: Concentrate efforts on high-priority areas +- **Gradual Implementation**: Phase in additional pillars over time + +## Scoring Examples + +### Example 1: Basic Two-Requirement Scenario + +Consider a compliance framework with two requirements: + +**Requirement 1: Encryption at Rest** + +- Findings: 200 PASS, 500 FAIL (total = 700) +- Pass Rate: 200/700 = 0.286 (28.6%) +- Weight: 500 (High priority - data protection) +- Risk Level: 4 (High risk - data exposure) + +**Requirement 2: Access Logging** + +- Findings: 300 PASS, 100 FAIL (total = 400) +- Pass Rate: 300/400 = 0.75 (75%) +- Weight: 800 (Critical for audit compliance) +- Risk Level: 3 (Medium risk - audit trail) + +**Calculation:** +``` +Numerator = (0.286 × 700 × 500 × 4) + (0.75 × 400 × 800 × 3) + = (400,400) + (720,000) + = 1,120,400 + +Denominator = (700 × 500 × 4) + (400 × 800 × 3) + = 1,400,000 + 960,000 + = 2,360,000 + +ThreatScore = (1,120,400 / 2,360,000) × 100 = 47.5% +``` + +### Example 2: Enterprise Scenario with Pillar Structure + +This example demonstrates how pillar organization affects ThreatScore calculation: + +| Pillar | Subpillar | Requirement | Pass | Fail | Total | Weight | Risk | Pass Rate | +|--------|-----------|-------------|------|------|-------|--------|------|-----------| +| 1. IAM | 1.2 Authorization | Access Controls | 280 | 120 | 400 | 800 | 4 | 70% | +| 2. Attack Surface | 2.1 Network | Network Segmentation | 150 | 50 | 200 | 750 | 4 | 75% | +| 2. Attack Surface | 2.2 Storage | Backup Security | 200 | 100 | 300 | 600 | 3 | 66.7% | +| 3. Logging and Monitoring | 3.1 Logging | Audit Logging | 350 | 50 | 400 | 700 | 3 | 87.5% | +| 4. Encryption | 4.2 At-Rest | Encryption | 450 | 50 | 500 | 950 | 5 | 90% | + +**Step-by-step Calculation:** + +1. **Calculate weighted contributions for each requirement:** + + ``` + Numerator = Σ(rate_i × total_i × weight_i × risk_i) + ``` + + - **Access Controls (1.2 Authorization)**: 0.70 × 400 × 800 × 4 = 896,000 + - **Network Segmentation (2.1 Network)**: 0.75 × 200 × 750 × 4 = 450,000 + - **Backup Security (2.2 Storage)**: 0.667 × 300 × 600 × 3 = 360,060 + - **Audit Logging (3.1 Logging)**: 0.875 × 400 × 700 × 3 = 735,000 + - **Encryption (4.2 At-Rest)**: 0.90 × 500 × 950 × 5 = 2,137,500 + +2. **Sum numerator:** 2,137,500 + 896,000 + 735,000 + 360,060 + 450,000 = **4,578,560** + +3. **Calculate total weights for each requirement:** + + ``` + Denominator = Σ(total_i × weight_i × risk_i) + ``` + + - **Access Controls (1.2 Authorization)**: 400 × 800 × 4 = 1,280,000 + - **Network Segmentation (2.1 Network)**: 200 × 750 × 4 = 600,000 + - **Backup Security (2.2 Storage)**: 300 × 600 × 3 = 540,000 + - **Audit Logging (3.1 Logging)**: 400 × 700 × 3 = 840,000 + - **Encryption (4.2 At-Rest)**: 500 × 950 × 5 = 2,375,000 + +4. **Sum denominator:** 2,375,000 + 1,280,000 + 840,000 + 540,000 + 600,000 = **5,635,000** + +5. **Final ThreatScore calculation:** + + ``` + ThreatScore = (Numerator / Denominator) × 100 + ThreatScore = (4,578,560 / 5,635,000) × 100 = 81.2% + ``` + +**Pillar-Level Analysis:** + +- **1. IAM pillar (1.2 Authorization)**: Significant impact despite lower pass rate (70%) due to high weight (800) +- **2. Attack Surface pillar (2.1 Network)**: Strong performance (75%) with high weight (750) balances the score +- **2. Attack Surface pillar (2.2 Storage)**: Lowest performance (66.7%) but limited impact due to moderate weight (600) +- **3. Logging and Monitoring pillar (3.1 Logging)**: Moderate contribution with good performance (87.5%) +- **4. Encryption pillar (4.2 At-Rest)**: Highest contribution due to maximum weight (950) and risk (5) + +### Example 3: Multi-Pillar Comprehensive Scenario + + +| Pillar | Subpillar | Requirement | Pass | Fail | Weight | Risk | Pass Rate | +|--------|-----------|-------------|------|------|--------|------|-----------| +| 1. IAM | 1.1 Authentication | MFA Implementation | 180 | 20 | 900 | 5 | 90% | +| 1. IAM | 1.2 Authorization | Least Privilege Access | 150 | 50 | 850 | 4 | 75% | +| 1. IAM | 1.3 Privilege Escalation | Admin Account Controls | 95 | 5 | 950 | 5 | 95% | +| 2. Attack Surface | 2.1 Network | Firewall Configuration | 400 | 100 | 600 | 3 | 80% | +| 2. Attack Surface | 2.1 Network | Public Endpoint Security | 80 | 20 | 700 | 4 | 80% | +| 2. Attack Surface | 2.2 Storage | Data Classification | 300 | 100 | 650 | 3 | 75% | +| 2. Attack Surface | 2.3 Application | Input Validation | 150 | 50 | 500 | 3 | 75% | +| 3. Logging and Monitoring | 3.1 Logging | Transaction Logging | 500 | 50 | 750 | 3 | 90.9% | +| 3. Logging and Monitoring | 3.3 Monitoring | Real-time Alerts | 200 | 50 | 700 | 4 | 80% | +| 4. Encryption | 4.2 At-Rest | Database Encryption | 300 | 20 | 900 | 5 | 93.8% | +| 4. Encryption | 4.1 In-Transit | API/Web Encryption | 250 | 10 | 800 | 4 | 96.2% | + +**Pillar Performance Summary**: + +- **1. IAM Pillar Average**: ~87% (weighted by findings across Authentication, Authorization, and Privilege Escalation subpillars) +- **2. Attack Surface Pillar Average**: ~77% (weighted across Network, Storage, and Application subpillars) + - 2.1 Network subpillar: ~80% average + - 2.2 Storage subpillar: 75% + - 2.3 Application subpillar: 75% +- **3. Logging and Monitoring Average**: ~87% (weighted by findings across Logging and Monitoring subpillars) +- **4. Encryption Pillar Average**: ~94% (weighted by findings across In-Transit and At-Rest subpillars) + +**Overall ThreatScore**: ~85.3% + +This comprehensive example demonstrates how: + +- High-performing, high-weight pillars (4. Encryption, 1. IAM) significantly boost the score +- The 2. Attack Surface pillar shows how diverse subpillars (Network, Storage, Application) are aggregated +- Multiple requirements within pillars provide detailed granular assessment +- Cross-pillar balance prevents single points of failure in security posture + +### Example 4: Impact of Parameter Changes + +Using the scenario, let's see how parameter changes affect the score: + +#### Scenario A: Increase Encryption Risk Level + +Change Encryption risk from 5 to 3: + +- **New ThreatScore: 77.8%** (decrease of 3.4 points) +- **Impact**: Lower risk weighting reduces the influence of high-performing critical controls + +#### Scenario B: Improve Access Controls Pass Rate + +Change Access Controls from 70% to 90% pass rate: + +- **New ThreatScore: 85.1%** (increase of 3.9 points) +- **Impact**: Improving performance on high-weight requirements has significant score impact + +#### Scenario C: Add New Low-Weight Requirement + +Add "Documentation Completeness" (50 PASS, 10 FAIL, weight=100, risk=1): + +- **New ThreatScore: 81.3%** (minimal change of 0.1 points) +- **Impact**: Low-weight requirements have minimal impact on overall score + +## Implementation Details + +### Edge Cases and Special Conditions + +#### Zero Findings Scenario +When a requirement has `total_i = 0` (no findings): + +- **Behavior**: Requirement is completely excluded from calculation +- **Rationale**: No evidence means no contribution to confidence in the score +- **Impact**: Other requirements receive proportionally more influence + +#### Perfect Score Scenario +When all requirements have 100% pass rate: + +- **Result**: ThreatScore = 100% +- **Interpretation**: All implemented security checks are passing + +#### Zero Pass Rate Scenario +When all requirements have 0% pass rate: + +- **Result**: ThreatScore = 0% +- **Interpretation**: Critical security failures across all requirements + +#### Single Requirement Framework +For frameworks with only one requirement: + +- **Formula simplification**: ThreatScore = pass_rate × 100 +- **Impact**: Weight and risk values become irrelevant for score calculation + +### Performance Considerations + +#### Computational Complexity +- **Time Complexity**: O(n) where n = number of requirements +- **Space Complexity**: O(1) - constant space for accumulation +- **Scalability**: Efficiently handles frameworks with thousands of requirements + +#### Calculation Precision +- **Floating Point**: Use double precision for intermediate calculations +- **Rounding**: Final score rounded to 1 decimal place for display +- **Overflow Protection**: Validate that weight × risk × total values don't exceed system limits + +### Data Requirements + +#### Minimum Data Set +For each requirement, the following data must be available: + +- **pass_count**: Number of PASS findings (integer ≥ 0) +- **fail_count**: Number of FAIL findings (integer ≥ 0) +- **weight**: Business importance (integer 1-1000) +- **risk**: Risk level (integer 1-5) + +#### Data Validation Rules +``` +total_i = pass_i + fail_i +rate_i = pass_i / total_i (when total_i > 0) +1 ≤ weight_i ≤ 1000 +1 ≤ risk_i ≤ 5 +``` + +#### Handling Invalid Data +- **Negative values**: Treat as 0 and log warning +- **Out-of-range weights/risk**: Clamp to valid range and log warning +- **Missing data**: Exclude requirement from calculation and log warning + +## Best Practices + +### Monitoring and Trending + +1. **Establish Baseline** + - Record initial ThreatScore after implementing measurement + - Set realistic improvement targets based on organizational capacity + - Track score changes over time to identify trends + +2. **Regular Reporting** + - Generate monthly ThreatScore reports for stakeholders + - Highlight significant score changes and their causes + - Include requirement-level breakdowns for detailed analysis + +3. **Continuous Improvement** + - Use score trends to identify systematic issues + - Correlate score changes with security incidents or changes + - Adjust weights and risk levels based on lessons learned + diff --git a/mkdocs.yml b/mkdocs.yml index b9170130b3..b9b2d364d2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -138,6 +138,10 @@ nav: - MongoDB Atlas: - Getting Started: tutorials/mongodbatlas/getting-started-mongodbatlas.md - Authentication: tutorials/mongodbatlas/authentication.md + + - Compliance: + - ThreatScore: tutorials/compliance/threatscore.md + - Developer Guide: - Concepts: - Introduction: developer-guide/introduction.md