aws-cis-controls-assessment 1.0.9__py3-none-any.whl → 1.0.10__py3-none-any.whl

docs/developer-guide.md

@@ -1,15 +1,16 @@
 # Developer Guide
 
-This guide covers extending and customizing the AWS CIS Controls Compliance Assessment Framework - a production-ready, enterprise-grade solution with 136 implemented rules (131 CIS Controls + 5 bonus security enhancements).
+This guide covers extending and customizing the AWS CIS Controls Compliance Assessment Framework - a production-ready, enterprise-grade solution with 138 implemented rules (133 CIS Controls + 5 bonus security enhancements).
 
 ## Production Framework Status
 
 **✅ Complete Implementation**
 - 100% CIS Controls coverage across all Implementation Groups
-- 136 total rules implemented (131 CIS + 5 bonus)
+- 138 total rules implemented (133 CIS + 5 bonus)
 - Production-tested architecture with comprehensive error handling
 - Enterprise-grade performance and scalability
 - Ready for immediate deployment and customization
+- **NEW:** AWS Backup service controls for infrastructure assessment
 
 ## Table of Contents
 
@@ -855,4 +856,312 @@ Common utility functions are available in various modules:
 
 - `aws_cis_assessment.cli.utils`: CLI utilities
 - `aws_cis_assessment.core.utils`: Core utilities
-- `aws_cis_assessment.reporters.utils`: Reporting utilities
+- `aws_cis_assessment.reporters.utils`: Reporting utilities
+
+
+## AWS Backup Controls Example (New in v1.0.10)
+
+### Overview
+
+The AWS Backup service controls demonstrate best practices for implementing service-level assessments. These controls assess the backup infrastructure itself, complementing resource-specific backup controls.
+
+### Implementation Example
+
+```python
+# aws_cis_assessment/controls/ig1/control_aws_backup_service.py
+from typing import Dict, List, Any
+import logging
+import json
+from botocore.exceptions import ClientError
+
+from aws_cis_assessment.controls.base_control import BaseConfigRuleAssessment
+from aws_cis_assessment.core.models import ComplianceResult, ComplianceStatus
+from aws_cis_assessment.core.aws_client_factory import AWSClientFactory
+
+logger = logging.getLogger(__name__)
+
+
+class BackupPlanMinFrequencyAndMinRetentionCheckAssessment(BaseConfigRuleAssessment):
+    """Assessment for backup-plan-min-frequency-and-min-retention-check Config rule.
+    
+    Validates that AWS Backup plans have appropriate backup frequency and retention
+    policies to ensure data protection and recovery capabilities.
+    """
+    
+    def __init__(self, min_retention_days: int = 7):
+        """Initialize backup plan assessment.
+        
+        Args:
+            min_retention_days: Minimum retention period in days (default: 7)
+        """
+        super().__init__(
+            rule_name="backup-plan-min-frequency-and-min-retention-check",
+            control_id="11.2",
+            resource_types=["AWS::Backup::BackupPlan"]
+        )
+        self.min_retention_days = min_retention_days
+    
+    def _get_resources(self, aws_factory: AWSClientFactory, 
+                      resource_type: str, region: str) -> List[Dict[str, Any]]:
+        """Get all AWS Backup plans in the region."""
+        if resource_type != "AWS::Backup::BackupPlan":
+            return []
+        
+        try:
+            backup_client = aws_factory.get_client('backup', region)
+            
+            # List all backup plans
+            response = aws_factory.aws_api_call_with_retry(
+                lambda: backup_client.list_backup_plans()
+            )
+            
+            plans = []
+            for plan in response.get('BackupPlansList', []):
+                plan_id = plan.get('BackupPlanId')
+                plan_name = plan.get('BackupPlanName')
+                
+                try:
+                    # Get detailed plan information including rules
+                    plan_details = aws_factory.aws_api_call_with_retry(
+                        lambda: backup_client.get_backup_plan(BackupPlanId=plan_id)
+                    )
+                    
+                    plans.append({
+                        'BackupPlanId': plan_id,
+                        'BackupPlanName': plan_name,
+                        'BackupPlan': plan_details.get('BackupPlan'),
+                        'BackupPlanArn': plan_details.get('BackupPlanArn'),
+                        'VersionId': plan.get('VersionId'),
+                        'CreationDate': plan.get('CreationDate')
+                    })
+                    
+                except ClientError as e:
+                    logger.warning(f"Could not get details for backup plan {plan_name}: {e}")
+                    # Include plan with minimal info
+                    plans.append({
+                        'BackupPlanId': plan_id,
+                        'BackupPlanName': plan_name,
+                        'BackupPlan': None,
+                        'Error': str(e)
+                    })
+            
+            logger.info(f"Retrieved {len(plans)} backup plan(s) in region {region}")
+            return plans
+            
+        except ClientError as e:
+            if e.response.get('Error', {}).get('Code') in ['AccessDenied', 'UnauthorizedOperation']:
+                logger.warning(f"Insufficient permissions to list backup plans in region {region}")
+                return []
+            logger.error(f"Error retrieving backup plans in region {region}: {e}")
+            raise
+    
+    def _evaluate_resource_compliance(self, resource: Dict[str, Any], 
+                                    aws_factory: AWSClientFactory, 
+                                    region: str) -> ComplianceResult:
+        """Evaluate if backup plan has appropriate frequency and retention."""
+        plan_id = resource.get('BackupPlanId', 'unknown')
+        plan_name = resource.get('BackupPlanName', 'unknown')
+        backup_plan = resource.get('BackupPlan')
+        
+        # Check if plan details were retrieved
+        if backup_plan is None:
+            error_msg = resource.get('Error', 'Unknown error')
+            return ComplianceResult(
+                resource_id=plan_id,
+                resource_type="AWS::Backup::BackupPlan",
+                compliance_status=ComplianceStatus.ERROR,
+                evaluation_reason=f"Could not retrieve backup plan details: {error_msg}",
+                config_rule_name=self.rule_name,
+                region=region
+            )
+        
+        # Check backup rules
+        rules = backup_plan.get('Rules', [])
+        
+        if not rules:
+            return ComplianceResult(
+                resource_id=plan_id,
+                resource_type="AWS::Backup::BackupPlan",
+                compliance_status=ComplianceStatus.NON_COMPLIANT,
+                evaluation_reason=f"Backup plan '{plan_name}' has no backup rules defined",
+                config_rule_name=self.rule_name,
+                region=region
+            )
+        
+        # Validate each rule
+        compliant_rules = 0
+        issues = []
+        
+        for rule in rules:
+            rule_name = rule.get('RuleName', 'unnamed')
+            schedule = rule.get('ScheduleExpression', '')
+            lifecycle = rule.get('Lifecycle', {})
+            
+            # Check schedule expression
+            if not schedule:
+                issues.append(f"Rule '{rule_name}' has no schedule expression")
+                continue
+            
+            # Validate schedule format (cron or rate expression)
+            has_valid_schedule = self._validate_schedule_expression(schedule)
+            if not has_valid_schedule:
+                issues.append(f"Rule '{rule_name}' has invalid schedule expression: {schedule}")
+            
+            # Check retention period
+            delete_after_days = lifecycle.get('DeleteAfterDays')
+            move_to_cold_storage_after_days = lifecycle.get('MoveToColdStorageAfterDays')
+            
+            if delete_after_days is None:
+                issues.append(f"Rule '{rule_name}' has no retention period defined")
+            elif delete_after_days < self.min_retention_days:
+                issues.append(
+                    f"Rule '{rule_name}' has insufficient retention "
+                    f"({delete_after_days} days, minimum: {self.min_retention_days} days)"
+                )
+            else:
+                # Check cold storage configuration if present
+                if move_to_cold_storage_after_days is not None:
+                    if move_to_cold_storage_after_days >= delete_after_days:
+                        issues.append(
+                            f"Rule '{rule_name}' has invalid lifecycle: "
+                            f"cold storage transition ({move_to_cold_storage_after_days} days) "
+                            f"must be before deletion ({delete_after_days} days)"
+                        )
+                    else:
+                        # Rule is compliant
+                        if has_valid_schedule:
+                            compliant_rules += 1
+                else:
+                    # No cold storage, just check schedule and retention
+                    if has_valid_schedule:
+                        compliant_rules += 1
+        
+        # Determine overall compliance
+        if compliant_rules == len(rules) and not issues:
+            compliance_status = ComplianceStatus.COMPLIANT
+            evaluation_reason = (
+                f"Backup plan '{plan_name}' has {len(rules)} compliant rule(s) "
+                f"with valid schedules and retention >= {self.min_retention_days} days"
+            )
+        elif compliant_rules > 0:
+            compliance_status = ComplianceStatus.NON_COMPLIANT
+            evaluation_reason = (
+                f"Backup plan '{plan_name}' has {compliant_rules}/{len(rules)} compliant rules. "
+                f"Issues: {'; '.join(issues)}"
+            )
+        else:
+            compliance_status = ComplianceStatus.NON_COMPLIANT
+            evaluation_reason = (
+                f"Backup plan '{plan_name}' has no compliant rules. "
+                f"Issues: {'; '.join(issues)}"
+            )
+        
+        return ComplianceResult(
+            resource_id=plan_id,
+            resource_type="AWS::Backup::BackupPlan",
+            compliance_status=compliance_status,
+            evaluation_reason=evaluation_reason,
+            config_rule_name=self.rule_name,
+            region=region
+        )
+    
+    def _validate_schedule_expression(self, schedule: str) -> bool:
+        """Validate AWS Backup schedule expression format."""
+        if not schedule:
+            return False
+        
+        schedule_lower = schedule.lower().strip()
+        
+        # Check for cron expression
+        if schedule_lower.startswith('cron(') and schedule_lower.endswith(')'):
+            return True
+        
+        # Check for rate expression
+        if schedule_lower.startswith('rate(') and schedule_lower.endswith(')'):
+            return True
+        
+        return False
+```
+
+### Key Implementation Patterns
+
+1. **Configurable Parameters**: The `min_retention_days` parameter allows customization
+2. **Comprehensive Error Handling**: Gracefully handles access denied and missing resources
+3. **Detailed Evaluation**: Provides specific reasons for non-compliance
+4. **Validation Logic**: Validates schedule expressions and lifecycle policies
+5. **Logging**: Appropriate logging for troubleshooting
+
+### Testing Example
+
+```python
+# tests/test_aws_backup_service_controls.py
+import pytest
+from unittest.mock import Mock
+from botocore.exceptions import ClientError
+
+from aws_cis_assessment.controls.ig1.control_aws_backup_service import (
+    BackupPlanMinFrequencyAndMinRetentionCheckAssessment
+)
+from aws_cis_assessment.core.models import ComplianceStatus
+
+class TestBackupPlanMinFrequencyAndMinRetentionCheckAssessment:
+    
+    def test_compliant_plan(self):
+        """Test evaluation of compliant backup plan."""
+        assessment = BackupPlanMinFrequencyAndMinRetentionCheckAssessment()
+        aws_factory = Mock()
+        
+        resource = {
+            'BackupPlanId': 'plan-123',
+            'BackupPlanName': 'daily-backup',
+            'BackupPlan': {
+                'Rules': [{
+                    'RuleName': 'daily-rule',
+                    'ScheduleExpression': 'cron(0 5 * * ? *)',
+                    'Lifecycle': {'DeleteAfterDays': 30}
+                }]
+            }
+        }
+        
+        result = assessment._evaluate_resource_compliance(resource, aws_factory, "us-east-1")
+        
+        assert result.compliance_status == ComplianceStatus.COMPLIANT
+        assert 'compliant rule(s)' in result.evaluation_reason
+        assert result.resource_id == 'plan-123'
+    
+    def test_plan_insufficient_retention(self):
+        """Test evaluation of backup plan with insufficient retention."""
+        assessment = BackupPlanMinFrequencyAndMinRetentionCheckAssessment()
+        aws_factory = Mock()
+        
+        resource = {
+            'BackupPlanId': 'plan-123',
+            'BackupPlanName': 'short-retention',
+            'BackupPlan': {
+                'Rules': [{
+                    'RuleName': 'short-rule',
+                    'ScheduleExpression': 'cron(0 5 * * ? *)',
+                    'Lifecycle': {'DeleteAfterDays': 3}  # Less than minimum 7 days
+                }]
+            }
+        }
+        
+        result = assessment._evaluate_resource_compliance(resource, aws_factory, "us-east-1")
+        
+        assert result.compliance_status == ComplianceStatus.NON_COMPLIANT
+        assert 'insufficient retention' in result.evaluation_reason
+```
+
+### Documentation
+
+For complete documentation on AWS Backup controls, see:
+- [AWS Backup Controls Implementation Guide](adding-aws-backup-controls.md)
+- [AWS Backup Controls Summary](../AWS_BACKUP_CONTROLS_IMPLEMENTATION_SUMMARY.md)
+
+### Benefits of This Approach
+
+1. **Hybrid Model**: Combines resource-specific and service-level assessments
+2. **Comprehensive Coverage**: Validates both resource protection and infrastructure security
+3. **Flexible**: Works for organizations using AWS Backup or service-native backups
+4. **Extensible**: Easy to add more AWS Backup controls (vault lock, restore testing, etc.)
+5. **Production-Ready**: Full error handling, logging, and testing

docs/installation.md

@@ -7,7 +7,7 @@ This guide covers the installation and initial setup of the AWS CIS Controls Com
 ## Production Status
 
 **✅ Ready for Enterprise Deployment**
-- Complete implementation with 136 AWS Config rules (131 CIS Controls + 5 bonus)
+- Complete implementation with 138 AWS Config rules (133 CIS Controls + 5 bonus)
 - 100% CIS Controls coverage across all Implementation Groups
 - Production-tested architecture with comprehensive error handling
 - Enterprise-grade performance and scalability
@@ -104,7 +104,7 @@ aws-cis-assess assess --aws-profile my-sso-profile
 
 ## Required IAM Permissions
 
-The tool requires read-only permissions for various AWS services. Here's a comprehensive IAM policy that covers all 136 assessments:
+The tool requires read-only permissions for various AWS services. Here's a comprehensive IAM policy that covers all 138 assessments:
 
 ```json
 {

docs/troubleshooting.md

@@ -1,6 +1,6 @@
 # Troubleshooting Guide
 
-This guide helps you diagnose and resolve common issues with the AWS CIS Controls Compliance Assessment Framework - a production-ready, enterprise-grade solution with 136 implemented rules.
+This guide helps you diagnose and resolve common issues with the AWS CIS Controls Compliance Assessment Framework - a production-ready, enterprise-grade solution with 138 implemented rules.
 
 ## Production Framework Status
 
@@ -631,4 +631,213 @@ When reporting issues, include:
 For enterprise users:
 - **AWS Support**: For AWS service-related issues
 - **Professional Services**: For implementation assistance
-- **Training**: For team education and best practices
+- **Training**: For team education and best practices
+
+
+## AWS Backup Controls Issues
+
+### Problem: Backup Plan Assessment Failures
+
+**Error Message:**
+```
+AccessDenied: User is not authorized to perform: backup:ListBackupPlans
+```
+
+**Solutions:**
+
+1. **Add Backup permissions:**
+   ```bash
+   # Ensure IAM policy includes Backup permissions
+   aws iam attach-user-policy \
+     --user-name your-user \
+     --policy-arn arn:aws:iam::aws:policy/AWSBackupReadOnlyAccess
+   ```
+
+2. **Verify Backup service availability:**
+   ```bash
+   # Check if Backup service is available in region
+   aws backup list-backup-plans --region us-east-1
+   ```
+
+3. **Check for Backup plans:**
+   ```bash
+   # List existing backup plans
+   aws backup list-backup-plans --query 'BackupPlansList[*].[BackupPlanName,BackupPlanId]' --output table
+   ```
+
+### Problem: Backup Vault Access Policy Check Failures
+
+**Error Message:**
+```
+ResourceNotFoundException: Backup vault not found
+```
+
+**Solutions:**
+
+1. **Verify backup vaults exist:**
+   ```bash
+   # List backup vaults in region
+   aws backup list-backup-vaults --region us-east-1
+   ```
+
+2. **Check vault access policy:**
+   ```bash
+   # Get vault access policy
+   aws backup get-backup-vault-access-policy --backup-vault-name MyVault
+   ```
+
+3. **Create backup vault if needed:**
+   ```bash
+   # Create a backup vault
+   aws backup create-backup-vault --backup-vault-name MyVault
+   ```
+
+### Problem: Backup Plan Frequency/Retention Validation
+
+**Symptoms:**
+- Backup plans marked as non-compliant
+- Frequency or retention requirements not met
+- Assessment shows "Backup plan does not meet minimum requirements"
+
+**Solutions:**
+
+1. **Review backup plan rules:**
+   ```bash
+   # Get backup plan details
+   aws backup get-backup-plan --backup-plan-id <plan-id>
+   ```
+
+2. **Check schedule expression:**
+   ```bash
+   # Verify cron/rate expression meets requirements
+   # Minimum daily frequency: cron(0 0 * * ? *) or rate(1 day)
+   ```
+
+3. **Verify retention settings:**
+   ```bash
+   # Ensure DeleteAfterDays >= 35 days (5 weeks)
+   # Check lifecycle settings in backup plan rules
+   ```
+
+4. **Update backup plan:**
+   ```bash
+   # Update plan to meet requirements
+   aws backup update-backup-plan \
+     --backup-plan-id <plan-id> \
+     --backup-plan file://updated-plan.json
+   ```
+
+### Problem: No Backup Resources Found
+
+**Symptoms:**
+- Assessment shows "No backup plans found"
+- Zero backup-related resources discovered
+- All backup controls show NOT_APPLICABLE
+
+**Solutions:**
+
+1. **Enable AWS Backup:**
+   ```bash
+   # Create your first backup plan
+   aws backup create-backup-plan --backup-plan file://backup-plan.json
+   ```
+
+2. **Check region scope:**
+   ```bash
+   # Backup resources are regional
+   # Ensure you're checking the correct regions
+   aws-cis-assess assess --regions us-east-1,us-west-2 --verbose
+   ```
+
+3. **Verify service availability:**
+   ```bash
+   # Check if Backup service is enabled in your account
+   aws backup describe-global-settings
+   ```
+
+### Problem: Backup Vault Policy Validation
+
+**Symptoms:**
+- Vault policy marked as non-compliant
+- "Vault allows public access" or "Vault policy too permissive"
+- Policy validation failures
+
+**Solutions:**
+
+1. **Review vault policy:**
+   ```bash
+   # Get current vault policy
+   aws backup get-backup-vault-access-policy \
+     --backup-vault-name MyVault \
+     --query 'Policy' \
+     --output text | jq .
+   ```
+
+2. **Check for overly permissive principals:**
+   ```json
+   {
+     "Statement": [{
+       "Principal": "*",  // ❌ Too permissive
+       "Effect": "Allow",
+       "Action": "backup:*"
+     }]
+   }
+   ```
+
+3. **Update vault policy:**
+   ```bash
+   # Apply restrictive policy
+   aws backup put-backup-vault-access-policy \
+     --backup-vault-name MyVault \
+     --policy file://restrictive-policy.json
+   ```
+
+4. **Best practice policy example:**
+   ```json
+   {
+     "Version": "2012-10-17",
+     "Statement": [{
+       "Effect": "Allow",
+       "Principal": {
+         "AWS": "arn:aws:iam::123456789012:role/BackupRole"
+       },
+       "Action": [
+         "backup:DescribeBackupVault",
+         "backup:ListRecoveryPointsByBackupVault"
+       ],
+       "Resource": "*"
+     }]
+   }
+   ```
+
+### Problem: Backup Assessment Performance
+
+**Symptoms:**
+- Backup control assessments take too long
+- Timeout errors during backup plan evaluation
+- High API call volume to Backup service
+
+**Solutions:**
+
+1. **Limit assessment scope:**
+   ```bash
+   # Assess only specific backup controls
+   aws-cis-assess assess --controls 11.1,11.2 --regions us-east-1
+   ```
+
+2. **Reduce parallel workers:**
+   ```bash
+   # Lower concurrency for Backup API calls
+   aws-cis-assess assess --max-workers 2
+   ```
+
+3. **Check for large number of backup plans:**
+   ```bash
+   # Count backup plans
+   aws backup list-backup-plans --query 'length(BackupPlansList)'
+   ```
+
+4. **Optimize backup plan structure:**
+   - Consolidate multiple small plans into fewer comprehensive plans
+   - Use backup selections to target specific resources
+   - Avoid creating excessive backup plans per region

docs/user-guide.md

@@ -5,10 +5,11 @@ This comprehensive guide covers how to use the AWS CIS Controls Compliance Asses
 ## Production Framework Overview
 
 **✅ Complete Implementation**
-- 136 AWS Config rules implemented (131 CIS Controls + 5 bonus security rules)
+- 138 AWS Config rules implemented (133 CIS Controls + 5 bonus security rules)
 - 100% coverage across all Implementation Groups (IG1, IG2, IG3)
 - Production-tested architecture with enterprise-grade error handling
 - Ready for immediate deployment in production environments
+- **NEW:** AWS Backup service controls for infrastructure assessment
 
 ## Table of Contents
 
@@ -490,4 +491,48 @@ Each non-compliant finding includes:
 - **Configuration Guide**: Learn about customizing assessments
 - **Troubleshooting Guide**: Resolve common issues
 - **CLI Reference**: Complete command reference
-- **Developer Guide**: Extend and customize the tool
+- **Developer Guide**: Extend and customize the tool
+
+
+## AWS Backup Controls (New in v1.0.10)
+
+### Overview
+
+Two new controls have been added to assess AWS Backup service infrastructure:
+
+1. **backup-plan-min-frequency-and-min-retention-check**
+   - Validates backup plans have appropriate frequency and retention policies
+   - Ensures backups happen regularly (daily minimum)
+   - Checks retention periods meet minimum requirements (7 days default)
+   - Validates lifecycle policies for cold storage transitions
+
+2. **backup-vault-access-policy-check**
+   - Ensures backup vaults have secure access policies
+   - Detects publicly accessible backup vaults
+   - Identifies overly permissive access policies
+   - Warns about dangerous permissions
+
+### Usage
+
+These controls are automatically included in IG1 assessments:
+
+```bash
+# Run assessment including new backup controls
+aws-cis-assess assess --implementation-groups IG1
+
+# Focus on backup-related controls
+aws-cis-assess assess --controls 11.2
+```
+
+### Benefits
+
+- **Comprehensive Coverage**: Assesses both resource protection AND backup infrastructure
+- **Security Validation**: Ensures backup vaults aren't publicly accessible
+- **Compliance Checking**: Validates backup policies meet organizational requirements
+- **Ransomware Protection**: Helps identify backup vulnerabilities
+
+### Documentation
+
+For detailed information about AWS Backup controls, see:
+- [AWS Backup Controls Implementation Guide](adding-aws-backup-controls.md)
+- [AWS Backup Controls Summary](../AWS_BACKUP_CONTROLS_IMPLEMENTATION_SUMMARY.md)