pangea 0.0.42 → 0.0.45

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

@@ -0,0 +1,504 @@
+# AWS EFS Access Point Implementation
+
+## Overview
+
+The AWS EFS Access Point resource provides application-specific entry points to EFS file systems with comprehensive POSIX user, group, and directory access controls. This implementation includes sophisticated validation for path security, permission management, and operational best practices.
+
+## Implementation Architecture
+
+### Type System
+
+The implementation uses Pangea's type-safe resource pattern with extensive POSIX and security validation:
+
+```ruby
+class EfsAccessPointAttributes < Dry::Struct
+  # Core configuration
+  attribute :file_system_id, Resources::Types::String
+  
+  # POSIX access control
+  attribute :posix_user, Resources::Types::EfsPosixUser.optional
+  
+  # Directory configuration
+  attribute :root_directory, Resources::Types::EfsRootDirectory.optional
+  
+  # Resource management
+  attribute :tags, Resources::Types::AwsTags.default({}.freeze)
+```
+
+### Advanced Validation System
+
+The type system includes comprehensive validation for security and operational correctness:
+
+1. **Path Security Validation**: Prevents directory traversal and invalid path constructions
+2. **POSIX Permission Validation**: Ensures proper octal format and security constraints
+3. **User/Group ID Management**: Validates UID/GID ranges and secondary group limits
+4. **Security Assessment**: Automated security analysis of access point configurations
+
+## Key Validation Features
+
+### Path Security Validation
+
+```ruby
+def self.new(attributes)
+  if attrs[:root_directory] && attrs[:root_directory][:path]
+    path = attrs[:root_directory][:path]
+    
+    # Comprehensive path validation
+    unless path.start_with?('/')
+      raise Dry::Struct::Error, "root_directory path must start with '/'"
+    end
+    
+    # Prevent directory traversal attacks
+    if path.include?('//')
+      raise Dry::Struct::Error, "root_directory path cannot contain consecutive slashes"
+    end
+    
+    # Validate individual path components
+    path_components = path.split('/').reject(&:empty?)
+    path_components.each do |component|
+      if component == '.' || component == '..'
+        raise Dry::Struct::Error, "root_directory path cannot contain '.' or '..' components"
+      end
+    end
+  end
+end
+```
+
+### POSIX Permissions Validation
+
+```ruby
+if attrs[:root_directory][:creation_info][:permissions]
+  perms = attrs[:root_directory][:creation_info][:permissions]
+  unless perms.match?(/\A[0-7]{3,4}\z/)
+    raise Dry::Struct::Error, "permissions must be 3-4 digit octal format"
+  end
+  
+  # Validate permission range
+  perm_int = perms.to_i(8)
+  if perm_int > 0o7777
+    raise Dry::Struct::Error, "permissions cannot exceed 0777"
+  end
+end
+```
+
+### Security Group and User Validation
+
+```ruby
+# Validate secondary group limits (AWS limit: 16 groups)
+if posix[:secondary_gids] && posix[:secondary_gids].length > 16
+  raise Dry::Struct::Error, "secondary_gids cannot exceed 16 groups"
+end
+```
+
+## Computed Security Properties
+
+### Security Assessment System
+
+The implementation includes an automated security assessment system:
+
+```ruby
+def security_assessment
+  issues = []
+  warnings = []
+  
+  # Check for root user usage
+  if is_root_user?
+    warnings << "Using root user (UID 0) - consider using non-privileged user"
+  end
+  
+  # Check for overly permissive permissions
+  if has_creation_info?
+    perm_int = root_directory[:creation_info][:permissions].to_i(8)
+    
+    if (perm_int & 0o002) != 0
+      issues << "Directory permissions are world-writable - security risk"
+    end
+    
+    if sensitive_path? && (perm_int & 0o004) != 0
+      warnings << "World-readable permissions on sensitive path"
+    end
+  end
+  
+  { issues: issues, warnings: warnings, secure: issues.empty? }
+end
+```
+
+### Operational Analysis
+
+```ruby
+def effective_uid
+  posix_user&.dig(:uid) || 1000  # Default to non-root
+end
+
+def effective_gid
+  posix_user&.dig(:gid) || 1000  # Default to non-root
+end
+
+def effective_root_path
+  root_directory&.dig(:path) || "/"
+end
+
+def is_root_user?
+  effective_uid == 0
+end
+```
+
+## Resource Function Implementation
+
+### Configuration Processing
+
+```ruby
+def aws_efs_access_point(name, attributes = {})
+  validated_attrs = AWS::Types::EfsAccessPointAttributes.new(attributes)
+  
+  resource_attributes = {
+    file_system_id: validated_attrs.file_system_id,
+    tags: validated_attrs.tags
+  }
+  
+  # Process POSIX user configuration
+  if validated_attrs.posix_user
+    resource_attributes[:posix_user] = [validated_attrs.posix_user]
+  end
+  
+  # Process root directory configuration
+  if validated_attrs.root_directory
+    root_dir = validated_attrs.root_directory.dup
+    root_dir[:path] = "/" unless root_dir[:path]  # Default to root
+    resource_attributes[:root_directory] = [root_dir]
+  end
+end
+```
+
+### Terraform Resource Generation
+
+The resource function creates properly structured Terraform configuration for EFS access points with all validation and security controls in place.
+
+## Resource Outputs
+
+### Core Identifiers
+- `id`: Access point unique identifier for mounting and IAM policies
+- `arn`: Full ARN for cross-service references and resource policies
+- `file_system_arn`: Associated EFS file system ARN
+
+### Configuration Details
+- `root_directory_path`: Effective root directory path for verification
+- `posix_user_uid`, `posix_user_gid`: POSIX user configuration confirmation
+- `owner_id`: AWS account ownership information
+
+### Integration Outputs
+- `root_directory_arn`: Directory-specific ARN for fine-grained IAM policies
+
+## Production Integration Patterns
+
+### Container Platform Integration
+
+```ruby
+# ECS task definition integration
+container_definition = {
+  name: "web-app",
+  image: "nginx:latest",
+  mountPoints: [{
+    sourceVolume: "efs-storage",
+    containerPath: "/var/www/html",
+    readOnly: false
+  }]
+}
+
+task_definition_volume = {
+  name: "efs-storage",
+  efsVolumeConfiguration: {
+    fileSystemId: efs_ref.id,
+    accessPoint: access_point_ref.id,  # Use access point for isolation
+    transitEncryption: "ENABLED",
+    authorizationConfig: {
+      iam: "ENABLED"
+    }
+  }
+}
+```
+
+### Lambda Function Integration
+
+```ruby
+# Lambda function with EFS access point
+lambda_function = {
+  function_name: "data-processor",
+  runtime: "python3.9",
+  vpc_config: {
+    subnet_ids: [private_subnet_ref.id],
+    security_group_ids: [lambda_sg_ref.id]
+  },
+  file_system_configs: [{
+    arn: access_point_ref.arn,  # Use access point ARN
+    local_mount_path: "/mnt/efs"
+  }]
+}
+```
+
+### Multi-Tenant Architecture Integration
+
+```ruby
+# Tenant-specific access points with IAM integration
+tenants.each do |tenant|
+  access_point = aws_efs_access_point(:"#{tenant[:name]}_access", {
+    file_system_id: shared_efs.id,
+    posix_user: {
+      uid: tenant[:uid],
+      gid: tenant[:gid]
+    },
+    root_directory: {
+      path: "/tenants/#{tenant[:name]}",
+      creation_info: {
+        owner_uid: tenant[:uid],
+        owner_gid: tenant[:gid],
+        permissions: "750"
+      }
+    }
+  })
+  
+  # Tenant-specific IAM policy
+  aws_iam_policy(:"#{tenant[:name]}_efs_policy", {
+    name: "#{tenant[:name]}-efs-access",
+    policy: {
+      Version: "2012-10-17",
+      Statement: [{
+        Effect: "Allow",
+        Action: ["elasticfilesystem:ClientMount", "elasticfilesystem:ClientWrite"],
+        Resource: access_point.arn,
+        Condition: {
+          StringEquals: {
+            "elasticfilesystem:AccessPointArn": access_point.arn
+          }
+        }
+      }]
+    }
+  })
+end
+```
+
+## Advanced Usage Patterns
+
+### Hierarchical Access Control
+
+```ruby
+# Application with multiple access levels
+application_efs = aws_efs_file_system(:app_efs, { ... })
+
+# Admin access point (full file system access)
+admin_access = aws_efs_access_point(:admin_access, {
+  file_system_id: application_efs.id,
+  posix_user: {
+    uid: 0,  # Admin privileges
+    gid: 0
+  },
+  root_directory: {
+    path: "/",  # Full file system access
+    creation_info: {
+      owner_uid: 0,
+      owner_gid: 0,
+      permissions: "755"
+    }
+  }
+})
+
+# Application access point (restricted to app directory)
+app_access = aws_efs_access_point(:app_access, {
+  file_system_id: application_efs.id,
+  posix_user: {
+    uid: 1000,
+    gid: 1000
+  },
+  root_directory: {
+    path: "/app",
+    creation_info: {
+      owner_uid: 1000,
+      owner_gid: 1000,
+      permissions: "750"
+    }
+  }
+})
+
+# Read-only access point for monitoring
+readonly_access = aws_efs_access_point(:readonly_access, {
+  file_system_id: application_efs.id,
+  posix_user: {
+    uid: 2000,
+    gid: 2000
+  },
+  root_directory: {
+    path: "/logs",
+    creation_info: {
+      owner_uid: 2000,
+      owner_gid: 2000,
+      permissions: "644"  # Read-only for group/others
+    }
+  }
+})
+```
+
+### Dynamic Access Point Creation
+
+```ruby
+# Service-oriented access point creation
+services = [
+  { name: "web", uid: 1001, path: "/web", ports: [80, 443] },
+  { name: "api", uid: 1002, path: "/api", ports: [3000] },
+  { name: "worker", uid: 1003, path: "/worker", ports: [] }
+]
+
+services.each do |service|
+  aws_efs_access_point(:"#{service[:name]}_access", {
+    file_system_id: shared_efs.id,
+    posix_user: {
+      uid: service[:uid],
+      gid: 1000,  # Shared application group
+      secondary_gids: service[:ports].map { |port| port + 2000 }  # Port-based groups
+    },
+    root_directory: {
+      path: service[:path],
+      creation_info: {
+        owner_uid: service[:uid],
+        owner_gid: 1000,
+        permissions: "755"
+      }
+    },
+    tags: {
+      Name: "#{service[:name].titleize} Service Access",
+      Service: service[:name],
+      Ports: service[:ports].join(",")
+    }
+  })
+end
+```
+
+## Error Handling and Validation
+
+### Path Validation Errors
+
+```ruby
+# These will raise validation errors:
+aws_efs_access_point(:bad_path, {
+  file_system_id: efs_ref.id,
+  root_directory: {
+    path: "relative/path"  # Must start with /
+  }
+})
+
+aws_efs_access_point(:traversal_attack, {
+  file_system_id: efs_ref.id,
+  root_directory: {
+    path: "/app/../../../etc"  # Contains ..
+  }
+})
+```
+
+### Permission Validation Errors
+
+```ruby
+# Invalid permission format
+aws_efs_access_point(:bad_perms, {
+  file_system_id: efs_ref.id,
+  root_directory: {
+    creation_info: {
+      permissions: "999"  # Invalid octal
+    }
+  }
+})
+
+# Overly permissive permissions
+aws_efs_access_point(:world_writable, {
+  file_system_id: efs_ref.id,
+  root_directory: {
+    creation_info: {
+      permissions: "777"  # Will trigger security warning
+    }
+  }
+})
+```
+
+## Testing and Validation
+
+### Security Assessment Testing
+
+```ruby
+# Test security assessment functionality
+access_point_attrs = AWS::Types::EfsAccessPointAttributes.new({
+  file_system_id: "fs-12345678",
+  posix_user: { uid: 0, gid: 0 },  # Root user
+  root_directory: {
+    path: "/",
+    creation_info: {
+      owner_uid: 0,
+      owner_gid: 0,
+      permissions: "777"  # World writable
+    }
+  }
+})
+
+assessment = access_point_attrs.security_assessment
+expect(assessment[:secure]).to be false
+expect(assessment[:issues]).to include("Directory permissions are world-writable")
+expect(assessment[:warnings]).to include("Using root user")
+```
+
+### Path Validation Testing
+
+```ruby
+# Test various path configurations
+valid_paths = ["/", "/app", "/data/processed", "/home/user"]
+invalid_paths = ["relative", "/app/", "/app//data", "/app/../data"]
+
+valid_paths.each do |path|
+  expect {
+    AWS::Types::EfsAccessPointAttributes.new({
+      file_system_id: "fs-12345678",
+      root_directory: { path: path }
+    })
+  }.not_to raise_error
+end
+
+invalid_paths.each do |path|
+  expect {
+    AWS::Types::EfsAccessPointAttributes.new({
+      file_system_id: "fs-12345678",
+      root_directory: { path: path }
+    })
+  }.to raise_error(Dry::Struct::Error)
+end
+```
+
+## AWS Service Integration
+
+The EFS Access Point resource integrates deeply with multiple AWS services:
+
+### IAM Integration
+- **Resource Policies**: Access points can have specific resource-based policies
+- **Access Point ARNs**: Used in IAM condition blocks for fine-grained control
+- **Cross-Account Access**: Supports cross-account access through resource policies
+
+### Container Services
+- **ECS**: Native support for access point mounting in task definitions
+- **EKS**: CSI driver integration for Kubernetes persistent volumes
+- **Fargate**: Serverless container access to persistent storage
+
+### Serverless Integration
+- **Lambda**: VPC-based Lambda functions can mount access points
+- **API Gateway**: Indirect access through Lambda function integration
+- **Step Functions**: State machine workflows with persistent storage
+
+## Operational Excellence
+
+### Monitoring and Observability
+
+- **CloudWatch Metrics**: Access point-specific performance metrics
+- **VPC Flow Logs**: Network traffic analysis for access point usage
+- **CloudTrail**: API-level access and configuration change tracking
+- **EFS Insights**: Performance analysis and optimization recommendations
+
+### Security and Compliance
+
+- **Least Privilege**: Automatic enforcement of POSIX permissions
+- **Directory Isolation**: Root directory confinement prevents cross-contamination
+- **Audit Trail**: Complete audit trail of access point configurations and changes
+- **Compliance**: Supports various compliance frameworks through access controls

data/lib/pangea/resources/aws_efs_access_point/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/aws_efs_access_point/types'
+require 'pangea/resource_registry'
+
+module Pangea
+  module Resources
+    module AWS
+      # Creates an AWS EFS Access Point for application-specific file system access
+      # 
+      # @param name [Symbol] The resource name
+      # @param attributes [Hash] Access point configuration
+      # @return [ResourceReference] Reference to the created access point
+      def aws_efs_access_point(name, attributes = {})
+        validated_attrs = AWS::Types::Types::EfsAccessPointAttributes.new(attributes)
+        
+        resource_attributes = {
+          file_system_id: validated_attrs.file_system_id,
+          tags: validated_attrs.tags
+        }
+        
+        # Add POSIX user configuration if specified
+        if validated_attrs.posix_user
+          resource_attributes[:posix_user] = [validated_attrs.posix_user]
+        end
+        
+        # Add root directory configuration if specified
+        if validated_attrs.root_directory
+          root_dir = validated_attrs.root_directory.dup
+          
+          # Ensure path defaults to "/"
+          root_dir[:path] = "/" unless root_dir[:path]
+          
+          resource_attributes[:root_directory] = [root_dir]
+        end
+        
+        resource(:aws_efs_access_point, name, resource_attributes)
+        
+        ResourceReference.new(
+          type: :aws_efs_access_point,
+          name: name,
+          attributes: validated_attrs,
+          outputs: {
+            id: "${aws_efs_access_point.#{name}.id}",
+            arn: "${aws_efs_access_point.#{name}.arn}",
+            file_system_arn: "${aws_efs_access_point.#{name}.file_system_arn}",
+            file_system_id: "${aws_efs_access_point.#{name}.file_system_id}",
+            owner_id: "${aws_efs_access_point.#{name}.owner_id}",
+            root_directory_arn: "${aws_efs_access_point.#{name}.root_directory_arn}",
+            root_directory_path: "${aws_efs_access_point.#{name}.root_directory[0].path}",
+            posix_user_uid: "${aws_efs_access_point.#{name}.posix_user[0].uid}",
+            posix_user_gid: "${aws_efs_access_point.#{name}.posix_user[0].gid}",
+            tags_all: "${aws_efs_access_point.#{name}.tags_all}"
+          }
+        )
+      end
+    end
+  end
+end
+
+# Auto-register this module when it's loaded
+Pangea::ResourceRegistry.register(:aws, Pangea::Resources::AWS)