User Guide¶

Complete reference for all commands and features.

Table of Contents¶

Quick Start
Security Scanning
Configuration
Commands Reference
Command Summary
Common Workflows
Volume Mounts
AWS Credentials
Best Practices

Quick Start¶

Pre-Deployment Checklist¶

Before deploying, ensure you have:

Docker 20.10+ installed and running (docker --version)
AWS credentials configured (aws sts get-caller-identity works)
AWS Marketplace subscription active for SEC Provisioner
IAM permissions verified (see IAM_PERMISSIONS.md)
Configuration file created and validated
S3 bucket exists for template upload (medium and enterprise tiers)
Security profile in config matches Docker image tier
Reviewed exported groups, roles, and policies
Tested in dev/staging environment first

1. Create Directories and Copy Documentation¶

cd ~
mkdir -p mlops-infra-suite/sec/{configs,policies,groups,roles,templates,reports}
cd mlops-infra-suite
mkdir -p sec/docs

# Copy docs from Docker image to host
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/docs:/output \
  --entrypoint cp \
  sec-provisioner:medium-10 \
  -r /app/docs/. /output/

ls sec/docs/

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

└── mlops-infra-suite
    └── sec
        ├── configs
        ├── docs
        │   ├── _sources/
        │   ├── _static/
        │   ├── index.html
        │   ├── USER_GUIDE.html
        │   ├── TIER_COMPARISON.html
        │   ├── POLICY_GUIDE.html
        │   ├── ROLES_ARCHITECTURE.html
        │   ├── NAMING_CONVENTIONS.html
        │   ├── IAM_PERMISSIONS.html
        │   ├── SECURITY.html
        │   ├── RELEASE_NOTES.html
        │   └── ...
        ├── groups
        ├── policies
        ├── reports
        ├── roles
        └── templates

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

2. Copy Master Config Template¶

Copy the master config template for your tier from the Docker image:

# Copy medium tier master config
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/output \
  --entrypoint cp \
  sec-provisioner:medium-10 \
  /app/configs/medium-master-config.yaml /output/

Rename and customize for your organization:

cp sec/configs/medium-master-config.yaml sec/configs/edge-prod-b001-us-west-1-sec.yaml

Edit the file and update the client, environment, deployment, and tags sections with your values:

client:
  company_name: Your Company
  company_prefix: yourco
  account_id: "123456789012"
  tenant_id: "a001"

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

deployment:
  template_bucket: yourco-prod-a001-us-west-1-s3
  template_prefix: solutions/master-solution/templates

tags:
  cost_center: Engineering
  project: ML-Platform
  owner: your-team

The security section contains pre-configured groups, roles, and policies for your tier. Review and adjust as needed.

3. Validate Configuration¶

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action validate-config

4. Export and Review IAM Policy¶

Generate the operator IAM policy and attach it to your IAM user/role before deploying:

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/policies:/app/policies \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action export-iam-policy

# Review the generated policy
cat sec/policies/edge-prod-b001-us-west-1-medium-sec-iam-policy.json

5. Review Groups, Roles, and Policies¶

Export all definitions for review before deployment:

# Export groups, roles, and service policies
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/groups:/app/groups \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action export-groups

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/roles:/app/roles \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action export-roles

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/policies:/app/policies \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action export-service-policies

# Review exported files
ls sec/groups/ sec/roles/ sec/policies/

6. Generate and Validate Template¶

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/templates:/app/templates \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action create-prov-template

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/templates:/app/templates \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action validate-prov-template

7. Test Deploy (Optional but Recommended)¶

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action test-deploy

# Delete test stack after verification
# aws cloudformation delete-stack --stack-name <test-stack-name> --region us-west-1

8. Deploy to Production¶

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action deploy \
  --force

9. Verify Deployment¶

# Check CloudFormation stack
aws cloudformation describe-stacks \
  --stack-name edge-prod-b001-us-west-1-medium-sec-stack \
  --region us-west-1 \
  --query 'Stacks[0].StackStatus'

# Check IAM groups created
aws iam list-groups --query 'Groups[?starts_with(GroupName, `edge-prod-b001`)].GroupName'

# Check IAM roles created
aws iam list-roles --query 'Roles[?starts_with(RoleName, `edge-prod-b001`)].RoleName'

# Check SSM parameters
aws ssm get-parameters-by-path \
  --path /security/edge-prod-b001-us-west-1-medium-sec/ \
  --region us-west-1 \
  --query 'Parameters[].Name'

10. Expected Output Files¶

After running the complete workflow, your directory structure will contain:

sec/
├── configs/
│   └── edge-prod-b001-us-west-1-sec.yaml
├── groups/
│   ├── edge-prod-b001-group-data-scientists.json
│   ├── edge-prod-b001-group-ml-engineers.json
│   └── ... (10 group files for medium tier)
├── policies/
│   ├── edge-prod-b001-us-west-1-medium-sec-iam-policy.json
│   ├── edge-prod-b001-policy-s3-level2-project-buckets-only.json
│   └── ... (22 service policy files for medium tier)
├── reports/
│   ├── edge-prod-b001-us-west-1-medium-sec-validate-config-20260404_141022_385.log
│   ├── edge-prod-b001-us-west-1-medium-sec-create-prov-template-20260404_141405_187.log
│   ├── edge-prod-b001-us-west-1-medium-sec-create-prov-template-20260404_141405_187.html
│   ├── edge-prod-b001-us-west-1-medium-sec-deploy-20260404_142005_823.log
│   ├── edge-prod-b001-us-west-1-medium-sec-deployment-20260404_142005.html
│   └── ...
├── roles/
│   ├── edge-prod-b001-role-sagemaker-execution.json
│   ├── edge-prod-b001-role-aml-engineer.json
│   ├── edge-prod-b001-xacct-deployment-role.json
│   └── ... (12 role files for medium tier)
└── templates/
    └── edge-prod-b001-us-west-1-medium-sec-template.yaml

Note: Replace sec-provisioner:medium-10 with sec-provisioner:startup-5 or sec-provisioner:enterprise-12 for other tiers. See TIER_COMPARISON.md for feature differences.

Security Scanning¶

Optional: Scan Docker Image for Vulnerabilities¶

Before deploying to production, scan the Docker image for security vulnerabilities.

Prerequisites:

Docker CLI installed
(Optional) Trivy installed: brew install trivy (macOS) or see Trivy installation

Scan with Trivy:

trivy image sec-provisioner:medium-10

Scan with Docker Scout (if available):

docker scout cves sec-provisioner:medium-10

Inspect container security:

# Verify non-root user
docker inspect sec-provisioner:medium-10 --format '{{.Config.User}}'
# Expected: secuser

# Verify no exposed ports
docker inspect sec-provisioner:medium-10 --format '{{.Config.ExposedPorts}}'
# Expected: map[]

# Verify health check
docker inspect sec-provisioner:medium-10 --format '{{.Config.Healthcheck}}'

Container security features:

Non-root user (secuser)
No exposed ports
Health check configured
Multi-stage build (minimal runtime image)
Cython-compiled core modules

Note: Replace medium-10 with your tier tag (startup-5 or enterprise-12).

Configuration¶

Configuration File Structure¶

The SEC Provisioner uses a six-section YAML configuration. The example below shows the medium tier (10 groups). See POLICY_GUIDE.md for startup and enterprise tier configurations.

tier:
  name: string                  # Tier name: startup, medium, enterprise
  version: string               # Tier version (e.g., "1.0.0")
  description: string           # Human-readable tier description
  security_profile: string      # Profile name (e.g., "medium-10")

client:
  company_name: string          # Full company name
  company_prefix: string        # Short identifier (lowercase, 2-10 chars)
  account_id: "string"          # 12-digit AWS account ID (quoted)
  tenant_id: "string"           # 4-character alphanumeric identifier (quoted)

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

deployment:
  template_bucket: string       # S3 bucket for template upload (medium/enterprise)
  template_prefix: string       # S3 prefix path for templates

security:
  iam_groups:                   # IAM group definitions
    <group_name>:
      description: string
      managed_policies: []      # AWS managed policy names
      policy_assignments:       # Service policy levels
        <service>: <level>
      assumable_roles: []       # Roles this group can assume

  service_roles:                # AWS service roles
    <role_name>:
      description: string
      trust_policy: {}          # AWS service trust policy
      managed_policies: []      # AWS managed policy names
      policy_assignments:       # Service policy levels
        <service>: <level>

  assumable_roles:              # Human-assumable roles
    <role_name>:
      description: string
      mirrors_group: string     # Cross-function: mirrors a group's policies
      # OR
      custom_permissions: {}    # Elevation: custom IAM policy document

  cross_account_roles:          # Cross-account access roles
    <role_name>:
      description: string
      trusted_accounts: []      # List of trusted AWS account IDs
      external_id: string       # External ID for verification
      managed_policies: []
      custom_policies: {}

  security_profiles:            # Tier profile — controls which resources are enabled
    <profile_name>:
      description: string
      enabled_groups: []
      enabled_service_roles: []
      enabled_assumable_roles: []
      enabled_cross_account_roles: []

tags:                           # Custom tags applied to all resources
  key: value

Medium Tier Example¶

tier:
  name: medium
  version: 1.0.0
  description: Medium Master Security Definitions - 10 Groups for Growing Companies
  security_profile: medium-10

client:
  company_name: Edge Corp
  company_prefix: edge
  account_id: "123456789012"
  tenant_id: "b001"

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

deployment:
  template_bucket: edge-prod-b001-us-west-1-s3
  template_prefix: solutions/master-solution/templates

security:
  iam_groups:
    data_scientists:
      description: Data scientists with ML model development access
      managed_policies:
        - CloudWatchLogsReadOnlyAccess
      policy_assignments:
        s3: level2
        ecr: level1
        sagemaker: level2
        bedrock: level1
      assumable_roles:
        - aml_engineer
    # ... 9 more groups (see master config for full definitions)

  service_roles:
    sagemaker_execution:
      description: SageMaker execution role for ML training and inference
      trust_policy:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service: sagemaker.amazonaws.com
            Action: sts:AssumeRole
      managed_policies:
        - CloudWatchLogsFullAccess
      policy_assignments:
        ecr: level1
        s3: level2
    # ... 4 more service roles

  assumable_roles:
    aml_engineer:
      description: Cross-function role mirroring ml_engineers group
      mirrors_group: ml_engineers
    model_approver:
      description: Approve/reject models in SageMaker Model Registry
      custom_permissions:
        Version: '2012-10-17'
        Statement:
          - Sid: ModelApproval
            Effect: Allow
            Action:
              - sagemaker:UpdateModelPackage
            Resource: 'arn:aws:sagemaker:*:*:model-package/*'
    # ... 4 more assumable roles

  cross_account_roles:
    deployment_role:
      description: Cross-account deployment role for CI/CD pipelines
      trusted_accounts:
        - "123456789012"
      external_id: "deployment-external-id-12345"
      managed_policies:
        - PowerUserAccess
      custom_policies:
        deployment_permissions:
          Version: '2012-10-17'
          Statement:
            - Effect: Allow
              Action:
                - cloudformation:*
                - iam:PassRole
              Resource: '*'

  security_profiles:
    medium-10:
      description: Medium security profile for growing companies (10 groups)
      enabled_groups:
        - data_scientists
        - data_engineers
        - mlops_engineers
        - ml_engineers
        - ai_governance
        - security_team
        - business_consumers
        - platform_administrators
        - operations_support
        - qa_testing
      enabled_service_roles:
        - sagemaker_execution
        - lambda_ml_pipeline
        - codebuild_service
        - glue_etl
        - ci_cd_deployment_role
      enabled_assumable_roles:
        - aml_engineer
        - adata_scientist
        - adata_engineer
        - aqa_testing
        - model_approver
        - security_admin
      enabled_cross_account_roles:
        - deployment_role

tags:
  cost_center: Engineering
  project: ML-Platform
  owner: devops-team

Deployment Section¶

The deployment section is required for medium and enterprise tiers. These tiers generate templates larger than 51,200 bytes, which exceeds the CloudFormation TemplateBody limit. The template is uploaded to the specified S3 bucket instead.

template_bucket: The S3 bucket created by the S3 Provisioner (must exist before SEC deploy)
template_prefix: S3 key prefix where templates are stored

Startup tier uses TemplateBody directly and does not require the deployment section.

Other Tiers¶

For complete configuration examples for all three tiers, see:

POLICY_GUIDE.md — full policy reference with all service levels
TIER_COMPARISON.md — feature comparison across tiers
ROLES_ARCHITECTURE.md — roles and groups architecture

Master config templates for each tier are included in the Docker image at /app/configs/.

Commands Reference¶

All examples use sec-provisioner:medium-10. Replace with sec-provisioner:startup-5 for startup tier or sec-provisioner:enterprise-12 for enterprise tier.

Validation Commands¶

validate-config¶

Validates configuration file against the tier-specific schema.

Purpose: Verify YAML syntax and schema compliance before deployment

Command:

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action validate-config

Output:

Report in console
File reports/{stem}-validate-config-{timestamp}.log
- e.g., edge-prod-b001-us-west-1-medium-10-sec-validate-config-20260403_141022_385.log

Export Commands¶

export-iam-policy¶

Generates IAM policy JSON file with permissions required to operate the SEC Provisioner (deploy stacks, manage IAM resources).

Purpose: Create IAM policy document for the operator running the tool

Command:

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/policies:/app/policies \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action export-iam-policy

Output:

File policies/{stem}-iam-policy.json
- e.g., edge-prod-b001-us-west-1-medium-10-sec-iam-policy.json
File reports/{stem}-export-iam-policy-{timestamp}.log
- e.g., edge-prod-b001-us-west-1-medium-10-sec-export-iam-policy-20260403_141105_712.log

Use Case: Attach generated policy to the IAM user/role that will run deploy and delete-stack actions.

export-service-policies¶

Exports service role policy definitions as individual JSON files.

Purpose: Review and audit the policies that will be attached to service roles (SageMaker, Lambda, Glue, etc.)

Command:

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/policies:/app/policies \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action export-service-policies

Output:

Files in policies/ — one JSON per service policy
- e.g., edge-prod-b001-sec-policy-s3-level2.json
File reports/{stem}-export-service-policies-{timestamp}.log
- e.g., edge-prod-b001-us-west-1-medium-10-sec-export-service-policies-20260403_141203_448.log

export-groups¶

Exports IAM group definitions as JSON files.

Purpose: Review group configurations, policy assignments, and assumable role mappings before deployment

Command:

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/groups:/app/groups \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action export-groups

Output:

Files in groups/ — one JSON per IAM group
- e.g., edge-prod-b001-group-data_scientists.json
File reports/{stem}-export-groups-{timestamp}.log
- e.g., edge-prod-b001-us-west-1-medium-10-sec-export-groups-20260403_141245_921.log

export-roles¶

Exports all IAM role definitions as JSON files — service roles, cross-function roles, elevation roles, and cross-account roles.

Purpose: Review role configurations, trust policies, and permission attachments before deployment

Command:

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/roles:/app/roles \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action export-roles

Output:

Files in roles/ — one JSON per IAM role
- e.g., edge-prod-b001-role-sagemaker_execution.json
File reports/{stem}-export-roles-{timestamp}.log
- e.g., edge-prod-b001-us-west-1-medium-10-sec-export-roles-20260403_141312_553.log

CloudFormation Template Commands¶

create-prov-template¶

Generates CloudFormation template for IAM resource provisioning.

Purpose: Create infrastructure-as-code template for groups, roles, and policies

Command:

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/templates:/app/templates \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action create-prov-template

Output:

File templates/{stem}-template.yaml
- e.g., edge-prod-b001-us-west-1-medium-10-sec-template.yaml
File reports/{stem}-create-prov-template-{timestamp}.log
- e.g., edge-prod-b001-us-west-1-medium-10-sec-create-prov-template-20260403_141405_187.log
File reports/{stem}-create-prov-template-{timestamp}.html
- e.g., edge-prod-b001-us-west-1-medium-10-sec-create-prov-template-20260403_141405_187.html

Template Includes:

IAM Groups with inline policies
Service Roles with trust policies and managed policy attachments
Assumable Roles (cross-function and elevation)
Cross-Account Roles with external ID verification
Standalone Managed Policies from policy templates
Stack outputs for cross-provisioner integration
Tags (system + custom)

validate-prov-template¶

Validates the generated CloudFormation template locally without making any AWS calls.

Purpose: Catch template errors early — YAML syntax, required keys, and internal reference integrity

Command:

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/templates:/app/templates \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action validate-prov-template

Output:

Report in console (template size, resource count, output count)
File reports/{stem}-validate-prov-template-{timestamp}.log
- e.g., edge-prod-b001-us-west-1-medium-10-sec-validate-prov-template-20260403_141502_634.log

What It Checks:

YAML syntax is valid
Required top-level keys present (AWSTemplateFormatVersion, Resources)
All !Ref and !GetAtt targets resolve to parameters or resources within the template

Note: If the template file does not exist, it will be generated automatically.

Change Preview and Drift Detection Commands¶

show-changes¶

Previews what would change in the deployed stack without applying any modifications.

Purpose: Review pending changes before updating infrastructure

Command:

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/templates:/app/templates \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action show-changes

Output:

Report in console (list of pending resource changes)
File reports/{stem}-show-changes-{timestamp}.log
- e.g., edge-prod-b001-us-west-1-medium-10-sec-show-changes-20260403_141615_278.log

How It Works:

Creates a temporary CloudFormation ChangeSet against the deployed stack
Displays pending resource changes (Add, Modify, Remove)
Deletes the ChangeSet after display (no changes applied)

Note: Requires a deployed stack. If no stack exists, the command will report an error.

check-drift¶

Detects infrastructure drift between the deployed stack and its template.

Purpose: Identify resources that have been modified outside of CloudFormation

Command:

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action check-drift

Output:

Report in console (per-resource drift status with property-level diffs)
File reports/{stem}-check-drift-{timestamp}.log
- e.g., edge-prod-b001-us-west-1-medium-10-sec-check-drift-20260403_141722_491.log

What It Detects:

IAM group policies modified manually
Role trust policies changed outside CloudFormation
Managed policy attachments altered
Tags modified or removed

Note: Requires a deployed stack. If no stack exists, the command will report an error.

Deployment Commands¶

test-deploy¶

Deploys IAM infrastructure with a random test suffix for safe testing.

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

Command:

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action test-deploy

Output:

Report in console (stack outputs)
File reports/{stem}-test-deploy-{timestamp}.log
- e.g., edge-prod-b001-us-west-1-medium-10-sec-test-deploy-20260403_141830_156.log

How It Works:

Appends a random 6-character suffix to all resource names
All groups, roles, and policies inherit the test suffix — no collision with production
Generates template in-memory (not persisted to disk)
Deploys via CloudFormation with the test-suffixed stack name
Restores original names after deployment

Cleanup: Delete the test stack when done:

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

Note: This action does not require --force. Test deployments are designed to be disposable.

deploy¶

Deploys IAM infrastructure via CloudFormation stack.

Purpose: Production deployment of groups, roles, and policies

Requirements: --force flag

Command:

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action deploy \
  --force

Output:

Report in console
File reports/{stem}-deploy-{timestamp}.log
- e.g., edge-prod-b001-us-west-1-medium-10-sec-deploy-20260403_142005_823.log
File reports/{stem}-deployment-{timestamp}.html
- e.g., edge-prod-b001-us-west-1-medium-10-sec-deployment-20260403_142005.html
CloudFormation stack: {stem}-stack
- e.g., edge-prod-b001-us-west-1-medium-10-sec-stack
SSM parameters: /security/{stem}/{output_key}
- e.g., /security/edge-prod-b001-us-west-1-medium-10-sec/StackId

What It Creates:

IAM Groups with scoped inline policies
Service Roles (SageMaker, Lambda, Glue, CodeBuild, CI/CD)
Assumable Roles (cross-function mirrors + elevation roles)
Cross-Account Roles (with external ID verification)
Standalone Managed Policies from policy templates
SSM Parameter Store entries for cross-provisioner discovery

Deployment Method:

Startup tier: TemplateBody (template < 51,200 bytes)
Medium and Enterprise tiers: S3 TemplateURL (template uploaded to S3 bucket)

delete-stack¶

Deletes the CloudFormation stack and all IAM resources it manages.

Purpose: Complete removal of all provisioned IAM resources

Requirements: --force flag

Command:

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action delete-stack \
  --force

Output:

Report in console
File reports/{stem}-delete-stack-{timestamp}.log
- e.g., edge-prod-b001-us-west-1-medium-10-sec-delete-stack-20260403_142215_467.log

What It Deletes:

All IAM Groups and their inline policies
All Service Roles and their policy attachments
All Assumable Roles (cross-function and elevation)
All Cross-Account Roles
All Standalone Managed Policies
SSM Parameter Store entries
CloudFormation stack

Warning: This is a destructive operation. All IAM resources managed by the stack will be deleted. Users assigned to groups will lose their permissions immediately.

Command Summary¶

Action	AWS Creds	–force	Purpose
validate-config	❌	❌	Validate YAML against tier schema
export-iam-policy	❌	❌	Generate operator IAM policy
export-service-policies	❌	❌	Export service role policies
export-groups	❌	❌	Export group definitions
export-roles	❌	❌	Export role definitions
create-prov-template	❌	❌	Generate CFN template
validate-prov-template	❌	❌	Validate CFN template locally
show-changes	✅	❌	Preview pending changes
check-drift	✅	❌	Detect infrastructure drift
test-deploy	✅	❌	Safe test deployment
deploy	✅	✅	Production deployment
delete-stack	✅	✅	Delete stack and all resources

Common Workflows¶

All examples use sec-provisioner:medium-10. Replace with sec-provisioner:startup-5 for startup tier or sec-provisioner:enterprise-12 for enterprise tier.

Complete Deployment Workflow¶

# Step 1: Validate configuration
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action validate-config

# Step 2: Export IAM policy for the operator
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/policies:/app/policies \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action export-iam-policy

# Step 3: Review and attach the generated IAM policy to your user/role
cat sec/policies/edge-prod-b001-us-west-1-medium-sec-iam-policy.json

# Step 4: Generate CloudFormation template
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/templates:/app/templates \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action create-prov-template

# Step 5: Validate the generated template
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/templates:/app/templates \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action validate-prov-template

# Step 6: Test deploy (safe, isolated resources with random suffix)
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action test-deploy

# Step 7: Delete test stack after verification
# aws cloudformation delete-stack --stack-name <test-stack-name> --region us-west-1

# Step 8: Production deploy
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action deploy \
  --force

# Step 9: Verify in AWS Console
# - Check IAM Groups created
# - Check IAM Roles created
# - Check Managed Policies created
# - Check SSM Parameter Store entries

Review and Audit Workflow¶

Export all definitions for review before deployment:

# Export service policies
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/policies:/app/policies \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action export-service-policies

# Export group definitions
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/groups:/app/groups \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action export-groups

# Export role definitions
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/roles:/app/roles \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action export-roles

# Review exported files
ls sec/policies/
ls sec/groups/
ls sec/roles/

Day-2 Operations Workflow¶

After deployment, monitor and maintain your security infrastructure:

# Check for infrastructure drift
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action check-drift

# Preview changes before updating
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/templates:/app/templates \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action show-changes

Cleanup Workflow¶

# Delete stack and all IAM resources
docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action delete-stack \
  --force

Volume Mounts¶

Mount	Container Path	Purpose	Required For
`~/.aws/`	`/home/secuser/.aws`	AWS credentials	All actions
`configs/`	`/app/configs`	Input configuration files	All actions
`reports/`	`/app/reports`	Execution logs and HTML reports	All actions
`policies/`	`/app/policies`	Generated IAM and service policies	export-iam-policy, export-service-policies
`groups/`	`/app/groups`	Exported group definitions	export-groups
`roles/`	`/app/roles`	Exported role definitions	export-roles
`templates/`	`/app/templates`	CloudFormation templates	create-prov-template, validate-prov-template, show-changes

Example with all mounts:

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/policies:/app/policies \
  -v $(pwd)/sec/groups:/app/groups \
  -v $(pwd)/sec/roles:/app/roles \
  -v $(pwd)/sec/templates:/app/templates \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action validate-config

Notes:

Mount configs/ as read-only (:ro) — the tool never writes to configs
Mount ~/.aws/ as read-only (:ro) — credentials are only read
Output directories (policies/, groups/, roles/, templates/, reports/) must be writable — do not use :ro
Only mount the directories needed for your action to minimize container access

AWS Credentials¶

All actions require AWS credentials for license validation. Actions that interact with AWS infrastructure (show-changes, check-drift, test-deploy, deploy, delete-stack) also require permissions for CloudFormation, IAM, SSM, and S3.

Option 1: AWS Profile (Recommended)¶

Mount your AWS credentials directory:

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action deploy \
  --force

Option 2: Environment Variables¶

docker run --rm \
  -e AWS_ACCESS_KEY_ID=<access_key> \
  -e AWS_SECRET_ACCESS_KEY=<secret_key> \
  -e AWS_DEFAULT_REGION=us-west-1 \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action deploy \
  --force

Warning: Credentials are visible in process list and Docker history. Use Option 1 instead.

Option 3: IAM Role (EC2/ECS)¶

When running on EC2 or ECS with an IAM role attached, credentials are automatically available:

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action deploy \
  --force

No credential mounts or environment variables needed — the container inherits the instance role automatically.

Best Practices¶

1. Always Validate First¶

Run validate-config before any deployment:

docker run --rm \
  -v ~/.aws:/home/secuser/.aws:ro \
  -v $(pwd)/sec/configs:/app/configs:ro \
  -v $(pwd)/sec/reports:/app/reports \
  sec-provisioner:medium-10 \
  --config edge-prod-b001-us-west-1-sec.yaml \
  --action validate-config

2. Export and Review Before Deploying¶

Always export groups, roles, and policies for review before production deployment. This gives your security team a chance to audit permissions:

# Export all definitions
--action export-groups
--action export-roles
--action export-service-policies
--action export-iam-policy

# Review exported JSON files
ls sec/groups/ sec/roles/ sec/policies/

3. Test Deploy Before Production¶

Use test-deploy to validate the full stack in isolation before committing to production:

--action test-deploy
# Verify in AWS Console, then delete test stack
aws cloudformation delete-stack --stack-name <test-stack-name> --region us-west-1

4. Use show-changes Before Updating¶

When modifying an existing deployment, always preview changes first:

--action show-changes

Review the pending modifications before running deploy --force.

5. Run Drift Detection Regularly¶

Schedule periodic drift checks to catch manual IAM changes that bypass CloudFormation:

--action check-drift

If drift is detected, investigate whether the manual change should be incorporated into the config or reverted by redeploying.

6. Follow Least Privilege¶

The tier system enforces progressive access:

Startup: 5 groups with essential permissions
Medium: 10 groups with governance and security roles
Enterprise: 12 groups with FinOps and external contractor controls

Start with the lowest tier that meets your needs. Upgrade when requirements grow.

7. Protect the Platform Administrators Group¶

The platform_administrators group has AdministratorAccess. Limit membership to a small number of trusted individuals. Consider using assumable roles for temporary elevated access instead of permanent group membership.

8. Use Assumable Roles for Cross-Function Access¶

Instead of adding users to multiple groups, use assumable roles:

An ML engineer who occasionally needs data scientist access assumes the adata_scientist role
Access is temporary, auditable via CloudTrail, and doesn’t require group membership changes

9. Version Control Configurations¶

Store configuration files in Git for:

Change tracking and audit trail
Rollback capability
Peer review before deployment
Environment consistency (dev/staging/prod from same config pattern)

10. Separate Environments¶

Use separate configurations per environment with the same structure:

sec/configs/
  edge-dev-b001-us-west-1-sec.yaml
  edge-staging-b001-us-west-1-sec.yaml
  edge-prod-b001-us-west-1-sec.yaml

Each deploys an independent CloudFormation stack with isolated IAM resources.

11. Monitor Logs¶

Always mount reports/ to capture execution logs:

-v $(pwd)/sec/reports:/app/reports

Review logs after each operation. HTML reports provide visual summaries for template and deployment results.

12. Secure Cross-Account Roles¶

For cross-account roles (medium and enterprise tiers):

Always use external_id for additional verification
Limit trusted_accounts to specific account IDs — never use wildcards
Review cross-account role permissions regularly
Use the exported role JSON to audit trust policies before deployment

Frequently Asked Questions¶

Q: Can I modify the generated CloudFormation template? A: Yes, but changes will be overwritten on next create-prov-template. Use the YAML configuration to customize groups, roles, and policy assignments instead.

Q: How do I upgrade to a new version? A: Pull the latest Docker image for your tier. Existing IAM resources are not affected unless you redeploy.

Q: Can I use this with existing IAM groups and roles? A: No, this tool creates new IAM resources via CloudFormation. Existing groups and roles are not affected. See MIGRATION_GUIDE.md for migrating from manual IAM setup.

Q: What happens if deployment fails? A: CloudFormation automatically rolls back all resources. Check stack events for details. See TROUBLESHOOTING.md.

Q: Can I deploy to multiple regions? A: Yes, create separate configuration files for each region. IAM resources are global but the CloudFormation stack is regional.

Q: How much does the infrastructure cost? A: Costs include your AWS Marketplace subscription plus minimal AWS resource costs. IAM resources are free. SSM Parameter Store is free tier. S3 template storage for medium/enterprise tiers is < $0.01/month. See COST_OPTIMIZATION.md for details.

Q: How do I add users to groups? A: The tool creates groups but does not manage user membership. Add users via AWS CLI: aws iam add-user-to-group --user-name jane.doe --group-name edge-prod-b001-group-data-scientists

Q: Can I upgrade from startup to medium tier? A: Yes. Delete the startup stack, then deploy with the medium image. Your configuration carries forward — just update the tier section and add the new groups/roles. See UPDATE_PROCEDURES.md for the tier upgrade process.

Q: What’s the difference between test-deploy and deploy? A: test-deploy appends a random suffix to all resource names for safe testing. deploy creates production resources with real names. Always test first.

Q: How do I delete everything? A: Use delete-stack --force to delete the CloudFormation stack, all IAM resources, and SSM parameters. Users will lose group permissions immediately.