aws-cis-controls-assessment 1.1.4__py3-none-any.whl → 1.2.2__py3-none-any.whl

docs/developer-guide.md

@@ -1,16 +1,17 @@
 # Developer Guide
 
-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).
+This guide covers extending and customizing the AWS CIS Controls Compliance Assessment Framework - a production-ready, enterprise-grade solution with **175 total rules** (125 IG1 + 38 IG2 + 12 IG3).
 
 ## Production Framework Status
 
-**✅ Complete Implementation**
-- 100% CIS Controls coverage across all Implementation Groups
-- 138 total rules implemented (133 CIS + 5 bonus)
+**✅ Enhanced CIS Controls v8.1 Coverage**
+- **125 IG1 rules** (75%+ coverage of CIS Controls v8.1 IG1 safeguards)
+- **38 IG2 rules** and **12 IG3 rules** for enhanced and advanced security
+- **50 new rules** added in v1.2.0 across 4 phases
 - Production-tested architecture with comprehensive error handling
 - Enterprise-grade performance and scalability
+- Coverage metrics reporting for transparency
 - Ready for immediate deployment and customization
-- **NEW:** AWS Backup service controls for infrastructure assessment
 
 ## Table of Contents
 
@@ -122,6 +123,204 @@ mypy aws_cis_assessment/
 pre-commit run --all-files
 ```
 
+## Implementation Patterns from Phase 1-4 Rules
+
+### Overview
+
+The 50 new rules added in v1.2.0 follow consistent implementation patterns that serve as excellent examples for adding new controls. These patterns ensure reliability, maintainability, and consistency across the framework.
+
+### Pattern 1: Service Enablement Checks
+
+Used for validating AWS security service enablement (GuardDuty, Inspector, Macie, etc.).
+
+**Key Characteristics:**
+- Check if service is enabled in the account/region
+- Handle service not available scenarios gracefully
+- Return NOT_APPLICABLE if service doesn't exist in region
+
+**Example: GuardDuty Enablement**
+```python
+def _get_resources(self, aws_factory: AWSClientFactory, region: str) -> List[Dict[str, Any]]:
+    """List GuardDuty detectors."""
+    try:
+        guardduty_client = aws_factory.get_client('guardduty', region)
+        response = guardduty_client.list_detectors()
+        
+        if not response.get('DetectorIds'):
+            # No detectors = service not enabled
+            return [{'DetectorId': 'NONE', 'Region': region, 'Status': 'NOT_ENABLED'}]
+        
+        return [{'DetectorId': detector_id, 'Region': region} 
+                for detector_id in response['DetectorIds']]
+    except Exception as e:
+        logger.error(f"Error listing GuardDuty detectors: {e}")
+        return []
+```
+
+### Pattern 2: Logging Enablement Checks
+
+Used for validating logging configuration (VPC Flow Logs, ELB logging, CloudFront, WAF).
+
+**Key Characteristics:**
+- List primary resources (VPCs, load balancers, distributions)
+- Check if logging is configured for each resource
+- Provide specific remediation steps
+
+**Example: VPC Flow Logs**
+```python
+def _evaluate_resource_compliance(self, resource: Dict[str, Any], 
+                                 aws_factory: AWSClientFactory) -> ComplianceResult:
+    """Check if VPC has Flow Logs enabled."""
+    vpc_id = resource['VpcId']
+    region = resource.get('Region', 'us-east-1')
+    
+    ec2_client = aws_factory.get_client('ec2', region)
+    
+    # Check for flow logs
+    response = ec2_client.describe_flow_logs(
+        Filters=[{'Name': 'resource-id', 'Values': [vpc_id]}]
+    )
+    
+    if response.get('FlowLogs'):
+        return self._create_compliant_result(vpc_id, region, 
+                                            "VPC has Flow Logs enabled")
+    else:
+        return self._create_non_compliant_result(vpc_id, region,
+                                                "VPC does not have Flow Logs enabled")
+```
+
+### Pattern 3: Encryption Validation
+
+Used for checking encryption at rest (EBS, RDS, EFS, DynamoDB, S3).
+
+**Key Characteristics:**
+- Verify encryption is enabled
+- Check for KMS encryption when required
+- Handle different encryption types (default vs KMS)
+
+**Example: RDS Storage Encryption**
+```python
+def _evaluate_resource_compliance(self, resource: Dict[str, Any],
+                                 aws_factory: AWSClientFactory) -> ComplianceResult:
+    """Check if RDS instance has storage encryption enabled."""
+    db_instance_id = resource['DBInstanceIdentifier']
+    encrypted = resource.get('StorageEncrypted', False)
+    
+    if encrypted:
+        return self._create_compliant_result(db_instance_id, region,
+                                            "RDS instance has storage encryption enabled")
+    else:
+        return self._create_non_compliant_result(db_instance_id, region,
+                                                "RDS instance does not have storage encryption")
+```
+
+### Pattern 4: Configuration Validation
+
+Used for checking configuration settings (SSM Patch Manager, AWS Config, Security Hub).
+
+**Key Characteristics:**
+- Validate service configuration exists
+- Check configuration meets requirements
+- Handle multi-region scenarios
+
+**Example: Config Multi-Region**
+```python
+def _get_resources(self, aws_factory: AWSClientFactory, region: str) -> List[Dict[str, Any]]:
+    """Check Config in all regions."""
+    resources = []
+    
+    for check_region in aws_factory.regions:
+        try:
+            config_client = aws_factory.get_client('config', check_region)
+            response = config_client.describe_configuration_recorders()
+            
+            if response.get('ConfigurationRecorders'):
+                resources.append({
+                    'Region': check_region,
+                    'Status': 'ENABLED',
+                    'Recorders': response['ConfigurationRecorders']
+                })
+            else:
+                resources.append({
+                    'Region': check_region,
+                    'Status': 'NOT_ENABLED'
+                })
+        except Exception as e:
+            logger.error(f"Error checking Config in {check_region}: {e}")
+    
+    return resources
+```
+
+### Pattern 5: Inventory Tracking
+
+Used for asset inventory controls (AMI tracking, Lambda runtimes, IAM users).
+
+**Key Characteristics:**
+- List all resources of a type
+- Check for required tags or metadata
+- Track versions and configurations
+
+**Example: Lambda Runtime Inventory**
+```python
+def _evaluate_resource_compliance(self, resource: Dict[str, Any],
+                                 aws_factory: AWSClientFactory) -> ComplianceResult:
+    """Check Lambda function runtime."""
+    function_name = resource['FunctionName']
+    runtime = resource.get('Runtime', 'unknown')
+    
+    # Check if runtime is supported
+    deprecated_runtimes = ['python2.7', 'nodejs10.x', 'dotnetcore2.1']
+    
+    if runtime in deprecated_runtimes:
+        return self._create_non_compliant_result(function_name, region,
+                                                f"Function uses deprecated runtime: {runtime}")
+    else:
+        return self._create_compliant_result(function_name, region,
+                                            f"Function uses supported runtime: {runtime}")
+```
+
+### Best Practices from Phase 1-4
+
+1. **Error Handling**: Always wrap AWS API calls in try-except blocks
+2. **Graceful Degradation**: Return appropriate status when service unavailable
+3. **Detailed Remediation**: Include specific CLI commands and console steps
+4. **Resource Identification**: Use proper resource IDs for tracking
+5. **Region Awareness**: Handle multi-region scenarios correctly
+6. **Logging**: Log errors and important events for debugging
+7. **Type Safety**: Use type hints for better code quality
+8. **Documentation**: Include docstrings explaining the control
+
+### Common Helper Methods
+
+```python
+def _create_compliant_result(self, resource_id: str, region: str, 
+                            reason: str) -> ComplianceResult:
+    """Helper to create compliant result."""
+    return ComplianceResult(
+        resource_id=resource_id,
+        resource_type=self.resource_types[0],
+        compliance_status=ComplianceStatus.COMPLIANT,
+        evaluation_reason=reason,
+        config_rule_name=self.rule_name,
+        region=region,
+        timestamp=datetime.now()
+    )
+
+def _create_non_compliant_result(self, resource_id: str, region: str,
+                                reason: str) -> ComplianceResult:
+    """Helper to create non-compliant result."""
+    return ComplianceResult(
+        resource_id=resource_id,
+        resource_type=self.resource_types[0],
+        compliance_status=ComplianceStatus.NON_COMPLIANT,
+        evaluation_reason=reason,
+        config_rule_name=self.rule_name,
+        region=region,
+        timestamp=datetime.now(),
+        remediation_guidance=self._get_rule_remediation_steps()
+    )
+```
+
 ## Adding New Controls
 
 ### Step 1: Define Control Configuration

docs/user-guide.md

@@ -4,12 +4,13 @@ This comprehensive guide covers how to use the AWS CIS Controls Compliance Asses
 
 ## Production Framework Overview
 
-**✅ Complete Implementation**
-- 138 AWS Config rules implemented (133 CIS Controls + 5 bonus security rules)
-- 100% coverage across all Implementation Groups (IG1, IG2, IG3)
+**✅ Enhanced CIS Controls v8.1 Coverage**
+- **125 IG1 rules** implemented (75%+ coverage of CIS Controls v8.1 IG1 safeguards)
+- **50 new rules** added across security services, logging, encryption, inventory, configuration management, and backup security
+- **38 IG2 rules** and **12 IG3 rules** for enhanced and advanced security
 - Production-tested architecture with enterprise-grade error handling
 - Ready for immediate deployment in production environments
-- **NEW:** AWS Backup service controls for infrastructure assessment
+- **NEW:** Coverage metrics reporting showing safeguard coverage percentages
 
 ## Table of Contents
 
@@ -486,6 +487,138 @@ Each non-compliant finding includes:
 - Priority level (HIGH, MEDIUM, LOW)
 - Estimated effort
 
+## CIS Controls v8.1 IG1 Expansion (New in v1.2.0)
+
+### Overview
+
+Version 1.2.0 adds **50 new IG1 rules** across four phases, achieving **75%+ coverage** of CIS Controls v8.1 Implementation Group 1 safeguards. This expansion significantly enhances the framework's ability to assess essential cyber hygiene controls.
+
+### Coverage Metrics
+
+The framework now reports coverage metrics showing how many CIS Controls safeguards are assessed:
+
+- **IG1**: 42 of 56 safeguards covered (75%+) with 125 rules
+- **IG2**: 30 of 74 safeguards covered (~40%) with 38 rules
+- **IG3**: 15 of 153 safeguards covered (~10%) with 12 rules
+
+Coverage metrics appear in:
+- HTML reports (executive dashboard)
+- JSON reports (executive_summary section)
+- Assessment statistics
+
+### Phase 1 - Quick Wins (13 Rules)
+
+**Security Services (4 rules)**
+- GuardDuty enablement check
+- Inspector v2 enablement and configuration
+- Macie enablement for data discovery
+- IAM Access Analyzer deployment
+
+**Logging (4 rules)**
+- VPC Flow Logs enablement
+- ELB access logging
+- CloudFront distribution logging
+- WAF logging configuration
+
+**Encryption (5 rules)**
+- EBS encryption by default
+- RDS storage encryption
+- EFS file system encryption
+- DynamoDB table encryption with KMS
+- S3 bucket default encryption with KMS
+
+### Phase 2 - Core Security (15 Rules)
+
+**Patch Management (3 rules)**
+- SSM Patch Manager enablement
+- Patch baseline configuration
+- EC2 instance patch compliance
+
+**Access Control (5 rules)**
+- AWS SSO/Identity Center enablement
+- Identity Center configuration
+- Admin user MFA requirements
+- Cognito user pool MFA
+- VPN endpoint MFA
+
+**TLS/SSL Enforcement (5 rules)**
+- ALB HTTP to HTTPS redirection
+- ELB HTTPS-only listeners
+- RDS SSL connection requirements
+- API Gateway SSL enforcement
+- Redshift TLS requirements
+
+**Additional Encryption (3 rules)**
+- SNS topic KMS encryption
+- SQS queue encryption
+- CloudTrail S3 data events
+
+### Phase 3 - Advanced (15 Rules)
+
+**Inventory Management (5 rules)**
+- SSM Inventory enablement
+- AWS Config multi-region deployment
+- AMI inventory tracking
+- Lambda runtime inventory
+- IAM user inventory
+
+**Configuration Management (4 rules)**
+- Config conformance pack deployment
+- Security Hub standards enablement
+- Asset tagging compliance
+- Inspector assessment enablement
+
+**Version Management (3 rules)**
+- EC2 OS version support validation
+- RDS engine version support
+- Lambda runtime support
+
+**Access & Asset Management (3 rules)**
+- IAM user last access tracking
+- SSM Session Manager availability
+- Unauthorized asset detection
+
+### Phase 4 - Enhanced (7 Rules)
+
+**Data Classification (2 rules)**
+- Data resource classification tagging
+- S3 bucket classification tags
+
+**Network Security (2 rules)**
+- AWS Network Firewall deployment
+- Route 53 DNS Firewall enablement
+
+**Backup Security (5 rules)**
+- Backup vault encryption
+- Cross-region backup copy
+- Backup vault lock
+- Route 53 query logging
+- RDS backup retention
+
+### Using the New Rules
+
+All new rules are automatically included in IG1 assessments:
+
+```bash
+# Run complete IG1 assessment with all 125 rules
+aws-cis-assess assess --implementation-groups IG1
+
+# View coverage metrics in HTML report
+aws-cis-assess assess --implementation-groups IG1 --output-format html
+
+# Check specific phase rules
+aws-cis-assess list-controls --implementation-groups IG1
+```
+
+### Benefits
+
+1. **Comprehensive Coverage**: 75%+ of CIS Controls v8.1 IG1 safeguards
+2. **Security Services**: Validates enablement of AWS security services
+3. **Encryption**: Ensures encryption at rest and in transit
+4. **Inventory**: Tracks assets and software versions
+5. **Configuration**: Validates security configuration standards
+6. **Backup**: Assesses backup infrastructure security
+
 ## Next Steps
 
 - **Configuration Guide**: Learn about customizing assessments