pangea 0.0.45 → 0.0.47

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

@@ -1,351 +0,0 @@
-# AWS IAM Group Implementation
-
-## Overview
-
-This implementation provides type-safe AWS IAM group creation with comprehensive organizational pattern support, automatic group classification, naming convention analysis, and security risk assessment for enterprise user management.
-
-## Architecture
-
-### Type Safety & Validation
-- **dry-struct validation** for group name and path attributes
-- **Name format validation** (128 chars max, alphanumeric + special chars)
-- **Path format validation** (starts with /, valid chars, 512 char max)
-- **Security best practice validation** with automated warnings
-
-### Group Classification System
-- **Automatic group categorization** based on naming patterns
-- **Purpose-based classification** (administrative, developer, operations, etc.)
-- **Risk assessment** based on group type and naming
-- **Organizational structure detection** from paths and names
-
-### Organizational Pattern Support
-- **Team-based group patterns** for development organizations
-- **Environment-specific groups** for deployment management
-- **Department-aligned groups** for business function access
-- **Service-oriented groups** for microservices architectures
-- **Cross-functional team support** for project-based access
-
-## Key Components
-
-### 1. IamGroupAttributes Class
-```ruby
-class IamGroupAttributes < Dry::Struct
-  attribute :name, Types::String                    # Group name (required)
-  attribute :path, Types::String.default("/")       # Group path
-end
-```
-
-### 2. Group Classification Methods
-
-#### Purpose Detection
-```ruby
-def administrative_group?
-  name.downcase.include?('admin') || 
-  name.downcase.include?('root') || 
-  name.downcase.include?('super') ||
-  name.downcase.include?('power')
-end
-
-def developer_group?
-  name.downcase.include?('dev') || 
-  name.downcase.include?('engineer') ||
-  name.downcase.include?('programmer')
-end
-
-def operations_group?
-  name.downcase.include?('ops') || 
-  name.downcase.include?('sre') ||
-  name.downcase.include?('infrastructure') ||
-  name.downcase.include?('platform')
-end
-```
-
-#### Risk Assessment
-```ruby
-def security_risk_level
-  case group_category
-  when :administrative
-    :high
-  when :operations
-    :high
-  when :developer
-    :medium
-  when :readonly
-    :low
-  else
-    :medium
-  end
-end
-```
-
-### 3. Group Patterns Module
-
-#### Organizational Patterns
-```ruby
-module GroupPatterns
-  def self.development_team_group(team_name, department = "engineering")
-    {
-      name: "#{department}-#{team_name}-developers",
-      path: "/teams/#{department}/#{team_name}/"
-    }
-  end
-
-  def self.environment_access_group(environment, access_level = "deploy")
-    {
-      name: "#{environment}-#{access_level}",
-      path: "/environments/#{environment}/"
-    }
-  end
-end
-```
-
-### 4. Naming Convention Analysis
-
-#### Convention Scoring
-```ruby
-def naming_convention_score
-  score = 0
-  
-  # Points for including environment
-  score += 20 if environment_group?
-  
-  # Points for including department/function
-  score += 20 if department_group? || developer_group? || operations_group?
-  
-  # Points for following hyphen convention
-  score += 20 if follows_naming_convention?
-  
-  # Points for appropriate length
-  score += 20 if name.length.between?(5, 30)
-  
-  # Points for organizational path
-  score += 20 if organizational_path?
-  
-  score
-end
-```
-
-## Implementation Decisions
-
-### 1. Pattern-Based Organization
-- **Pre-defined organizational patterns** for common structures
-- **Team-based patterns** for development organizations
-- **Environment-specific patterns** for deployment workflows
-- **Service-oriented patterns** for microservices architectures
-
-### 2. Automatic Classification
-- **Purpose-based categorization** using name analysis
-- **Risk level assessment** based on group type
-- **Access level suggestions** for policy attachment
-- **Naming convention scoring** for compliance
-
-### 3. Security-First Approach
-- **Risk assessment** for all group configurations
-- **Security warnings** for potentially problematic configurations
-- **Best practice guidance** through computed properties
-- **Organizational structure enforcement** through validation
-
-## Usage Patterns
-
-### 1. Development Team Groups
-```ruby
-aws_iam_group(:frontend_team,
-  GroupPatterns.development_team_group("frontend", "engineering")
-)
-```
-
-### 2. Environment-Based Groups
-```ruby
-aws_iam_group(:prod_deployers,
-  GroupPatterns.environment_access_group("production", "deploy")
-)
-```
-
-### 3. Service-Specific Groups
-```ruby
-aws_iam_group(:api_owners,
-  GroupPatterns.service_group("user-api", "owner")
-)
-```
-
-### 4. Administrative Groups
-```ruby
-aws_iam_group(:infra_admins,
-  GroupPatterns.admin_group("infrastructure", "platform")
-)
-```
-
-## Computed Properties Analysis
-
-The implementation provides comprehensive computed properties for group analysis:
-
-### Group Classification
-- `group_category`: Primary group categorization (:administrative, :developer, :operations, etc.)
-- `administrative_group`: Boolean flag for admin groups
-- `developer_group`: Boolean flag for development groups
-- `operations_group`: Boolean flag for operations groups
-- `readonly_group`: Boolean flag for read-only groups
-
-### Organizational Analysis
-- `department_group`: Boolean for department-specific groups
-- `environment_group`: Boolean for environment-specific groups
-- `organizational_path`: Boolean for structured path usage
-- `organizational_unit`: Extracted organizational unit from path
-
-### Security Analysis
-- `security_risk_level`: Risk assessment (:low, :medium, :high)
-- `suggested_access_level`: Recommended access level for the group
-
-### Naming Analysis
-- `follows_naming_convention`: Boolean for naming best practices
-- `naming_convention_score`: Numeric score (0-100) for naming quality
-- `extracted_environment`: Environment extracted from group name
-- `extracted_department`: Department extracted from group name
-
-## Group Categories and Access Patterns
-
-### 1. Administrative Groups (`:administrative`)
-- **High security risk** - require careful access management
-- **Full admin access** - broad permissions across AWS services
-- **Examples**: platform-admins, security-admins, infrastructure-admins
-
-### 2. Developer Groups (`:developer`)
-- **Medium security risk** - development access requirements
-- **Environment-specific access** - dev/staging focused permissions
-- **Examples**: frontend-developers, backend-engineers, mobile-team
-
-### 3. Operations Groups (`:operations`)
-- **High security risk** - production infrastructure access
-- **Infrastructure management** - deployment, monitoring, maintenance
-- **Examples**: infrastructure-ops, platform-sre, database-admins
-
-### 4. Read-Only Groups (`:readonly`)
-- **Low security risk** - safe for broad membership
-- **Monitoring and audit access** - view-only permissions
-- **Examples**: monitoring-viewers, audit-team, compliance-readonly
-
-### 5. Department Groups (`:department`)
-- **Medium security risk** - business function alignment
-- **Department-specific access** - resources aligned with business units
-- **Examples**: engineering-standard, finance-elevated, marketing-readonly
-
-### 6. Environment Groups (`:environment`)
-- **Variable security risk** - depends on target environment
-- **Deployment workflow access** - environment-specific permissions
-- **Examples**: production-deploy, staging-admin, development-full
-
-## Security Considerations
-
-### 1. Automatic Security Validation
-```ruby
-def validate_group_security!
-  warnings = []
-
-  # Check for overly broad group names
-  broad_names = ['users', 'all', 'everyone', 'default']
-  if broad_names.any? { |broad| name.downcase.include?(broad) }
-    warnings << "Group name '#{name}' is very broad - consider more specific grouping"
-  end
-
-  # Check for admin groups without organizational structure
-  if administrative_group? && path == "/"
-    warnings << "Administrative group '#{name}' should be in organized path structure"
-  end
-
-  # Log warnings without blocking deployment
-  unless warnings.empty?
-    puts "IAM Group Security Warnings for '#{name}':"
-    warnings.each { |warning| puts "  - #{warning}" }
-  end
-end
-```
-
-### 2. Risk-Based Access Recommendations
-- **High-risk groups** require additional approval workflows
-- **Medium-risk groups** need regular access reviews
-- **Low-risk groups** can have broader membership
-
-### 3. Naming Convention Enforcement
-- **Hyphen-based separation** for component identification
-- **Environment inclusion** for deployment-related groups
-- **Function specification** for clear purpose identification
-- **Length optimization** for readability and management
-
-## Organizational Pattern Categories
-
-### 1. Team-Based Patterns
-- Development team organization by function or product
-- Cross-functional team support for projects
-- Department-aligned teams with appropriate access levels
-
-### 2. Environment-Based Patterns
-- Production, staging, development environment access
-- Environment-specific deployment permissions
-- Read-only access for monitoring and troubleshooting
-
-### 3. Service-Oriented Patterns
-- Microservice owner, operator, viewer roles
-- Service-specific resource access
-- Cross-service integration permissions
-
-### 4. Functional Patterns
-- Administrative access by scope (infrastructure, security, etc.)
-- Compliance and audit access patterns
-- CI/CD pipeline access management
-
-### 5. Emergency and Special Access
-- Break-glass emergency access groups
-- Incident response team access
-- Security incident response permissions
-
-## Testing Approach
-
-### 1. Validation Tests
-- Group name format validation
-- Path format validation
-- Security warning generation
-- Classification accuracy testing
-
-### 2. Pattern Tests
-- Group pattern generation accuracy
-- Organizational structure validation
-- Access level recommendation testing
-- Environment and department extraction
-
-### 3. Naming Convention Tests
-- Convention scoring accuracy
-- Best practice identification
-- Component extraction testing
-- Length and format validation
-
-### 4. Integration Tests
-- Terraform resource generation
-- Resource reference outputs
-- Computed properties accuracy
-- Cross-group relationship testing
-
-## Future Enhancements
-
-### 1. Advanced Organizational Support
-- **LDAP/AD integration** for group synchronization
-- **Nested group hierarchies** for complex organizations
-- **Dynamic group membership** based on attributes
-- **Group lifecycle management** automation
-
-### 2. Enhanced Security Features
-- **Group permission analysis** across all attached policies
-- **Access pattern detection** and anomaly identification
-- **Compliance framework mapping** (SOC2, HIPAA, etc.)
-- **Regular access review** automation and reporting
-
-### 3. Operational Improvements
-- **Group usage analytics** for optimization
-- **Unused group detection** and cleanup recommendations
-- **Access optimization** suggestions based on actual usage
-- **Cost analysis** for group-based resource access
-
-### 4. Integration Features
-- **Identity provider integration** (Okta, Azure AD, etc.)
-- **RBAC system integration** for complex access models
-- **Workflow integration** for group approval processes
-- **Monitoring integration** for group activity tracking

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

@@ -1,278 +0,0 @@
-# AWS IAM Policy Implementation
-
-## Overview
-
-This implementation provides type-safe AWS IAM customer-managed policy creation with comprehensive security validation, policy templates, and complexity analysis.
-
-## Architecture
-
-### Type Safety & Validation
-- **dry-struct validation** for all policy attributes
-- **Policy document structure validation** with proper IAM schema
-- **Path format validation** (must start/end with /, 1-512 chars)
-- **Policy size validation** (max 6144 chars for managed policies)
-- **Reserved name detection** (AWS/Amazon prefixes)
-
-### Security Features
-- **Automatic security analysis** with risk level assessment
-- **Wildcard permission detection** with warnings
-- **Dangerous action identification** (iam:*, admin actions)
-- **Root resource access warnings**
-- **Complexity scoring** for policy review
-
-### Policy Templates
-- **Pre-defined templates** for common use cases
-- **Service-specific policies** (S3, CloudWatch, RDS, Lambda, etc.)
-- **Security-focused patterns** with least privilege principles
-- **Cross-service access patterns** for microservices
-
-## Key Components
-
-### 1. IamPolicyAttributes Class
-```ruby
-class IamPolicyAttributes < Dry::Struct
-  attribute :name, Types::String                    # Policy name (required)
-  attribute :path, Types::String.default("/")       # Policy path
-  attribute? :description, Types::String.optional   # Policy description
-  attribute :policy, Types::Hash.schema(...)        # Policy document
-  attribute :tags, Types::AwsTags.default({})       # Resource tags
-end
-```
-
-### 2. Policy Document Schema
-```ruby
-Types::Hash.schema(
-  Version: Types::String.default("2012-10-17"),
-  Statement: Types::Array.of(
-    Types::Hash.schema(
-      Sid?: Types::String.optional,
-      Effect: Types::String.enum("Allow", "Deny"),
-      Action: Types::String | Types::Array.of(Types::String),
-      Resource: Types::String | Types::Array.of(Types::String),
-      Condition?: Types::Hash.optional,
-      # Additional IAM-specific fields...
-    )
-  )
-)
-```
-
-### 3. Security Validation Methods
-
-#### Risk Assessment
-```ruby
-def security_level
-  if has_wildcard_permissions?
-    :high_risk
-  elsif allows_action?("iam:*") || allows_action?("sts:AssumeRole")
-    :medium_risk
-  else
-    :low_risk
-  end
-end
-```
-
-#### Complexity Scoring
-```ruby
-def complexity_score
-  statements_count = policy[:Statement].length
-  actions_count = all_actions.length
-  resources_count = all_resources.length
-  conditions_count = policy[:Statement].count { |s| s[:Condition] }
-  
-  statements_count + actions_count + resources_count + (conditions_count * 2)
-end
-```
-
-### 4. Policy Templates Module
-
-#### S3 Access Patterns
-```ruby
-module PolicyTemplates
-  def self.s3_bucket_readonly(bucket_name)
-    {
-      Version: "2012-10-17",
-      Statement: [
-        {
-          Effect: "Allow",
-          Action: ["s3:GetObject", "s3:GetObjectVersion"],
-          Resource: "arn:aws:s3:::#{bucket_name}/*"
-        },
-        {
-          Effect: "Allow", 
-          Action: ["s3:ListBucket"],
-          Resource: "arn:aws:s3:::#{bucket_name}"
-        }
-      ]
-    }
-  end
-end
-```
-
-## Implementation Decisions
-
-### 1. Security-First Approach
-- **Automatic warnings** for overly permissive policies
-- **Best practice guidance** through computed properties
-- **Template-based policies** following least privilege
-- **Risk assessment** for all policies
-
-### 2. Comprehensive Validation
-- **Schema validation** for policy document structure
-- **Size constraints** matching AWS limits
-- **Format validation** for paths and names
-- **Content analysis** for security implications
-
-### 3. Developer Experience
-- **Rich computed properties** for policy analysis
-- **Template library** for common patterns
-- **Clear error messages** for validation failures
-- **Security guidance** through warnings and scoring
-
-## Usage Patterns
-
-### 1. Simple Policies
-```ruby
-aws_iam_policy(:readonly_policy, {
-  name: "ReadOnlyAccess",
-  policy: PolicyTemplates.s3_bucket_readonly("my-bucket")
-})
-```
-
-### 2. Complex Conditional Policies
-```ruby
-aws_iam_policy(:conditional_policy, {
-  name: "ConditionalAccess",
-  policy: {
-    Version: "2012-10-17",
-    Statement: [{
-      Effect: "Allow",
-      Action: "s3:GetObject",
-      Resource: "*",
-      Condition: {
-        IpAddress: { "aws:SourceIp": "203.0.113.0/24" },
-        DateGreaterThan: { "aws:CurrentTime": "08:00Z" }
-      }
-    }]
-  }
-})
-```
-
-### 3. Multi-Statement Policies
-```ruby
-aws_iam_policy(:microservice_policy, {
-  name: "MicroserviceAccess", 
-  policy: {
-    Version: "2012-10-17",
-    Statement: [
-      {
-        Effect: "Allow",
-        Action: ["s3:GetObject", "s3:PutObject"],
-        Resource: "arn:aws:s3:::app-data/*"
-      },
-      {
-        Effect: "Allow",
-        Action: "logs:CreateLogStream",
-        Resource: "arn:aws:logs:*:*:log-group:/aws/lambda/app-*"
-      }
-    ]
-  }
-})
-```
-
-## Computed Properties Analysis
-
-The implementation provides rich computed properties for policy analysis:
-
-### Security Analysis
-- `security_level`: Risk assessment (:low_risk, :medium_risk, :high_risk)
-- `has_wildcard_permissions`: Boolean wildcard detection
-- `complexity_score`: Numeric complexity for review prioritization
-
-### Content Analysis
-- `all_actions`: Complete list of actions across all statements
-- `all_resources`: Complete list of resources across all statements
-- `service_role_policy`: Identifies policies for role assumption
-
-### Validation Helpers
-- `uses_reserved_name`: Detects AWS reserved naming patterns
-- `allows_action?(action)`: Tests if policy allows specific action
-
-## Security Considerations
-
-### 1. Automatic Security Analysis
-```ruby
-def validate_policy_security!
-  warnings = []
-
-  if has_wildcard_permissions?
-    warnings << "Policy contains wildcard (*) permissions"
-  end
-
-  dangerous_actions = ["iam:*", "iam:CreateRole", "iam:AttachRolePolicy"]
-  dangerous_actions.each do |action|
-    if allows_action?(action)
-      warnings << "Policy allows potentially dangerous action: #{action}"
-    end
-  end
-
-  # Log warnings but don't fail validation
-  unless warnings.empty?
-    puts "IAM Policy Security Warnings for '#{name}':"
-    warnings.each { |warning| puts "  - #{warning}" }
-  end
-end
-```
-
-### 2. Best Practice Templates
-- **Least privilege** policy templates
-- **Service-specific** access patterns
-- **Conditional access** examples
-- **Cross-service** integration patterns
-
-### 3. Compliance Support
-- **Policy complexity scoring** for review processes
-- **Security level classification** for risk management
-- **Automatic documentation** through computed properties
-- **Audit trail** through comprehensive resource references
-
-## Testing Approach
-
-### 1. Type Safety Tests
-- Validate all dry-struct constraints
-- Test policy document schema validation
-- Verify size and format constraints
-
-### 2. Security Validation Tests
-- Test security warning generation
-- Verify risk level classification
-- Check complexity scoring accuracy
-
-### 3. Template Tests
-- Validate all policy templates
-- Test template parameter substitution
-- Verify generated policy correctness
-
-### 4. Integration Tests
-- Test with terraform-synthesizer
-- Verify resource reference outputs
-- Check computed properties accuracy
-
-## Future Enhancements
-
-### 1. Advanced Security Features
-- **Policy simulation** integration with AWS APIs
-- **Least privilege recommendations** based on usage
-- **Cross-policy conflict detection**
-- **Automated policy optimization**
-
-### 2. Enhanced Templates
-- **Industry-specific** policy templates
-- **Compliance framework** templates (SOC2, HIPAA, etc.)
-- **Multi-cloud** policy translation
-- **Dynamic policy generation** based on resources
-
-### 3. Integration Features
-- **Policy version management** and rollback
-- **Cross-account policy** validation
-- **Service catalog** integration
-- **Cost impact analysis** for policies