User Guide¶

Complete command reference for the SG Provisioner Tool.

Table of Contents¶

Quick Start
Configuration
Commands Reference
Common Workflows
Volume Mounts
AWS Credentials
Best Practices
FAQ

Quick Start¶

Pre-Deployment Checklist¶

Docker 20.10+ installed and running (docker --version)
AWS credentials configured (aws sts get-caller-identity works)
AWS Marketplace subscription active for SG Provisioner
IAM permissions verified (see IAM Permissions)
Configuration file created and validated
VPC deployed and VPC ID available (via SSM Parameter Store or direct ID)
Scenario selected for your architecture (use list-scenarios to view options)
Reviewed generated CloudFormation template
Tested in dev/staging environment first

1. Create Directories and Copy Documentation¶

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

# Create a temporary container
container_id=$(docker create sg-provisioner:latest)

# Copy docs from container to host
docker cp $container_id:/app/docs/. sg/docs/

# Remove the temporary container
docker rm $container_id

ls sg/docs/

The following directory tree is created and the documentation files are copied.

└── mlops-infra-suite
    └── sg
        ├── configs
        ├── docs
        │   ├── _sources/
        │   ├── _static/
        │   ├── CONFIGURATION.html
        │   ├── FEEDBACK.html
        │   ├── IAM_PERMISSIONS.html
        │   ├── README.html
        │   ├── RELEASE_NOTES.html
        │   ├── ROADMAP.html
        │   ├── SCENARIOS.html
        │   ├── SECURITY.html
        │   ├── SECURITY_GUIDELINES.html
        │   ├── SUPPORT.html
        │   ├── TROUBLESHOOTING.html
        │   ├── USER_GUIDE.html
        │   ├── api_reference.html
        │   ├── genindex.html
        │   ├── index.html
        │   ├── objects.inv
        │   ├── py-modindex.html
        │   ├── search.html
        │   └── searchindex.js
        ├── policies
        ├── reports
        └── templates

Open sg/docs/index.html in your browser to view the documentation.

2. Copy Schemas and Scenarios¶

# Create a temporary container
container_id=$(docker create sg-provisioner:latest)

# Copy schemas from container to host
docker cp $container_id:/app/schemas/. sg/schemas/

# Remove the temporary container
docker rm $container_id

ls sg/schemas/
ls sg/schemas/scenarios/

The schemas directory contains the validation schema and all available scenario templates:

└── mlops-infra-suite
    └── sg
        └── schemas
            ├── validation-schema.yaml
            └── scenarios
                ├── 2-tier-rds-postgresql.yaml
                ├── 2-tier-web.yaml
                ├── 3-tier-documentdb.yaml
                ├── 3-tier-oracle.yaml
                ├── 3-tier-rds-mysql.yaml
                ├── 3-tier-rds-postgresql.yaml
                ├── 3-tier-redshift.yaml
                ├── 3-tier-sqlserver.yaml
                └── 3-tier-web.yaml

Review the scenario YAML files to understand the security group rules that will be created for each architecture pattern.

3A. Prepare Configuration File¶

The configuration file contains your environment-specific settings and any overrides to the base scenario. The base scenario (e.g., 3-tier-web.yaml) lives in /app/schemas/scenarios/ inside the container — you copied these to sg/schemas/scenarios/ in Step 2. Your config file selects which scenario to use and applies customizations (port changes, additional rules) on top of it.

Create a YAML configuration file in mlops-infra-suite/sg/configs/ directory on host.

└── mlops-infra-suite
    └── sg
      └── configs
         └── globalbank-prod-c001-us-west-2-sg.yaml

Here is an example YAML configuration file. Replace data elements with your data.

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
    db:
      additional_ingress:
        - protocol: tcp
          port: 5432
          source_tier: app
          description: Read replica connection from app tier

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

3B. Verify Structure of Configuration File¶

The configuration file has four sections: client, environment, security_groups, and tags.

client:
  company_name: string          # Full company name
  company_prefix: string        # Short identifier (lowercase, pattern: ^[a-z][a-z0-9-]*$)
  account_id: "string"          # 12-digit AWS account ID (quoted)
  tenant_id: "string"           # 4-character alphanumeric (pattern: ^[a-z0-9]{4}$)

environment:
  env: string                   # prod, dev, test, staging
  region: string                # AWS region (e.g., us-west-2)

security_groups:
  scenario: string              # Scenario template name (e.g., 3-tier-web)
  vpc_source: string            # parameter-store or direct
  vpc_parameter_store_path: string  # SSM path (when vpc_source: parameter-store)
  vpc_id: string                # VPC ID (when vpc_source: direct)
  sg_name_override: ""          # Override auto-generated name (optional)
  workload: ""                  # Workload discriminator (optional)
  overrides:                    # Per-tier customizations (optional)
    <tier_name>:
      port_overrides: []
      additional_ingress: []
      additional_egress: []

tags:
  cost_center: string
  project: string
  owner: string

SG Naming Convention:

Format	Pattern	Example
Without workload	`{prefix}-{env}-{tenant}-{region}-sg`	`globalbank-prod-c001-us-west-2-sg`
With workload	`{prefix}-{env}-{tenant}-{region}-{workload}-sg`	`globalbank-prod-c001-us-west-2-fraud-sg`

For complete configuration reference including overrides, validation rules, and examples, see Configuration Reference.

4A. Validate Configuration Template¶

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act validate-config

4B. List 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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act list-scenarios

4C. Show Scenario¶

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act show-scenario

4D. Create Policy JSON File¶

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act create-policy

4E. Create Provisioning 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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act create-prov-template

4F. Validate Provisioning 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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act validate-prov-template

4G. Create Pre-deployment Reports¶

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act create-review-report

4H. Test Deploy¶

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act test-deploy

4I. Create Security Groups (Deployment)¶

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act create-security-groups \
--force

4J. Show 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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act show-changes

4K. Check 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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act check-drift

4L. 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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act delete-security-groups \
--force

5. Expected Output Files¶

sg/
├── configs/
│   └── globalbank-prod-c001-us-west-2-sg.yaml
├── policies/
│   └── globalbank-prod-c001-us-west-2-sg-iam-policy.json
├── reports/
│   ├── globalbank-prod-c001-us-west-2-sg-validate-config-YYYYMMDD_HHMMSS_mmm.log
│   ├── globalbank-prod-c001-us-west-2-sg-list-scenarios-YYYYMMDD_HHMMSS_mmm.log
│   ├── globalbank-prod-c001-us-west-2-sg-show-scenario-YYYYMMDD_HHMMSS_mmm.log
│   ├── globalbank-prod-c001-us-west-2-sg-create-policy-YYYYMMDD_HHMMSS_mmm.log
│   ├── globalbank-prod-c001-us-west-2-sg-create-prov-template-YYYYMMDD_HHMMSS_mmm.log
│   ├── globalbank-prod-c001-us-west-2-sg-validate-prov-template-YYYYMMDD_HHMMSS_mmm.log
│   ├── globalbank-prod-c001-us-west-2-sg-create-review-report-YYYYMMDD_HHMMSS_mmm.log
│   ├── globalbank-prod-c001-us-west-2-sg-review-YYYYMMDD_HHMMSS.html
│   ├── globalbank-prod-c001-us-west-2-sg-test-deploy-YYYYMMDD_HHMMSS_mmm.log
│   ├── globalbank-prod-c001-us-west-2-sg-create-security-groups-YYYYMMDD_HHMMSS_mmm.log
│   ├── globalbank-prod-c001-us-west-2-sg-post-deployment-YYYYMMDD_HHMMSS.html
│   ├── globalbank-prod-c001-us-west-2-sg-show-changes-YYYYMMDD_HHMMSS_mmm.log
│   ├── globalbank-prod-c001-us-west-2-sg-check-drift-YYYYMMDD_HHMMSS_mmm.log
│   └── globalbank-prod-c001-us-west-2-sg-delete-security-groups-YYYYMMDD_HHMMSS_mmm.log
└── templates/
    ├── globalbank-prod-c001-us-west-2-sg-template.yaml
    └── globalbank-prod-c001-us-west-2-sg-review.yaml

File Naming Conventions:

Logs: <sg-name>-<action>-YYYYMMDD_HHMMSS_mmm.log
Pre-Deployment Report: <sg-name>-review-YYYYMMDD_HHMMSS.html
Post-Deployment Report: <sg-name>-post-deployment-YYYYMMDD_HHMMSS.html
Templates: <sg-name>-template.yaml
Policies: <sg-name>-iam-policy.json

File Types:

.log files contain detailed execution logs for troubleshooting
.html files are professional reports for visualization and documentation
.yaml files are CloudFormation templates
.json files are IAM policies for permission management

Security Scanning¶

Optional: Scan Docker Image for Vulnerabilities¶

You can scan the SG Provisioner Docker image for security vulnerabilities using Trivy or any container scanning tool your organization uses.

Install Trivy:

# macOS
brew install trivy

# Linux
sudo apt-get install trivy

Run scan:

trivy image sg-provisioner:latest

Filter by severity:

trivy image --severity HIGH,CRITICAL sg-provisioner:latest

Note: OS-level vulnerabilities in the base image (Debian) are common and typically have no fixed version available yet. Python package vulnerabilities are more actionable — report any findings to support.

Commands Reference¶

validate-config¶

Check YAML configuration for schema compliance and syntax errors.

Purpose: Verify YAML syntax and schema compliance before deployment.

AWS Credentials: Required (license validation).

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act validate-config

Output:

reports/<sg-name>-validate-config-YYYYMMDD_HHMMSS_mmm.log

What It Checks:

YAML syntax validity
Required fields present
Field value constraints (patterns, enums)

list-scenarios¶

Lists all available scenario templates.

Purpose: Discover which architecture patterns are available.

AWS Credentials: Required (license validation).

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act list-scenarios

Output:

Console listing of all scenario YAML files with descriptions.
reports/<sg-name>-list-scenarios-YYYYMMDD_HHMMSS_mmm.log

show-scenario¶

Displays the details of the scenario configured in your YAML file.

Purpose: Review the security group tiers, ports, and rules before deployment.

AWS Credentials: Required (license validation).

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act show-scenario

Output:

Console display of tiers, ingress/egress rules, and ports for the selected scenario.
reports/<sg-name>-show-scenario-YYYYMMDD_HHMMSS_mmm.log

create-policy¶

Generates an IAM policy JSON file scoped to your configuration.

Purpose: Produce a least-privilege IAM policy for attaching to your user/role.

AWS Credentials: Required (license validation).

Command:

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act create-policy

Output:

Report in console
reports/<sg-name>-create-policy-YYYYMMDD_HHMMSS_mmm.log
policies/<sg-name>-iam-policy.json

create-prov-template¶

Generates a CloudFormation template for the security groups.

Purpose: Create infrastructure-as-code for review before deployment.

AWS Credentials: Required.

Command:

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act create-prov-template

How It Works:

Validates scenarios directory exists
Validates VPC exists
Loads the selected scenario
Applies overrides from configuration (if any)
Validates scenario rules (errors block generation unless --force is used)
Generates and saves CloudFormation template

Output:

Report in console
reports/<sg-name>-create-prov-template-YYYYMMDD_HHMMSS_mmm.log
templates/<sg-name>-template.yaml — CloudFormation template

validate-prov-template¶

Validates the generated CloudFormation template locally.

Purpose: Catch template errors (syntax, references) before deployment.

AWS Credentials: Required (license validation).

Command:

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act validate-prov-template

What It Checks:

YAML syntax valid
Required CloudFormation keys present (AWSTemplateFormatVersion, Resources)
All !Ref and !GetAtt targets resolve within the template
Resource types are valid for SG templates (AWS::EC2::SecurityGroup, AWS::EC2::SecurityGroupIngress, AWS::EC2::SecurityGroupEgress, AWS::SSM::Parameter)

Output:

reports/<sg-name>-validate-prov-template-YYYYMMDD_HHMMSS_mmm.log

create-review-report¶

Generates a pre-deployment review report.

Purpose: Produce an HTML report summarizing what will be deployed for stakeholder review.

AWS Credentials: Required (license validation).

Command:

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act create-review-report

Output:

templates/<sg-name>-review.yaml — Human-readable review summary
reports/<sg-name>-review-YYYYMMDD_HHMMSS.html — Visual report
reports/<sg-name>-create-review-report-YYYYMMDD_HHMMSS_mmm.log

test-deploy¶

Deploys security groups with a random test suffix for safe testing.

Purpose: Validate that the template deploys successfully without affecting production.

AWS Credentials: Required.

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act test-deploy

How It Works:

Generates a random 6-character suffix
Builds test stack name using the suffix
Loads scenario and applies overrides (if any)
Generates CloudFormation template in-memory (not saved to disk)
Deploys via CloudFormation and waits for completion
Displays stack outputs
Reminds user to delete the test stack

Output:

reports/<sg-name>-test-deploy-YYYYMMDD_HHMMSS_mmm.log

Cleanup: Delete the test stack when done:

aws cloudformation delete-stack --stack-name <test-stack-name> --region us-west-2

create-security-groups¶

Deploys security groups to AWS via CloudFormation.

Purpose: Production deployment of security groups.

AWS Credentials: Required.

Requires: --force flag.

Command:

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act create-security-groups \
  --force

What It Does:

Reads the CloudFormation template from disk
Provisions security groups through CloudFormation
Stores stack outputs in SSM Parameter Store (/sg/<sg-name>/<tier>/SecurityGroupId)
- e.g., /sg/globalbank-prod-c001-us-west-2-sg/web/SecurityGroupId
Generates deployment report

Output:

reports/<sg-name>-post-deployment-YYYYMMDD_HHMMSS.html
reports/<sg-name>-create-security-groups-YYYYMMDD_HHMMSS_mmm.log

show-changes¶

Previews pending changes without applying them.

Purpose: Review what would change in the deployed stack.

AWS Credentials: Required (deployed stack must exist).

Command:

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act show-changes

How It Works:

Checks the stack exists
Reads the CloudFormation template from disk
Creates a temporary ChangeSet
Waits for ChangeSet creation
Displays pending resource changes (Add, Modify, Remove) — or reports “No changes detected”
Deletes the ChangeSet (no changes applied)

Output:

reports/<sg-name>-show-changes-YYYYMMDD_HHMMSS_mmm.log

check-drift¶

Detects infrastructure drift between the deployed stack and its template.

Purpose: Identify resources modified outside of CloudFormation.

AWS Credentials: Required (deployed stack must exist).

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act check-drift

What It Detects:

Security group rules added/removed manually
Tags modified outside CloudFormation
Security group descriptions changed

How It Works:

Checks the stack exists
Initiates CloudFormation drift detection
Polls until detection is complete
Reports per-resource drift details (property path, expected vs actual value)

Output:

reports/<sg-name>-check-drift-YYYYMMDD_HHMMSS_mmm.log

delete-security-groups¶

Deletes the CloudFormation stack and all security groups.

Purpose: Complete cleanup of deployed security groups.

AWS Credentials: Required.

Requires: --force flag.

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act delete-security-groups \
  --force

What It Does:

Deletes CloudFormation stack and waits for completion
Removes SSM parameters under /sg/<sg-name>/

Output:

reports/<sg-name>-delete-security-groups-YYYYMMDD_HHMMSS_mmm.log

Command Summary¶

Action	AWS Creds	–force	Purpose
validate-config	✅	❌	Validate YAML
list-scenarios	✅	❌	List available scenarios
show-scenario	✅	❌	Display scenario details
create-policy	✅	❌	Generate IAM policy
create-prov-template	✅	❌	Generate CFN template
validate-prov-template	✅	❌	Validate CFN template locally
create-review-report	✅	❌	Generate review report
test-deploy	✅	❌	Safe test deployment
create-security-groups	✅	✅	Deploy security groups
show-changes	✅	❌	Preview pending changes
check-drift	✅	❌	Detect drift
delete-security-groups	✅	✅	Delete all SGs and stack

Common Workflows¶

Complete Deployment¶

Full end-to-end workflow from validation to production deployment.

# 1. 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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml -act validate-config

# 2. Review scenario
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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml -act show-scenario

# 3. 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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml -act create-policy

# 4. Generate and review 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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml -act create-prov-template

# 5. Validate 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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml -act validate-prov-template

# 6. Generate 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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml -act create-review-report

# 7. Test deploy
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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml -act test-deploy

# 8. Preview changes before production deploy
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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml -act show-changes

# 9. Deploy to production
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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml -act create-security-groups --force

# 10. Verify no drift after deployment
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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml -act check-drift

Quick Test¶

Validate and generate artifacts without deploying to AWS.

# Validate + generate template + 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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml -act validate-config

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml -act create-prov-template

# Review generated template
cat sg/templates/globalbank-prod-c001-us-west-2-sg-template.yaml

Cleanup¶

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml -act delete-security-groups --force

Multi-Workload Deployment¶

Deploy multiple SG sets in the same VPC using the workload discriminator.

# Deploy fraud workload SGs
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 \
  -con globalbank-prod-c001-us-west-2-fraud-sg.yaml -act create-security-groups --force

# Deploy payments workload SGs
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 \
  -con globalbank-prod-c001-us-west-2-payments-sg.yaml -act create-security-groups --force

Each workload gets its own CloudFormation stack and SSM parameters with no naming collisions.

Volume Mounts¶

Mount	Container Path	Purpose	Required For
`$(pwd)/sg/configs`	`/app/configs`	Input configuration files	All actions
`$(pwd)/sg/policies`	`/app/policies`	Generated IAM policies	create-policy
`$(pwd)/sg/templates`	`/app/templates`	CloudFormation templates	create-prov-template, validate-prov-template, create-review-report, create-security-groups, show-changes
`$(pwd)/sg/reports`	`/app/reports`	Execution logs and HTML reports	All actions (recommended)
`~/.aws`	`/home/sguser/.aws`	AWS credentials	All actions requiring AWS access

Mount flags:

:ro — read-only (use for configs and credentials)
No flag — read-write (use for policies, templates, reports where tool writes output)

Example with all mounts:

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/templates:/app/templates \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act create-security-groups --force

AWS Credentials¶

Option 1: AWS Profile (Recommended)¶

Mount your ~/.aws directory containing credentials and config files.

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 \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act create-security-groups --force

Option 2: Environment Variables¶

Pass credentials as environment variables.

docker run --rm \
  -e AWS_ACCESS_KEY_ID=AKIA... \
  -e AWS_SECRET_ACCESS_KEY=wJal... \
  -e AWS_DEFAULT_REGION=us-west-2 \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act create-security-groups --force

Option 3: IAM Role (EC2/ECS)¶

When running on EC2 or ECS with an IAM role attached, no manual credential configuration is needed. The AWS SDK inside the container automatically uses the instance/task role.

docker run --rm \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  -con globalbank-prod-c001-us-west-2-sg.yaml \
  -act create-security-groups --force

Best Practices¶

Always validate first — Run validate-config before any AWS operations.
Review templates — Inspect the generated CloudFormation template before deploying.
Generate review report — Run create-review-report and share with stakeholders before deploying to production.
Test before production — Use test-deploy or deploy to a dev environment first.
Use Parameter Store for VPC ID — Decouples SG provisioning from VPC deployment.
Use workload discriminator — Avoid naming collisions when deploying multiple SG sets.
Keep overrides minimal — For fundamentally different architectures, create a new scenario.
Use IAM roles over access keys in production.
Monitor drift — Run check-drift periodically to detect manual changes.
Version control configs — Store configuration files in Git for audit trail.
Mount reports — Always mount the reports directory to capture logs for troubleshooting.

FAQ¶

Q: Can I modify the generated CloudFormation template? A: Yes, but changes are overwritten on next create-prov-template. Use configuration overrides instead.

Q: What happens if deployment fails? A: CloudFormation automatically rolls back. Check stack events and the log file in reports/ for details.

Q: Can I deploy multiple SG sets to the same VPC? A: Yes — use the workload field to create separate named SG sets (e.g., fraud, payments).

Q: How do I upgrade to a new version? A: Pull the latest Docker image. Existing deployed security groups are not affected unless you redeploy.

Q: What if the VPC doesn’t exist yet? A: Deploy the VPC first using the VPC Provisioner, or use vpc_source: direct with an existing VPC ID.

Q: How do I delete everything? A: Use delete-security-groups --force to remove the CloudFormation stack, all security groups, and SSM parameters.

Q: Can I deploy to multiple regions? A: Yes, create separate configuration files per region and run the tool for each.

Q: What’s the difference between test-deploy and create-security-groups? A: test-deploy appends a random suffix to avoid collisions with production. create-security-groups deploys with the real names.

Additional Resources¶

Configuration Reference — Complete configuration reference
Scenarios Reference — Scenario details and customization
IAM Permissions — Required AWS permissions
Troubleshooting — Common issues and solutions
Security Guidelines — Security best practices

See LICENSE.txt for terms and conditions.