README¶

Enterprise-grade Security Group provisioning and management tool for AWS.

Table of Contents¶

What It Does
Quick Start
Common Commands
AWS Credentials
What Gets Created
Available Scenarios
Directory Structure
Accessing Documentation
Next Steps
Quick Troubleshooting
License

What It Does¶

Creates and configures Security Groups using CloudFormation
Generates IAM policies automatically
Provides scenario-based templates (3-tier-web, 2-tier-web, database-specific)
Supports customer overrides (port changes, additional rules)
Validates configurations and templates before deployment
Previews infrastructure changes before applying them
Detects infrastructure drift against deployed stacks
Supports safe test deployments with isolated resource names
Stores Security Group IDs in Parameter Store for downstream consumers
Generates pre-deployment review reports with override highlighting

Quick Start¶

1. Pull the Image¶

docker pull <your-ecr-url>/sg-provisioner:latest

2. Set Up Directories¶

mkdir -p mlops-infra-suite/sg/{configs,policies,reports,templates,schemas}
cd mlops-infra-suite

3. Add Your Configuration¶

Create sg/configs/my-config.yaml:

client:
  company_name: Global Bank
  company_prefix: globalbank
  account_id: "123456789012"
  tenant_id: "c001"

environment:
  env: prod
  region: us-west-2

security_groups:
  scenario: 3-tier-web
  vpc_source: parameter-store
  vpc_parameter_store_path: /vpc/globalbank-prod-c001-us-west-2-vpc/VPCId
  sg_name_override: ""
  workload: ""

  overrides:
    app:
      port_overrides:
        - protocol: tcp
          old_port: 8080
          new_port: 8443
      additional_ingress:
        - protocol: tcp
          port: 9090
          source_tier: web
          description: Prometheus metrics from web tier

tags:
  cost_center: Fraud Operations
  project: Real-time Fraud Detection
  owner: fraud-ml-engineering-team

4. Run Your First Command¶

docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config my-config.yaml \
  --action validate-config

Success! You’ve validated your configuration.

Common Commands¶

Validate Configuration¶

docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config my-config.yaml \
  --action validate-config

List Available Scenarios¶

docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config my-config.yaml \
  --action list-scenarios

Show Scenario Details¶

docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config my-config.yaml \
  --action show-scenario

Generate IAM Policy¶

docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/policies:/app/policies \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config my-config.yaml \
  --action create-policy

Generate CloudFormation Template¶

docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/templates:/app/templates \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config my-config.yaml \
  --action create-prov-template

Validate Generated Template¶

docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/templates:/app/templates \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config my-config.yaml \
  --action validate-prov-template

Generate Pre-Deployment Review Report¶

docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/templates:/app/templates \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config my-config.yaml \
  --action create-review-report

Create Security Groups¶

docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/templates:/app/templates \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config my-config.yaml \
  --action create-security-groups \
  --force

Preview Changes¶

docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/templates:/app/templates \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config my-config.yaml \
  --action show-changes

Check Infrastructure Drift¶

docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config my-config.yaml \
  --action check-drift

Test Deploy (Safe Testing)¶

docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config my-config.yaml \
  --action test-deploy

Delete Security Groups¶

docker run --rm \
  -v ~/.aws:/home/sguser/.aws:ro \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  --config my-config.yaml \
  --action delete-security-groups \
  --force

AWS Credentials¶

Option 1: AWS Profile (Recommended)

-v ~/.aws:/home/sguser/.aws:ro

Option 2: Environment Variables

-e AWS_ACCESS_KEY_ID=your_key \
-e AWS_SECRET_ACCESS_KEY=your_secret \
-e AWS_DEFAULT_REGION=us-west-2

What Gets Created¶

When you run create-security-groups, the tool creates:

Security Groups — one per tier defined in the selected scenario
Ingress Rules — CIDR-based inline + cross-tier as standalone resources
Egress Rules — CIDR-based inline + cross-tier as standalone resources
SSM Parameters — stores each SG ID at /sg/{sg-name}/{tier}/SecurityGroupId
- e.g., /sg/globalbank-prod-c001-us-west-2-sg/web/SecurityGroupId
Tags on all resources (Name, Environment, ManagedBy, Tier, custom tags)

Available Scenarios¶

Scenario	Description	DB Port
3-tier-web	Generic 3-tier web application (PostgreSQL default)	5432
3-tier-rds-postgresql	3-tier with RDS PostgreSQL	5432
3-tier-rds-mysql	3-tier with RDS MySQL	3306
3-tier-redshift	3-tier with Redshift	5439
3-tier-oracle	3-tier with Oracle	1521
3-tier-sqlserver	3-tier with SQL Server	1433
3-tier-documentdb	3-tier with DocumentDB	27017
2-tier-web	2-tier web + app (no DB)	—
2-tier-rds-postgresql	2-tier web + PostgreSQL DB	5432

Directory Structure¶

your-project/
├── configs/          # SG configuration files
├── policies/         # Generated IAM policies
├── templates/        # Generated CloudFormation templates and review YAMLs
├── reports/          # Execution logs and HTML reports
└── schemas/          # Validation schema and scenario definitions

Accessing Documentation¶

All documentation is embedded in the Docker image:

# List available documentation
docker run --rm --entrypoint ls sg-provisioner:latest /app/docs

# Copy all documentation locally
container_id=$(docker create sg-provisioner:latest)
docker cp $container_id:/app/docs/. sg/docs/
docker rm $container_id

Next Steps¶

Read the User Guide for all commands
See Configuration Reference for all parameters
See Scenarios for scenario details and overrides
Check Troubleshooting for common issues

Quick Troubleshooting¶

VPC not found in Parameter Store

Ensure the VPC was deployed with the VPC Provisioner first
Verify the path matches: /vpc/{vpc-name}/VPCId
Or use vpc_source: direct with a VPC ID

Stack already exists

Use delete-security-groups --force to remove existing stack
Or use show-changes to preview what would change
Or use workload field for multiple SG sets

Circular dependency error

This should not occur — cross-tier rules use standalone resources
If it does, check for custom scenario YAML issues

Permission denied

Check IAM permissions (use create-policy to generate required policy)
Verify AWS credentials are valid

Scenario not found

Use list-scenarios to see available scenarios
Verify scenario name in config matches a YAML file in schemas/scenarios/

License¶

This product requires a valid AWS Marketplace subscription.