@techwavedev/agi-agent-kit 1.1.7 → 1.2.1

package/templates/skills/ec/aws-terraform/references/best_practices.md

@@ -0,0 +1,394 @@
+# Terraform Best Practices for AWS
+
+Reference guide for AWS Terraform development.
+
+## Provider Selection
+
+### AWS Provider vs AWSCC Provider
+
+| Provider                      | Use When                                                |
+| ----------------------------- | ------------------------------------------------------- |
+| **AWS** (`hashicorp/aws`)     | Most common resources, extensive documentation          |
+| **AWSCC** (`hashicorp/awscc`) | New resources, consistent API behavior, better defaults |
+
+**Recommendation:** Prefer AWSCC when available for new projects; it provides better security defaults and consistent API behavior.
+
+---
+
+## State Management
+
+### Remote State with S3
+
+```hcl
+terraform {
+  backend "s3" {
+    bucket         = "terraform-state-511383368449"
+    key            = "project/terraform.tfstate"
+    region         = "eu-west-1"
+    encrypt        = true
+    dynamodb_table = "terraform-locks"
+  }
+}
+```
+
+### State Locking
+
+Always enable DynamoDB locking for team environments:
+
+```hcl
+resource "aws_dynamodb_table" "terraform_locks" {
+  name         = "terraform-locks"
+  billing_mode = "PAY_PER_REQUEST"
+  hash_key     = "LockID"
+
+  attribute {
+    name = "LockID"
+    type = "S"
+  }
+
+  tags = {
+    Purpose   = "Terraform State Locking"
+    ManagedBy = "terraform"
+  }
+}
+```
+
+---
+
+## Security Patterns
+
+### Least Privilege IAM
+
+```hcl
+data "aws_iam_policy_document" "lambda_assume" {
+  statement {
+    actions = ["sts:AssumeRole"]
+    principals {
+      type        = "Service"
+      identifiers = ["lambda.amazonaws.com"]
+    }
+  }
+}
+
+resource "aws_iam_role" "lambda" {
+  name               = "lambda-execution-role"
+  assume_role_policy = data.aws_iam_policy_document.lambda_assume.json
+}
+
+# Attach only required permissions
+resource "aws_iam_role_policy_attachment" "lambda_basic" {
+  role       = aws_iam_role.lambda.name
+  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
+}
+```
+
+### Encryption at Rest
+
+Always enable encryption for data stores:
+
+```hcl
+# RDS
+resource "aws_db_instance" "main" {
+  # ...
+  storage_encrypted = true
+  kms_key_id        = aws_kms_key.rds.arn
+}
+
+# EBS
+resource "aws_ebs_volume" "main" {
+  # ...
+  encrypted  = true
+  kms_key_id = aws_kms_key.ebs.arn
+}
+
+# S3
+resource "aws_s3_bucket_server_side_encryption_configuration" "main" {
+  bucket = aws_s3_bucket.main.id
+  rule {
+    apply_server_side_encryption_by_default {
+      kms_master_key_id = aws_kms_key.s3.arn
+      sse_algorithm     = "aws:kms"
+    }
+  }
+}
+```
+
+### Security Groups - Explicit Rules
+
+```hcl
+resource "aws_security_group" "web" {
+  name        = "web-sg"
+  description = "Security group for web servers"
+  vpc_id      = var.vpc_id
+
+  # HTTPS from anywhere
+  ingress {
+    from_port   = 443
+    to_port     = 443
+    protocol    = "tcp"
+    cidr_blocks = ["0.0.0.0/0"]
+    description = "HTTPS traffic"
+  }
+
+  # Explicit egress rules
+  egress {
+    from_port   = 443
+    to_port     = 443
+    protocol    = "tcp"
+    cidr_blocks = ["0.0.0.0/0"]
+    description = "HTTPS to external services"
+  }
+
+  tags = {
+    Name        = "web-sg"
+    Environment = var.environment
+  }
+}
+```
+
+---
+
+## Tagging Strategy
+
+### Default Tags Provider
+
+```hcl
+provider "aws" {
+  region = "eu-west-1"
+
+  default_tags {
+    tags = {
+      Environment = var.environment
+      Project     = var.project_name
+      ManagedBy   = "terraform"
+      Owner       = var.owner
+      CostCenter  = var.cost_center
+    }
+  }
+}
+```
+
+### Required Tags
+
+| Tag           | Purpose                           |
+| ------------- | --------------------------------- |
+| `Environment` | dev, staging, prod                |
+| `Project`     | Project/application name          |
+| `ManagedBy`   | terraform, manual, cloudformation |
+| `Owner`       | Team or individual owner          |
+| `CostCenter`  | For billing allocation            |
+
+---
+
+## Modules Best Practices
+
+### Module Structure
+
+```
+modules/
+└── vpc/
+    ├── main.tf          # Primary resources
+    ├── variables.tf     # Input variables
+    ├── outputs.tf       # Output values
+    ├── versions.tf      # Provider requirements
+    └── README.md        # Usage documentation
+```
+
+### Module Versioning
+
+```hcl
+module "vpc" {
+  source  = "terraform-aws-modules/vpc/aws"
+  version = "~> 5.0"  # Allow patch updates
+
+  # Pin major version to avoid breaking changes
+}
+```
+
+### Local Module Usage
+
+```hcl
+module "app_vpc" {
+  source = "../../modules/vpc"
+
+  name        = "app-vpc"
+  environment = var.environment
+  cidr_block  = "10.0.0.0/16"
+}
+```
+
+---
+
+## Variable Best Practices
+
+### Type Constraints
+
+```hcl
+variable "instance_type" {
+  type        = string
+  default     = "t3.micro"
+  description = "EC2 instance type"
+
+  validation {
+    condition     = can(regex("^t3\\.", var.instance_type))
+    error_message = "Instance type must be in the t3 family."
+  }
+}
+
+variable "allowed_cidrs" {
+  type        = list(string)
+  default     = []
+  description = "List of CIDRs allowed to access resources"
+
+  validation {
+    condition = alltrue([
+      for cidr in var.allowed_cidrs :
+      can(cidrhost(cidr, 0))
+    ])
+    error_message = "All values must be valid CIDR blocks."
+  }
+}
+```
+
+### Sensitive Variables
+
+```hcl
+variable "database_password" {
+  type        = string
+  sensitive   = true
+  description = "Database master password"
+}
+```
+
+---
+
+## Lifecycle Rules
+
+### Prevent Accidental Destruction
+
+```hcl
+resource "aws_db_instance" "main" {
+  # ...
+
+  lifecycle {
+    prevent_destroy = true
+  }
+}
+```
+
+### Ignore External Changes
+
+```hcl
+resource "aws_autoscaling_group" "main" {
+  # ...
+
+  lifecycle {
+    ignore_changes = [
+      desired_capacity,  # Allow autoscaling to manage
+    ]
+  }
+}
+```
+
+### Create Before Destroy
+
+```hcl
+resource "aws_instance" "main" {
+  # ...
+
+  lifecycle {
+    create_before_destroy = true
+  }
+}
+```
+
+---
+
+## Data Sources
+
+### Current Account Info
+
+```hcl
+data "aws_caller_identity" "current" {}
+data "aws_region" "current" {}
+
+locals {
+  account_id = data.aws_caller_identity.current.account_id
+  region     = data.aws_region.current.name
+}
+```
+
+### Latest AMI
+
+```hcl
+data "aws_ami" "amazon_linux" {
+  most_recent = true
+  owners      = ["amazon"]
+
+  filter {
+    name   = "name"
+    values = ["al2023-ami-*-x86_64"]
+  }
+
+  filter {
+    name   = "virtualization-type"
+    values = ["hvm"]
+  }
+}
+```
+
+---
+
+## Workspace Strategy
+
+Use workspaces for environment isolation:
+
+```bash
+# Create workspaces
+terraform workspace new dev
+terraform workspace new staging
+terraform workspace new prod
+
+# Select workspace
+terraform workspace select dev
+```
+
+Reference workspace in code:
+
+```hcl
+locals {
+  environment = terraform.workspace
+
+  instance_type = {
+    dev     = "t3.micro"
+    staging = "t3.small"
+    prod    = "t3.medium"
+  }[local.environment]
+}
+```
+
+---
+
+## Performance Tips
+
+### Parallelism
+
+```bash
+# Increase parallelism for large deployments
+terraform apply -parallelism=20
+```
+
+### Target Specific Resources
+
+```bash
+# Apply only specific resources
+terraform apply -target=module.vpc
+terraform apply -target=aws_instance.web
+```
+
+### Refresh State
+
+```bash
+# Skip refresh for faster plans
+terraform plan -refresh=false
+```

package/templates/skills/ec/aws-terraform/references/checkov_reference.md

@@ -0,0 +1,337 @@
+# Checkov Security Scanning Reference
+
+Comprehensive guide for security and compliance scanning with Checkov.
+
+## Quick Start
+
+```bash
+# Scan current directory
+checkov -d .
+
+# Scan with specific framework
+checkov -d . --framework terraform
+
+# Output as JSON
+checkov -d . -o json > checkov-report.json
+
+# Compact output
+checkov -d . --compact
+```
+
+---
+
+## Common AWS Checks
+
+### S3 Buckets
+
+| Check ID      | Description                       | Severity |
+| ------------- | --------------------------------- | -------- |
+| `CKV_AWS_18`  | S3 bucket access logging enabled  | MEDIUM   |
+| `CKV_AWS_19`  | S3 bucket encryption enabled      | HIGH     |
+| `CKV_AWS_20`  | S3 bucket public access block     | HIGH     |
+| `CKV_AWS_21`  | S3 bucket versioning enabled      | MEDIUM   |
+| `CKV_AWS_53`  | S3 bucket lifecycle configuration | LOW      |
+| `CKV_AWS_145` | S3 bucket encrypted with CMK      | MEDIUM   |
+
+### EC2 Instances
+
+| Check ID      | Description                     | Severity |
+| ------------- | ------------------------------- | -------- |
+| `CKV_AWS_79`  | IMDSv2 required                 | HIGH     |
+| `CKV_AWS_88`  | EC2 not assigned public IP      | MEDIUM   |
+| `CKV_AWS_126` | EC2 detailed monitoring enabled | LOW      |
+| `CKV_AWS_135` | EBS optimized instance          | LOW      |
+| `CKV_AWS_8`   | EBS encryption enabled          | HIGH     |
+
+### Security Groups
+
+| Check ID      | Description                        | Severity |
+| ------------- | ---------------------------------- | -------- |
+| `CKV_AWS_23`  | Security group has description     | LOW      |
+| `CKV_AWS_24`  | No SSH from 0.0.0.0/0              | HIGH     |
+| `CKV_AWS_25`  | No RDP from 0.0.0.0/0              | HIGH     |
+| `CKV_AWS_260` | No unrestricted ingress to port 80 | MEDIUM   |
+| `CKV_AWS_277` | No unrestricted egress             | LOW      |
+
+### RDS
+
+| Check ID      | Description             | Severity |
+| ------------- | ----------------------- | -------- |
+| `CKV_AWS_16`  | RDS encryption enabled  | HIGH     |
+| `CKV_AWS_17`  | RDS logging enabled     | MEDIUM   |
+| `CKV_AWS_118` | RDS enhanced monitoring | LOW      |
+| `CKV_AWS_157` | RDS multi-AZ enabled    | MEDIUM   |
+| `CKV_AWS_161` | RDS IAM authentication  | MEDIUM   |
+
+### Lambda
+
+| Check ID      | Description                     | Severity |
+| ------------- | ------------------------------- | -------- |
+| `CKV_AWS_45`  | Lambda in VPC                   | MEDIUM   |
+| `CKV_AWS_50`  | X-Ray tracing enabled           | LOW      |
+| `CKV_AWS_115` | Reserved concurrency set        | LOW      |
+| `CKV_AWS_116` | Dead letter queue configured    | MEDIUM   |
+| `CKV_AWS_173` | Environment variables encrypted | HIGH     |
+
+### IAM
+
+| Check ID      | Description                   | Severity |
+| ------------- | ----------------------------- | -------- |
+| `CKV_AWS_40`  | No wildcard actions in IAM    | HIGH     |
+| `CKV_AWS_49`  | No wildcard resources in IAM  | HIGH     |
+| `CKV_AWS_109` | IAM policy allows assume role | MEDIUM   |
+| `CKV_AWS_289` | No admin access policy        | CRITICAL |
+
+---
+
+## Skipping Checks
+
+### Inline Skip
+
+```hcl
+#checkov:skip=CKV_AWS_18:Access logging disabled for non-production
+resource "aws_s3_bucket" "dev" {
+  bucket = "my-dev-bucket"
+}
+```
+
+### Multiple Skips
+
+```hcl
+#checkov:skip=CKV_AWS_18:Access logging disabled for dev
+#checkov:skip=CKV_AWS_21:Versioning not needed for temp data
+resource "aws_s3_bucket" "temp" {
+  bucket = "temp-processing-bucket"
+}
+```
+
+### Command-Line Skip
+
+```bash
+# Skip specific checks
+checkov -d . --skip-check CKV_AWS_18,CKV_AWS_21
+
+# Skip by severity
+checkov -d . --check LOW --skip-check-severity MEDIUM,HIGH
+```
+
+### Skip File
+
+Create `.checkov.yml`:
+
+```yaml
+skip-check:
+  - CKV_AWS_18 # Access logging for dev buckets
+  - CKV_AWS_21 # Versioning for temp buckets
+
+framework:
+  - terraform
+
+compact: true
+```
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+name: Terraform Security Scan
+
+on:
+  pull_request:
+    paths:
+      - "**.tf"
+
+jobs:
+  checkov:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run Checkov
+        uses: bridgecrewio/checkov-action@master
+        with:
+          directory: .
+          framework: terraform
+          soft_fail: false
+          skip_check: CKV_AWS_18
+```
+
+### Pre-commit Hook
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/bridgecrewio/checkov
+    rev: "3.0.0"
+    hooks:
+      - id: checkov
+        args: [--framework, terraform]
+```
+
+---
+
+## Output Formats
+
+```bash
+# CLI output (default)
+checkov -d .
+
+# JSON output
+checkov -d . -o json > report.json
+
+# JUnit XML (for CI)
+checkov -d . -o junitxml > report.xml
+
+# SARIF (for GitHub Security)
+checkov -d . -o sarif > report.sarif
+
+# Multiple outputs
+checkov -d . -o cli -o json > report.json
+```
+
+---
+
+## Fixing Common Issues
+
+### CKV_AWS_79: IMDSv2
+
+```hcl
+resource "aws_instance" "main" {
+  # ... other config
+
+  metadata_options {
+    http_tokens                 = "required"  # Enforce IMDSv2
+    http_endpoint               = "enabled"
+    http_put_response_hop_limit = 1
+  }
+}
+```
+
+### CKV_AWS_20: S3 Public Access Block
+
+```hcl
+resource "aws_s3_bucket_public_access_block" "main" {
+  bucket = aws_s3_bucket.main.id
+
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+}
+```
+
+### CKV_AWS_24: No SSH from 0.0.0.0/0
+
+```hcl
+resource "aws_security_group_rule" "ssh" {
+  type              = "ingress"
+  from_port         = 22
+  to_port           = 22
+  protocol          = "tcp"
+  # Use specific CIDR, not 0.0.0.0/0
+  cidr_blocks       = ["10.0.0.0/8"]
+  security_group_id = aws_security_group.main.id
+  description       = "SSH from internal network"
+}
+```
+
+### CKV_AWS_16: RDS Encryption
+
+```hcl
+resource "aws_db_instance" "main" {
+  # ... other config
+
+  storage_encrypted = true
+  kms_key_id        = aws_kms_key.rds.arn
+}
+```
+
+### CKV_AWS_173: Lambda Environment Encryption
+
+```hcl
+resource "aws_lambda_function" "main" {
+  # ... other config
+
+  kms_key_arn = aws_kms_key.lambda.arn
+
+  environment {
+    variables = {
+      API_KEY = var.api_key  # Will be encrypted with KMS
+    }
+  }
+}
+```
+
+---
+
+## Custom Policies
+
+### Python Custom Check
+
+```python
+# custom_checks/s3_naming.py
+from checkov.terraform.checks.resource.base_resource_check import BaseResourceCheck
+from checkov.common.models.enums import CheckResult, CheckCategories
+
+class S3NamingConvention(BaseResourceCheck):
+    def __init__(self):
+        name = "S3 bucket follows naming convention"
+        id = "CKV_CUSTOM_1"
+        supported_resources = ["aws_s3_bucket"]
+        categories = [CheckCategories.CONVENTION]
+        super().__init__(name=name, id=id, categories=categories,
+                        supported_resources=supported_resources)
+
+    def scan_resource_conf(self, conf):
+        bucket_name = conf.get("bucket", [""])[0]
+        if bucket_name.startswith("company-"):
+            return CheckResult.PASSED
+        return CheckResult.FAILED
+
+check = S3NamingConvention()
+```
+
+Run with custom checks:
+
+```bash
+checkov -d . --external-checks-dir ./custom_checks
+```
+
+---
+
+## Severity Levels
+
+| Level        | Description              | Action              |
+| ------------ | ------------------------ | ------------------- |
+| **CRITICAL** | Must fix immediately     | Block deployment    |
+| **HIGH**     | Security vulnerability   | Fix before prod     |
+| **MEDIUM**   | Security best practice   | Fix soon            |
+| **LOW**      | Hardening recommendation | Fix when convenient |
+
+### Filter by Severity
+
+```bash
+# Only high and critical
+checkov -d . --check HIGH,CRITICAL
+
+# Fail on critical only
+checkov -d . --hard-fail-on CRITICAL
+```
+
+---
+
+## Performance Tips
+
+```bash
+# Parallel scanning
+checkov -d . --parallelism 8
+
+# Skip downloads
+checkov -d . --skip-download
+
+# Cache results
+checkov -d . --cache-dir /tmp/.checkov_cache
+```