Application Architecture

System architecture documentation for the SEC Provisioner.

Table of Contents

Introduction and Context

Purpose

The SEC Provisioner is a config-driven IAM provisioning tool that manages AWS IAM groups, roles, and policies via CloudFormation. It transforms a single YAML configuration file into a complete IAM security infrastructure deployed as a single CloudFormation stack.

Problem Statement

Setting up IAM infrastructure for ML teams is complex, error-prone, and time-consuming:

  • Multiple groups with overlapping but distinct permissions

  • Service roles with trust policies for SageMaker, Lambda, Glue, CodeBuild

  • Cross-function assumable roles for temporary access elevation

  • Cross-account roles for CI/CD pipelines and monitoring

  • Least-privilege policies scoped to specific AWS services and actions

  • Consistency across dev/staging/prod environments

Solution

A tiered, config-driven approach where:

  • All IAM resources are defined in a single YAML configuration

  • Pre-built policy templates provide least-privilege access for 9 AWS service categories

  • Three tiers (startup/medium/enterprise) offer progressive feature availability

  • CloudFormation manages the entire lifecycle as a single stack

  • Export actions enable review and audit before deployment

Scope

The SEC Provisioner manages:

  • IAM Groups with inline policies and managed policy attachments

  • Service Roles for AWS services (SageMaker, Lambda, Glue, CodeBuild, CI/CD)

  • Assumable Roles (cross-function mirrors and elevation roles)

  • Cross-Account Roles with external ID verification

  • Standalone Managed Policies from policy templates

  • SSM Parameter Store entries for cross-provisioner discovery

It does not manage:

  • IAM Users (users are added to groups manually or via external tooling)

  • AWS Organizations or SCPs

  • VPC or S3 infrastructure (handled by VPC and S3 Provisioners)

Architectural Representation

System Context

┌──────────────────────────────────────────────────────┐
│                    Client Host                       │
│                                                      │
│  configs/          Docker Container                  │
│  ┌──────────┐      ┌───────────────────────────────┐ │
│  │ YAML     │────▶ │  SEC Provisioner              │ │
│  │ Config   │      │  ┌────────┐   ┌─────────────┐ │ │
│  └──────────┘      │  │ CLI    │─▶ │ SecManager  │ │ │
│                    │  └────────┘   └──────┬──────┘ │ │
│  policies/         │                      │        │ │
│  ┌──────────┐◀──── │  ┌──────────────────┐│        │ │
│  │ JSON     │      │  │ Policy Templates ││        │ │
│  └──────────┘      │  └──────────────────┘│        │ │
│                    │                      ▼        │ │
│  templates/        │              ┌──────────────┐ │ │
│  ┌──────────┐◀──── │              │ CFN Template │ │ │
│  │ YAML     │      │              └─────┬────────┘ │ │
│  └──────────┘      └────────────────────┼──────────┘ │
│                                         │            │
│  reports/                               ▼            │
│  ┌──────────┐                   ┌────────────┐       │
│  │ LOG/HTML │                   │ AWS APIs   │       │
│  └──────────┘                   └────────────┘       │
└──────────────────────────────────────────────────────┘

Processing Flow

YAML Config ──▶ Schema Validation ──▶ Config Parsing ──▶ Resource Generation
                                                              │
                    ┌─────────────────────────────────────────┘
                    │
                    ▼
              ┌───────────┐     ┌───────────┐     ┌───────────┐
              │ Policies  │     │ Roles     │     │ Groups    │
              │ (31 YAML  │     │ (service, │     │ (inline   │
              │ templates)│     │ assumable,│     │ policies, │
              └─────┬─────┘     │ xacct)    │     │ role ARNs)│
                    │           └─────┬─────┘     └─────┬─────┘
                    │                 │                 │
                    ▼                 ▼                 ▼
              ┌─────────────────────────────────────────────┐
              │         CloudFormation Template             │
              │  (single YAML with all IAM resources)       │
              └──────────────────┬──────────────────────────┘
                                 │
                    ┌────────────┼────────────┐
                    ▼            ▼            ▼
              TemplateBody   S3 Upload    ChangeSet
              (startup)     (med/ent)    (show-changes)
                    │            │
                    ▼            ▼
              ┌─────────────────────┐
              │  CloudFormation     │
              │  Stack Deploy       │
              └─────────┬───────────┘
                        │
                        ▼
              ┌─────────────────────┐
              │  SSM Parameter      │
              │  Store              │
              └─────────────────────┘

Technical Strategy and Decisions

Single Stack Architecture

All IAM resources are managed in a single CloudFormation stack per environment. This ensures:

  • Atomic deployment — all resources created or none

  • Consistent rollback on failure

  • Single point of management for drift detection

  • Simplified cleanup via stack deletion

Config-Driven Design

The YAML configuration is the single source of truth. The code generates all resources from the config — no hardcoded resource definitions. This enables:

  • Customization without code changes

  • Tier-specific schemas for validation

  • Reproducible deployments across environments

Policy Template System

Pre-built YAML policy templates (31 files across 9 service categories) provide least-privilege access patterns. Benefits:

  • Audited and tested policy definitions

  • Consistent permission levels across deployments

  • Placeholder substitution for tenant-scoped resources (${company_prefix}, ${env}, ${tenant_id})

  • New services added by dropping YAML files into policy-templates/

Tiered Access Control

Three tiers with build-time injection:

  • Startup-5: 5 groups, 4 service roles, 1 assumable role, 0 cross-account roles

  • Medium-10: 10 groups, 5 service roles, 6 assumable roles, 1 cross-account role

  • Enterprise-12: 12 groups, 5 service roles, 7 assumable roles, 2 cross-account roles

The tier is injected into app_config.yaml at Docker build time via sed in the Makefile. The same codebase serves all tiers — the security profile in the config controls which resources are enabled.

Template Size Strategy

  • Startup: Template < 51,200 bytes → deployed via CloudFormation TemplateBody (inline)

  • Medium/Enterprise: Template > 51,200 bytes → uploaded to S3, deployed via TemplateURL

This is handled automatically based on template size at deploy time.

Cython Compilation

Core modules are compiled to .so files via Cython for:

  • Source code protection in commercial distribution

  • Modest performance improvement for template generation

  • IP protection for policy generation logic

Compiled modules: sec_manager.py, loader.py, validator.py, html_generator.py

Component Architecture

Package Structure

sec_provisioner/
├── cli.py                  # CLI entry point (SecProvisionerCLI)
├── __main__.py             # Module entry point
├── __init__.py
├── config/
│   ├── loader.py           # AppConfig class, load_app_config()
│   └── app_config.yaml     # Embedded app configuration (tier injected at build)
├── core/
│   └── sec_manager.py      # SecManager — all business logic (2,960 lines)
├── license/
│   └── validator.py        # AWS Marketplace license validation
└── utils/
    └── html_generator.py   # HTML report generation (template + deployment + policy)

Supporting Assets

schemas/                    # Tier-specific JSON schemas
├── validation-schema-startup.yaml
├── validation-schema-medium.yaml
└── validation-schema-enterprise.yaml

policy-templates/           # 31 pre-built IAM policy templates
├── s3/                     # level1, level2, level3
├── ecr/                    # level1, level2, level3
├── sagemaker/              # level1, level1-prod, level2, level3, level4-ci
├── pipeline/               # level1, level2, level3
├── lambda/                 # level1, level2
├── bedrock/                # level1, level2
├── kms/                    # level1
├── trusted-advisor/        # level1
└── combined/               # ops-services-read-only, mlops-services-a/b/c

Shared Common Module

common/
├── cli/
│   └── base_cli.py         # BaseCLI — argument parsing, error handling
├── logger/                 # Structured logging
├── utils/
│   ├── aws_helpers.py      # AWS client initialization, credential validation
│   ├── aws_retry.py        # Retry logic for AWS API calls
│   ├── class_helpers.py    # Utility functions
│   ├── config_helpers.py   # Config loading utilities
│   ├── dry_run_helpers.py  # Dry-run simulation
│   └── timing_helpers.py   # Operation timing
└── validation/             # Schema validation

SecManager Class

The SecManager class (2,960 lines) is the core business logic. Key method groups:

Initialization:

  • __init__ — config loading, schema validation, AWS client setup

  • _load_and_validate_config_early — YAML parsing and schema validation

  • _flatten_config_to_attributes — config dict → instance attributes

  • _ensure_aws_access — AWS credential and connectivity validation

Resource Generation:

  • _generate_iam_groups → _generate_iam_group — group with inline policies + assumable role ARNs

  • _generate_service_roles → _generate_service_role — role with trust policy + managed policies

  • _generate_cross_function_roles — roles that mirror group policies via mirrors_group

  • _generate_elevation_roles — roles with custom IAM permissions

  • _generate_cross_account_roles → _generate_cross_account_role — roles with external ID

  • _generate_service_policies — standalone managed policies from templates

  • _generate_prov_template — orchestrates all generators into single CFN template

  • _generate_outputs — CloudFormation outputs for all resources

Export Actions:

  • _export_iam_policy — operator IAM policy scoped to config

  • _export_service_policies — service policy JSONs

  • _export_iam_groups — group definition JSONs

  • _export_service_roles, _export_cross_function_roles, _export_elevation_roles, _export_cross_account_roles — role JSONs

Infrastructure Operations:

  • _create_prov_template_file — generate and save CFN template

  • _validate_prov_template — local template validation (YAML, refs, structure)

  • _show_changes — CloudFormation ChangeSet preview

  • _check_drift — drift detection against deployed stack

  • _test_deploy — deploy with random suffix

  • _deploy — production deployment + SSM parameter storage

  • _delete_stack — stack deletion + SSM parameter cleanup

Action Dispatch:

  • _execute_action — maps action strings to method calls

  • execute — top-level entry point called by CLI

Data Architecture

Input Data

Configuration File (YAML):

  • 6 top-level sections: tier, client, environment, deployment, security, tags

  • Security section contains: iam_groups, service_roles, assumable_roles, cross_account_roles, security_profiles

  • Validated against tier-specific JSON schema

Policy Templates (YAML):

  • 31 files across 9 service directories

  • Each defines an IAM policy document with placeholder variables

  • Placeholders: ${company_prefix}, ${env}, ${tenant_id}, ${account_id}, ${region}

Output Data

CloudFormation Template (YAML):

  • Single template containing all IAM resources

  • Startup: ~30KB (TemplateBody compatible)

  • Medium: ~69KB (requires S3 upload)

  • Enterprise: ~85KB (requires S3 upload)

Exported JSON Files:

  • IAM policy: {stem}-iam-policy.json

  • Service policies: {prefix}-policy-{service}-{level}.json

  • Groups: {prefix}-group-{name}.json

  • Roles: {prefix}-role-{name}.json or {prefix}-xacct-{name}.json

Reports:

  • Log files: {stem}-{action}-{timestamp}.log

  • HTML reports: template documentation, deployment results, policy documentation

SSM Parameters:

  • Path: /security/{stem}/{output_key}

  • Contains ARNs for all deployed resources

  • Enables cross-provisioner resource discovery

Naming Conventions

All resource names derive from the stem: {company_prefix}-{env}-{tenant_id}-{region}-{tier_name}-sec

Example stem: edge-prod-b001-us-west-1-medium-sec

Resource Type

Pattern

Example

Stack

{stem}-stack

edge-prod-b001-us-west-1-medium-sec-stack

Group

{prefix}-{env}-{tenant_id}-group-{name}

edge-prod-b001-group-data-scientists

Service Role

{prefix}-{env}-{tenant_id}-role-{name}

edge-prod-b001-role-sagemaker-execution

Assumable Role

{prefix}-{env}-{tenant_id}-role-{name}

edge-prod-b001-role-aml-engineer

Cross-Account Role

{prefix}-{env}-{tenant_id}-xacct-{name}

edge-prod-b001-xacct-deployment-role

Managed Policy

{prefix}-{env}-{tenant_id}-policy-{service}-{level}

edge-prod-b001-policy-s3-level2-project-buckets-only

See NAMING_CONVENTIONS.md for complete naming reference.

Security Architecture

Container Security

  • Non-root user: secuser (UID 1000)

  • No exposed ports: container has no network listeners

  • Health check: configured for orchestrator compatibility

  • Multi-stage build: builder stage discarded, minimal runtime image

  • Cython compilation: core modules compiled to .so — source code not included in image

  • Read-only config mount: configs mounted with :ro flag

IAM Security Model

Least Privilege:

  • 31 policy templates with scoped permissions per service and level

  • Resource ARNs scoped to tenant: arn:aws:s3:::{prefix}-{env}-{tenant_id}-*

  • No wildcard resources except where AWS requires it (IAM global actions)

Separation of Concerns:

  • Groups define team membership and permission boundaries

  • Service roles define what AWS services can do

  • Assumable roles provide temporary cross-function access

  • Cross-account roles isolate external access with external ID verification

Audit Trail:

  • All assumable role usage logged via CloudTrail (sts:AssumeRole)

  • SSM parameters provide discoverable resource inventory

  • Export actions enable pre-deployment security review

  • HTML reports document deployed configuration

Credential Handling

  • AWS credentials mounted read-only from host

  • No credentials stored in the container image

  • License validation uses AWS Marketplace API (requires credentials)

  • Environment variable credentials supported but discouraged

Deployment Architecture

Docker Image Structure

/app/
├── sec_provisioner/        # Compiled application code (.so + .py)
├── common/                 # Shared library
├── schemas/                # Tier-specific validation schemas
├── policy-templates/       # 31 IAM policy YAML templates
├── templates/              # Pre-generated sample templates
├── configs/                # Master config templates per tier
├── docs/                   # Sphinx HTML documentation
├── entrypoint.sh           # Container entry point
├── configs/                # Mount point for client configs
├── policies/               # Mount point for exported policies
├── groups/                 # Mount point for exported groups
├── roles/                  # Mount point for exported roles
├── templates/              # Mount point for generated templates
└── reports/                # Mount point for logs and reports

Build Pipeline

Source Code ──▶ Cython Compile ──▶ Docker Build ──▶ Docker Image
                (.py → .so)       (multi-stage)    (sec-provisioner:<tier>)
                                       │
                                  Tier Injection
                                  (sed → app_config.yaml)

The Makefile:

  1. Injects tier into app_config.yaml via sed

  2. Compiles Python to .so via Cython

  3. Builds Docker image with multi-stage build (uv dependency install → slim runtime)

  4. Restores app_config.yaml after build

  5. Tags image as sec-provisioner:<tier> (e.g., startup-5, medium-10, enterprise-12)

CloudFormation Deployment

Startup Tier:

Config → Template Generation → TemplateBody → CloudFormation CreateStack

Medium/Enterprise Tiers:

Config → Template Generation → S3 Upload → TemplateURL → CloudFormation CreateStack

Post-deployment:

Stack Outputs → SSM Parameter Store (/security/{stem}/*)

Quality Attributes

Reliability

  • Schema validation: Config validated against tier-specific schema before any processing

  • Template validation: Local validation of YAML syntax, required keys, and reference integrity

  • Test deploy: Isolated test deployment with random suffix before production

  • Atomic deployment: CloudFormation ensures all-or-nothing resource creation

  • Automatic rollback: CloudFormation rolls back on any resource creation failure

Maintainability

  • Single source of truth: YAML config drives all resource generation

  • Policy templates: New services added by dropping YAML files — no code changes

  • Shared common module: CLI, logging, AWS helpers shared across all 3 provisioners

  • Consistent patterns: All provisioners follow the same architecture (CLI → Manager → CloudFormation)

Testability

  • Export actions: Review all generated resources as JSON before deployment

  • Test deploy: Full stack deployment with isolated resource names

  • Dry-run mode: Simulate operations without AWS calls

  • Template validation: Catch errors locally before deployment

Security

  • Least privilege: Scoped policies per service and level

  • No hardcoded credentials: All credentials from host mount or instance role

  • Cython compilation: Source code protection

  • Non-root container: Runs as secuser

Portability

  • Docker-based: Runs on any system with Docker

  • No host dependencies: All dependencies bundled in image

  • Multi-platform: Python 3.13-slim base image

Integration Architecture

Cross-Provisioner Integration

The SEC Provisioner integrates with the S3 and VPC Provisioners via SSM Parameter Store:

S3 Provisioner ──▶ S3 Bucket ──▶ SEC Provisioner (template upload)
                                        │
                                        ▼
                                  SSM Parameters
                                        │
                                        ▼
                              VPC Provisioner (reads role ARNs)

S3 → SEC: Medium and enterprise tiers upload templates to the S3 bucket created by the S3 Provisioner. The deployment.template_bucket config field references this bucket.

SEC → SSM: After deployment, all stack outputs (group ARNs, role ARNs, policy ARNs) are stored in SSM Parameter Store under /security/{stem}/.

SSM → Other Provisioners: Other provisioners can discover SEC resources by reading SSM parameters — for example, retrieving a SageMaker execution role ARN for use in a training pipeline.

AWS Service Integration

AWS Service

Usage

CloudFormation

Stack lifecycle (create, update, delete, drift, changeset)

IAM

Groups, roles, policies (managed by CloudFormation)

S3

Template upload for medium/enterprise tiers

SSM Parameter Store

Stack output storage for cross-provisioner discovery

STS

Credential validation, caller identity

AWS Marketplace

License validation

Operational Architecture

Action Safety Levels

Level

Actions

AWS Impact

Local

validate-config, export-iam-policy, export-service-policies, export-groups, export-roles, create-prov-template, validate-prov-template

None (local file operations only)

Read-only

show-changes, check-drift

Read-only AWS calls (ChangeSet, drift detection)

Mutating

test-deploy, deploy, delete-stack

Creates/modifies/deletes AWS resources

Logging

  • All actions produce log files in reports/

  • Log format: {stem}-{action}-{timestamp}.log

  • Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL (configurable via --verbose)

  • HTML reports generated for template creation, deployment, and policy documentation

Error Handling

  • Config errors: Caught during schema validation (before any AWS calls)

  • Template errors: Caught during local validation (before deployment)

  • AWS errors: Caught and logged with error code and message

  • Stack failures: CloudFormation automatic rollback with event logging

  • Fatal errors: Caught by BaseCLI with exit code 1

Monitoring

  • Drift detection: check-drift identifies resources modified outside CloudFormation

  • Change preview: show-changes shows pending modifications before applying

  • SSM parameters: Provide discoverable inventory of deployed resources

  • CloudFormation events: Full audit trail of stack operations