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¶

Regulatory Mapping: Assign higher weights to controls required by industry regulations
Business Impact: Consider the potential business impact of control failures
Risk Tolerance: Align weights with organizational risk appetite
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:

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
Sum numerator: 2,137,500 + 896,000 + 735,000 + 360,060 + 450,000 = 4,578,560
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
Sum denominator: 2,375,000 + 1,280,000 + 840,000 + 540,000 + 600,000 = 5,635,000

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¶

Establish Baseline
- Record initial ThreatScore after implementing measurement
- Set realistic improvement targets based on organizational capacity
- Track score changes over time to identify trends
Regular Reporting
- Generate monthly ThreatScore reports for stakeholders
- Highlight significant score changes and their causes
- Include requirement-level breakdowns for detailed analysis
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

Prowler ThreatScore Documentation¶

Introduction¶

Purpose¶

How ThreatScore Works¶

1. Pass Rate (rate_i)¶

2. Total Findings (total_i)¶

3. Weight (weight_i)¶

4. Risk Level (risk_i)¶

Score Interpretation Guidelines¶

Mathematical Formula¶

Formula Properties¶

Parameters Explained¶

Weight Values (1-1000)¶

Weight Assignment Guidelines¶

Weight Selection Strategy¶

Risk Levels (1-5)¶

Risk Level Assessment Criteria¶

Security Pillars and Subpillars¶

Security Pillars Overview¶

1. IAM (Identity and Access Management)¶

2. Attack Surface¶

3. Logging and Monitoring¶

4. Encryption¶

Pillar Hierarchy and ThreatScore Impact¶

Hierarchy Structure¶

Weight and Risk Assignment by Pillar¶

Pillar-Specific Scoring Considerations¶

High-Impact Pillars (1. IAM, 4. Encryption)¶

Variable-Impact Pillar (2. Attack Surface)¶

Monitoring Pillar (3. Logging and Monitoring)¶

Cross-Pillar Dependencies¶

Authentication ↔ Authorization (IAM)¶

Logging ↔ Monitoring (Logging and Monitoring)¶

In-Transit ↔ At-Rest (Encryption)¶

Pillar Coverage in ThreatScore¶

Complete Coverage Benefits¶

Partial Coverage Considerations¶

Scoring Examples¶

Example 1: Basic Two-Requirement Scenario¶

Example 2: Enterprise Scenario with Pillar Structure¶

Example 3: Multi-Pillar Comprehensive Scenario¶

Example 4: Impact of Parameter Changes¶

Scenario A: Increase Encryption Risk Level¶

Scenario B: Improve Access Controls Pass Rate¶

Scenario C: Add New Low-Weight Requirement¶

Implementation Details¶

Edge Cases and Special Conditions¶

Zero Findings Scenario¶

Perfect Score Scenario¶

Zero Pass Rate Scenario¶

Single Requirement Framework¶

Performance Considerations¶

Computational Complexity¶

Calculation Precision¶

Data Requirements¶

Minimum Data Set¶

Data Validation Rules¶

Handling Invalid Data¶

Best Practices¶

Monitoring and Trending¶

1. Pass Rate (`rate_i`)¶

2. Total Findings (`total_i`)¶

3. Weight (`weight_i`)¶

4. Risk Level (`risk_i`)¶