pangea 0.0.42 → 0.0.45

data/lib/pangea/resources/aws_s3_bucket_public_access_block/CLAUDE.md

@@ -0,0 +1,528 @@
+# AWS S3 Bucket Public Access Block Implementation
+
+## Implementation Overview
+
+The `aws_s3_bucket_public_access_block` resource provides type-safe S3 bucket public access control with comprehensive security analysis and configuration management.
+
+## Architecture
+
+```
+S3BucketPublicAccessBlockAttributes (dry-struct)
+    ↓ validates
+Public Access Block Configuration
+    ↓ synthesizes
+aws_s3_bucket_public_access_block (terraform)
+    ↓ returns
+ResourceReference with security analysis
+```
+
+## Type Safety
+
+### Attributes Structure
+- **bucket**: Required string bucket name
+- **block_public_acls**: Optional boolean (default: not set)
+- **block_public_policy**: Optional boolean (default: not set) 
+- **ignore_public_acls**: Optional boolean (default: not set)
+- **restrict_public_buckets**: Optional boolean (default: not set)
+- **expected_bucket_owner**: Optional string for multi-account scenarios
+
+### Public Access Settings
+```ruby
+attribute? :block_public_acls, Resources::Types::Bool.optional
+attribute? :block_public_policy, Resources::Types::Bool.optional
+attribute? :ignore_public_acls, Resources::Types::Bool.optional
+attribute? :restrict_public_buckets, Resources::Types::Bool.optional
+```
+
+## Public Access Control Logic
+
+### Four Security Settings
+
+#### block_public_acls
+- **Purpose**: Prevents setting public ACLs on bucket and objects
+- **Effect**: Blocks PUT Object acl and PUT Bucket acl with public access
+- **Scope**: Future ACL operations only
+
+#### ignore_public_acls
+- **Purpose**: Ignores existing public ACLs on bucket and objects  
+- **Effect**: Treats all objects as private regardless of ACL settings
+- **Scope**: All ACL evaluations
+
+#### block_public_policy
+- **Purpose**: Prevents setting public bucket policies
+- **Effect**: Blocks PUT Bucket Policy operations that grant public access
+- **Scope**: Future policy operations only
+
+#### restrict_public_buckets
+- **Purpose**: Restricts access to buckets with public policies
+- **Effect**: Only allows access from within the AWS account
+- **Scope**: All policy evaluations
+
+## Helper Methods
+
+### Security Level Analysis
+```ruby
+def fully_blocked?
+  block_public_acls == true &&
+    block_public_policy == true &&
+    ignore_public_acls == true &&
+    restrict_public_buckets == true
+end
+
+def partially_blocked?
+  [block_public_acls, block_public_policy, ignore_public_acls, restrict_public_buckets]
+    .any? { |setting| setting == true }
+end
+
+def allows_public_access?
+  !partially_blocked?
+end
+```
+
+### Configuration Metrics
+```ruby
+def blocked_settings_count
+  [block_public_acls, block_public_policy, ignore_public_acls, restrict_public_buckets]
+    .count { |setting| setting == true }
+end
+
+def security_level
+  case blocked_settings_count
+  when 0 then 'open'
+  when 1..3 then 'restricted' 
+  when 4 then 'secure'
+  else 'unknown'
+  end
+end
+```
+
+### Configuration Summary
+```ruby
+def configuration_summary
+  {
+    block_public_acls: block_public_acls || false,
+    block_public_policy: block_public_policy || false,
+    ignore_public_acls: ignore_public_acls || false,
+    restrict_public_buckets: restrict_public_buckets || false
+  }
+end
+```
+
+## Terraform Integration
+
+### Resource Generation
+```ruby
+resource(:aws_s3_bucket_public_access_block, name) do
+  bucket pab_attrs.bucket
+  expected_bucket_owner pab_attrs.expected_bucket_owner if pab_attrs.expected_bucket_owner
+  
+  # Only set values that are explicitly provided
+  block_public_acls pab_attrs.block_public_acls if pab_attrs.block_public_acls
+  block_public_policy pab_attrs.block_public_policy if pab_attrs.block_public_policy
+  ignore_public_acls pab_attrs.ignore_public_acls if pab_attrs.ignore_public_acls
+  restrict_public_buckets pab_attrs.restrict_public_buckets if pab_attrs.restrict_public_buckets
+end
+```
+
+### Output Properties
+- `id`: Public access block resource ID
+- `bucket`: Associated bucket name
+- `block_public_acls`: Effective block public ACLs setting
+- `block_public_policy`: Effective block public policy setting
+- `ignore_public_acls`: Effective ignore public ACLs setting
+- `restrict_public_buckets`: Effective restrict public buckets setting
+
+## Computed Properties
+
+### Security Analysis
+- **fully_blocked**: Maximum security (all four settings enabled)
+- **partially_blocked**: Some restrictions in place
+- **allows_public_access**: No restrictions (potentially insecure)
+- **blocked_settings_count**: Number of enabled restrictions
+- **security_level**: Overall security level assessment
+- **configuration_summary**: Complete configuration overview
+
+### Usage Pattern
+```ruby
+pab_ref = aws_s3_bucket_public_access_block(:secure_bucket, {...})
+
+if pab_ref.computed[:fully_blocked]
+  puts "Maximum security: all public access blocked"
+elsif pab_ref.computed[:partially_blocked]
+  puts "Partial security: #{pab_ref.computed[:blocked_settings_count]} restrictions enabled"
+else
+  puts "Warning: bucket allows public access"
+end
+
+puts "Security level: #{pab_ref.computed[:security_level]}"
+```
+
+## Implementation Patterns
+
+### Maximum Security (Recommended)
+```ruby
+max_security = aws_s3_bucket_public_access_block(:max_security, {
+  bucket: "private-corporate-data",
+  block_public_acls: true,
+  block_public_policy: true,
+  ignore_public_acls: true,
+  restrict_public_buckets: true
+})
+# Results in: fully_blocked = true, security_level = "secure"
+```
+
+### Website Hosting (Controlled Public Access)
+```ruby
+website_hosting = aws_s3_bucket_public_access_block(:website_hosting, {
+  bucket: "my-static-website",
+  block_public_acls: true,      # Block direct ACL access
+  ignore_public_acls: true,     # Ignore any existing public ACLs
+  block_public_policy: false,   # Allow public read policies
+  restrict_public_buckets: false
+})
+# Results in: partially_blocked = true, security_level = "restricted"
+```
+
+### Legacy Migration (Gradual Security)
+```ruby
+migration_step1 = aws_s3_bucket_public_access_block(:migration_step1, {
+  bucket: "legacy-public-bucket",
+  block_public_acls: true,      # Stop new public ACLs
+  ignore_public_acls: false,    # Don't break existing access yet
+  block_public_policy: false,   # Allow existing policies
+  restrict_public_buckets: false
+})
+# Results in: partially_blocked = true, allows controlled migration
+```
+
+### Open Access (Use with Extreme Caution)
+```ruby
+open_access = aws_s3_bucket_public_access_block(:open_bucket, {
+  bucket: "truly-public-bucket",
+  block_public_acls: false,
+  block_public_policy: false,
+  ignore_public_acls: false,
+  restrict_public_buckets: false
+})
+# Results in: allows_public_access = true, security_level = "open"
+```
+
+## Security Strategies
+
+### Defense in Depth
+```ruby
+template :defense_in_depth do
+  # Layer 1: Public Access Block (maximum security)
+  pab = aws_s3_bucket_public_access_block(:layered_security, {
+    bucket: "sensitive-corporate-data",
+    block_public_acls: true,
+    block_public_policy: true,
+    ignore_public_acls: true,
+    restrict_public_buckets: true
+  })
+
+  # Layer 2: Explicit Deny Policy
+  aws_s3_bucket_policy(:explicit_deny, {
+    bucket: "sensitive-corporate-data",
+    policy: JSON.generate({
+      Version: "2012-10-17",
+      Statement: [{
+        Sid: "ExplicitDenyPublicAccess",
+        Effect: "Deny",
+        Principal: "*",
+        Action: "s3:*",
+        Resource: [
+          "arn:aws:s3:::sensitive-corporate-data",
+          "arn:aws:s3:::sensitive-corporate-data/*"
+        ],
+        Condition: {
+          StringNotEquals: {
+            "aws:PrincipalAccount": "123456789012"
+          }
+        }
+      }]
+    })
+  })
+
+  # Layer 3: Encryption
+  aws_s3_bucket_encryption(:layered_encryption, {
+    bucket: "sensitive-corporate-data",
+    server_side_encryption_configuration: {
+      rule: [{
+        apply_server_side_encryption_by_default: {
+          sse_algorithm: "aws:kms",
+          kms_master_key_id: "alias/sensitive-data-key"
+        },
+        bucket_key_enabled: true
+      }]
+    }
+  })
+
+  output :security_analysis do
+    value {
+      public_access_blocked: pab.computed[:fully_blocked],
+      security_level: pab.computed[:security_level],
+      explicit_policy_deny: true,
+      encrypted: true,
+      defense_layers: 3
+    }
+  end
+end
+```
+
+### Graduated Security Migration
+```ruby
+template :security_migration do
+  bucket_name = "legacy-bucket-to-secure"
+
+  # Phase 1: Block new public ACLs
+  phase1 = aws_s3_bucket_public_access_block(:phase1, {
+    bucket: bucket_name,
+    block_public_acls: true
+    # Leave other settings unchanged
+  })
+
+  # Phase 2: Ignore existing public ACLs (separate deployment)
+  # phase2 = aws_s3_bucket_public_access_block(:phase2, {
+  #   bucket: bucket_name,
+  #   block_public_acls: true,
+  #   ignore_public_acls: true
+  # })
+
+  # Phase 3: Block public policies (separate deployment)
+  # phase3 = aws_s3_bucket_public_access_block(:phase3, {
+  #   bucket: bucket_name,
+  #   block_public_acls: true,
+  #   ignore_public_acls: true,
+  #   block_public_policy: true
+  # })
+
+  # Phase 4: Full lockdown (final deployment)
+  # final = aws_s3_bucket_public_access_block(:final, {
+  #   bucket: bucket_name,
+  #   block_public_acls: true,
+  #   ignore_public_acls: true,
+  #   block_public_policy: true,
+  #   restrict_public_buckets: true
+  # })
+
+  output :migration_status do
+    value {
+      current_phase: "block_new_public_acls",
+      security_level: phase1.computed[:security_level],
+      next_phase: "ignore_existing_public_acls",
+      final_goal: "fully_blocked"
+    }
+  end
+end
+```
+
+## Integration Points
+
+### With CloudFront Distributions
+```ruby
+# CloudFront origin bucket should be fully private
+cloudfront_origin_pab = aws_s3_bucket_public_access_block(:cloudfront_origin, {
+  bucket: "cloudfront-origin-bucket",
+  block_public_acls: true,
+  block_public_policy: true,
+  ignore_public_acls: true,
+  restrict_public_buckets: true
+})
+
+# CloudFront accesses via OAC, not public policies
+aws_s3_bucket_policy(:cloudfront_only, {
+  bucket: "cloudfront-origin-bucket",
+  policy: JSON.generate({
+    Version: "2012-10-17",
+    Statement: [{
+      Effect: "Allow",
+      Principal: { Service: "cloudfront.amazonaws.com" },
+      Action: "s3:GetObject",
+      Resource: "arn:aws:s3:::cloudfront-origin-bucket/*",
+      Condition: {
+        StringEquals: {
+          "AWS:SourceArn": "arn:aws:cloudfront::123456789012:distribution/EXAMPLE"
+        }
+      }
+    }]
+  })
+})
+```
+
+### With Application Load Balancer Access Logs
+```ruby
+# ALB access logs bucket needs specific public access configuration
+alb_logs_pab = aws_s3_bucket_public_access_block(:alb_logs, {
+  bucket: "alb-access-logs-bucket",
+  block_public_acls: true,      # Block public ACLs
+  ignore_public_acls: true,     # Ignore public ACLs
+  block_public_policy: false,   # Allow ALB service policy
+  restrict_public_buckets: false
+})
+
+# ALB service needs specific policy permissions
+aws_s3_bucket_policy(:alb_logs_policy, {
+  bucket: "alb-access-logs-bucket",
+  policy: JSON.generate({
+    Version: "2012-10-17",
+    Statement: [{
+      Effect: "Allow",
+      Principal: { AWS: "arn:aws:iam::elasticloadbalancing:root" },
+      Action: "s3:PutObject",
+      Resource: "arn:aws:s3:::alb-access-logs-bucket/alb-logs/*"
+    }]
+  })
+})
+```
+
+### With Cross-Account Access
+```ruby
+# Cross-account shared bucket with controlled access
+cross_account_pab = aws_s3_bucket_public_access_block(:cross_account, {
+  bucket: "cross-account-shared-bucket",
+  expected_bucket_owner: "123456789012",
+  block_public_acls: true,
+  ignore_public_acls: true,
+  block_public_policy: false,   # Allow cross-account policies
+  restrict_public_buckets: true # Restrict to account access only
+})
+
+aws_s3_bucket_policy(:cross_account_policy, {
+  bucket: "cross-account-shared-bucket",
+  policy: JSON.generate({
+    Version: "2012-10-17",
+    Statement: [{
+      Effect: "Allow",
+      Principal: { AWS: "arn:aws:iam::987654321098:root" },
+      Action: ["s3:GetObject", "s3:PutObject"],
+      Resource: "arn:aws:s3:::cross-account-shared-bucket/shared/*"
+    }]
+  })
+})
+```
+
+## Best Practices Implementation
+
+### Security by Default
+```ruby
+# Default to maximum security for new buckets
+def secure_bucket_template(bucket_name)
+  aws_s3_bucket_public_access_block(:"#{bucket_name}_pab", {
+    bucket: bucket_name,
+    block_public_acls: true,
+    block_public_policy: true,
+    ignore_public_acls: true,
+    restrict_public_buckets: true
+  })
+end
+```
+
+### Monitoring and Compliance
+```ruby
+template :compliance_monitoring do
+  buckets = ["app-data", "user-uploads", "backup-files"]
+  
+  bucket_security_status = buckets.map do |bucket_name|
+    pab = aws_s3_bucket_public_access_block(:"#{bucket_name}_pab", {
+      bucket: bucket_name,
+      block_public_acls: true,
+      block_public_policy: true,
+      ignore_public_acls: true,
+      restrict_public_buckets: true
+    })
+    
+    {
+      bucket: bucket_name,
+      fully_blocked: pab.computed[:fully_blocked],
+      security_level: pab.computed[:security_level],
+      configuration: pab.computed[:configuration_summary]
+    }
+  end
+
+  output :security_compliance_report do
+    value bucket_security_status
+    description "Security compliance status for all S3 buckets"
+  end
+end
+```
+
+### Exception Documentation
+```ruby
+# Document any exceptions to security policy
+website_exception = aws_s3_bucket_public_access_block(:website_exception, {
+  bucket: "company-public-website",
+  block_public_acls: true,
+  ignore_public_acls: true,
+  block_public_policy: false,   # EXCEPTION: Required for website hosting
+  restrict_public_buckets: false
+})
+
+output :security_exceptions do
+  value {
+    bucket: "company-public-website",
+    exception_reason: "Static website hosting requires public read access",
+    risk_mitigation: [
+      "Public access limited to read-only via bucket policy",
+      "No sensitive data stored in website bucket",
+      "Regular security reviews scheduled"
+    ],
+    approved_by: "Security Team",
+    review_date: "2024-12-31"
+  }
+  description "Documented exceptions to standard security policy"
+end
+```
+
+## Error Handling
+
+### Multi-Account Scenarios
+```ruby
+# Prevent cross-account access issues
+safe_cross_account = aws_s3_bucket_public_access_block(:safe_cross_account, {
+  bucket: "shared-bucket",
+  expected_bucket_owner: "123456789012",  # Prevents accidents
+  block_public_acls: true,
+  block_public_policy: true,
+  ignore_public_acls: true,
+  restrict_public_buckets: true
+})
+```
+
+### Configuration Conflicts
+```ruby
+# Be explicit about settings to avoid defaults
+explicit_config = aws_s3_bucket_public_access_block(:explicit, {
+  bucket: "my-bucket",
+  block_public_acls: true,
+  block_public_policy: true,
+  ignore_public_acls: true,
+  restrict_public_buckets: true
+  # All settings explicit - no surprises
+})
+```
+
+## Testing Considerations
+
+### Security Testing
+- Test that maximum security blocks all public access attempts
+- Test website hosting configuration allows intended access only
+- Test cross-account scenarios work correctly
+- Verify computed properties accurately reflect security state
+
+### Migration Testing  
+- Test gradual migration doesn't break existing applications
+- Test that each phase achieves intended security improvements
+- Verify rollback scenarios work if needed
+
+### Integration Testing
+- Test interaction with bucket policies
+- Test CloudFront integration with private buckets
+- Test service-specific access patterns (ALB logs, etc.)
+- Test cross-account sharing scenarios
+
+### Compliance Testing
+- Verify security levels meet compliance requirements
+- Test documentation and exception tracking
+- Verify monitoring and alerting integration
+- Test audit trail completeness

data/lib/pangea/resources/aws_s3_bucket_public_access_block/resource.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+# Copyright 2025 The Pangea Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require 'pangea/resources/base'
+require 'pangea/resources/reference'
+require 'pangea/resources/aws_s3_bucket_public_access_block/types'
+require 'pangea/resource_registry'
+
+module Pangea
+  module Resources
+    module AWS
+      # Create an AWS S3 Bucket Public Access Block configuration with type-safe attributes
+      #
+      # @param name [Symbol] The resource name
+      # @param attributes [Hash] S3 bucket public access block attributes
+      # @return [ResourceReference] Reference object with outputs and computed properties
+      def aws_s3_bucket_public_access_block(name, attributes = {})
+        # Validate attributes using dry-struct
+        pab_attrs = Types::S3BucketPublicAccessBlockAttributes.new(attributes)
+        
+        # Generate terraform resource block via terraform-synthesizer
+        resource(:aws_s3_bucket_public_access_block, name) do
+          # Set bucket name
+          bucket pab_attrs.bucket
+          
+          # Set expected bucket owner if provided
+          expected_bucket_owner pab_attrs.expected_bucket_owner if pab_attrs.expected_bucket_owner
+          
+          # Configure public access block settings
+          block_public_acls pab_attrs.block_public_acls if pab_attrs.block_public_acls
+          block_public_policy pab_attrs.block_public_policy if pab_attrs.block_public_policy
+          ignore_public_acls pab_attrs.ignore_public_acls if pab_attrs.ignore_public_acls
+          restrict_public_buckets pab_attrs.restrict_public_buckets if pab_attrs.restrict_public_buckets
+        end
+        
+        # Return resource reference with available outputs
+        ResourceReference.new(
+          type: 'aws_s3_bucket_public_access_block',
+          name: name,
+          resource_attributes: pab_attrs.to_h,
+          outputs: {
+            id: "${aws_s3_bucket_public_access_block.#{name}.id}",
+            bucket: "${aws_s3_bucket_public_access_block.#{name}.bucket}",
+            block_public_acls: "${aws_s3_bucket_public_access_block.#{name}.block_public_acls}",
+            block_public_policy: "${aws_s3_bucket_public_access_block.#{name}.block_public_policy}",
+            ignore_public_acls: "${aws_s3_bucket_public_access_block.#{name}.ignore_public_acls}",
+            restrict_public_buckets: "${aws_s3_bucket_public_access_block.#{name}.restrict_public_buckets}"
+          },
+          computed: {
+            fully_blocked: pab_attrs.fully_blocked?,
+            partially_blocked: pab_attrs.partially_blocked?,
+            allows_public_access: pab_attrs.allows_public_access?,
+            blocked_settings_count: pab_attrs.blocked_settings_count,
+            security_level: pab_attrs.security_level,
+            configuration_summary: pab_attrs.configuration_summary
+          }
+        )
+      end
+    end
+  end
+end
+
+# Auto-register this module when it's loaded
+Pangea::ResourceRegistry.register(:aws, Pangea::Resources::AWS)

data/lib/pangea/resources/aws_s3_bucket_public_access_block/types.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+# Copyright 2025 The Pangea Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require 'dry-struct'
+require 'pangea/resources/types'
+
+module Pangea
+  module Resources
+    module AWS
+      module Types
+      # Type-safe attributes for AWS S3 Bucket Public Access Block resources
+      class S3BucketPublicAccessBlockAttributes < Dry::Struct
+        transform_keys(&:to_sym)
+
+        # Bucket name (required)
+        attribute :bucket, Resources::Types::String
+
+        # Block public ACLs (optional, default false)
+        attribute? :block_public_acls, Resources::Types::Bool.optional
+
+        # Block public policy (optional, default false)
+        attribute? :block_public_policy, Resources::Types::Bool.optional
+
+        # Ignore public ACLs (optional, default false)
+        attribute? :ignore_public_acls, Resources::Types::Bool.optional
+
+        # Restrict public buckets (optional, default false)
+        attribute? :restrict_public_buckets, Resources::Types::Bool.optional
+
+        # Expected bucket owner for multi-account scenarios
+        attribute? :expected_bucket_owner, Resources::Types::String.optional
+
+        # Helper methods
+        def fully_blocked?
+          block_public_acls == true &&
+            block_public_policy == true &&
+            ignore_public_acls == true &&
+            restrict_public_buckets == true
+        end
+
+        def partially_blocked?
+          [block_public_acls, block_public_policy, ignore_public_acls, restrict_public_buckets].any? { |setting| setting == true }
+        end
+
+        def allows_public_access?
+          !partially_blocked?
+        end
+
+        def blocked_settings_count
+          [block_public_acls, block_public_policy, ignore_public_acls, restrict_public_buckets].count { |setting| setting == true }
+        end
+
+        def security_level
+          case blocked_settings_count
+          when 0
+            'open'
+          when 1..3
+            'restricted'
+          when 4
+            'secure'
+          else
+            'unknown'
+          end
+        end
+
+        def configuration_summary
+          {
+            block_public_acls: block_public_acls || false,
+            block_public_policy: block_public_policy || false,
+            ignore_public_acls: ignore_public_acls || false,
+            restrict_public_buckets: restrict_public_buckets || false
+          }
+        end
+      end
+    end
+      end
+    end
+  end
+end