Application Architecture

Table of Contents

  1. Executive Summary

  2. System Context

  3. Component Architecture

  4. Key Architecture Decisions

  5. Security Architecture

  6. Deployment Architecture

Executive Summary

SG Provisioner is an enterprise-grade AWS Security Group provisioning and management tool built for cloud infrastructure teams. It automates the creation, validation, and lifecycle management of Security Groups using a scenario-based, configuration-driven approach backed by AWS CloudFormation.

Rather than requiring engineers to manually define individual firewall rules, SG Provisioner provides pre-built scenario templates for common application architectures (3-tier web, 2-tier web, database-specific variants). Engineers select a scenario, apply overrides for their specific requirements, and the tool generates a validated CloudFormation template that provisions all Security Groups with correct cross-tier references.

Key Capabilities:

  • 9 pre-built scenarios covering common 2-tier and 3-tier architectures

  • Override system for port changes and additional ingress/egress rules per tier

  • Workload discriminator for deploying multiple SG sets in the same environment

  • CloudFormation-based provisioning with automatic circular dependency resolution

  • Security validation blocking dangerous patterns (open DB ports, SSH/RDP from public)

  • Pre-deployment review reports with override highlighting

  • Post-deployment reports with real Security Group IDs

  • SSM Parameter Store integration for downstream resource discovery

  • AWS Marketplace license validation

  • Docker containerization with Cython-compiled core modules for IP protection

System Context

SG Provisioner is one of four provisioners in the mlops-infra-suite — a suite of infrastructure automation tools designed to work together to provision complete AWS environments for ML workloads.

Position in the Suite

┌───────────────────────────────────────────────┐
│              mlops-infra-suite                │
│                                               │
│  ┌─────────────────┐    ┌─────────────────┐   │
│  │ VPC Provisioner │───▶│ SG Provisioner  │   │
│  │                 │    │                 │   │
│  │ Provisions VPC, │    │ Provisions      │   │
│  │ subnets, NAT,   │    │ Security Groups │   │
│  │ route tables    │    │ per tier        │   │
│  └─────────────────┘    └────────┬────────┘   │
│                                  │            │
│  ┌─────────────────┐    ┌────────▼────────┐   │
│  │ S3 Provisioner  │    │ SEC Provisioner │   │
│  │                 │    │                 │   │
│  │ Provisions S3   │    │ Provisions IAM  │   │
│  │ buckets and     │    │ roles and       │   │
│  │ folder structure│    │ policies        │   │
│  └─────────────────┘    └─────────────────┘   │
│                                               │
└───────────────────────────────────────────────┘

Dependency Order

SG Provisioner depends on the VPC Provisioner — it requires a VPC to exist before Security Groups can be created. The typical provisioning order is:

  1. VPC Provisioner — creates VPC, subnets, gateways, stores VPC ID in SSM

  2. SG Provisioner — reads VPC ID from SSM, creates Security Groups, stores SG IDs in SSM

  3. SEC Provisioner — creates IAM roles and policies

  4. S3 Provisioner — creates S3 buckets and folder structures

SSM Parameter Store as Integration Backbone

All provisioners use AWS SSM Parameter Store as the integration backbone — each provisioner stores its outputs so downstream provisioners and application workloads can discover resources without hardcoding IDs:

/vpc/{vpc-name}/VPCId                          → consumed by SG Provisioner
/sg/{sg-name}/{tier}/SecurityGroupId           → consumed by EC2, RDS, ECS, Lambda, SageMaker
/s3/{bucket-name}/BucketName                   → consumed by application workloads
/security/{stem}/StackId                       → consumed by application workloads

External Dependencies

Service

Purpose

AWS CloudFormation

Stack-based provisioning and lifecycle management

AWS EC2

Security Group resource creation

AWS SSM Parameter Store

VPC ID resolution (input) and SG ID storage (output)

AWS Marketplace

License validation

Component Architecture

Module Overview

sg_provisioner/
├── cli.py                          # CLI entry point, action dispatch
├── __main__.py                     # Python module execution entry
│
├── config/
│   ├── loader.py (.so)             # Configuration loading and validation
│   └── app_config.yaml             # Application-level settings (dirs, timeouts)
│
├── core/
│   └── sg_manager.py (.so)         # Core orchestration and AWS operations
│
├── generators/
│   └── cfn_generator.py (.so)      # CloudFormation template generation
│
├── scenarios/
│   ├── loader.py (.so)             # Scenario loading and override application
│   └── validator.py (.so)          # Security rule validation
│
├── models/
│   ├── scenario.py                 # Scenario, Tier data models
│   └── security_group.py           # SecurityGroup, SecurityGroupRule data models
│
├── license/
│   └── validator.py (.so)          # AWS Marketplace license validation
│
└── utils/
    ├── html_generator.py (.so)     # Deployment HTML report generation
    └── review_report.py (.so)      # Pre-deployment review report generation

common/ (shared library)
├── cli/
│   └── base_cli.py                 # Base CLI with --config, --action, --force flags
├── logger/
│   └── base_logger.py              # Shared logging setup
├── utils/
│   ├── aws_helpers.py              # AWS credential verification and region validation
│   ├── aws_retry.py                # Retry logic with exponential backoff
│   ├── class_helpers.py            # Class utility functions
│   ├── config_helpers.py           # YAML configuration parsing utilities
│   ├── dry_run_helpers.py          # Dry-run mode decorator
│   └── timing_helpers.py           # Performance timing decorators
└── validation/
    └── config_validator.py         # JSON schema validation engine

Module Responsibilities

cli.py — Entry Point

  • Validates AWS Marketplace license before any action

  • Parses CLI arguments (-con, -act, --force, --verbose)

  • Instantiates SgManager and dispatches the requested action

  • Handles top-level exceptions with user-friendly messages

config/loader.py — Configuration Management

  • Loads and parses the customer YAML configuration file

  • Validates against JSON schema (schemas/validation-schema.yaml)

  • Computes derived values: SG name, stack name, log file path, template path

  • Initialises AWS clients (EC2, CloudFormation, SSM)

core/sg_manager.py — Core Orchestration

  • Central orchestrator for all 12 CLI actions

  • Manages the full SG lifecycle: validate → generate → deploy → monitor → delete

  • Handles CloudFormation stack operations with waiter pattern for async completion

  • Stores and deletes SG IDs in SSM Parameter Store

  • Generates pre-deployment and post-deployment HTML reports

generators/cfn_generator.py — CloudFormation Template Generation

  • Builds the complete CloudFormation template dict from a Scenario object

  • Generates AWS::EC2::SecurityGroup resources per tier

  • Resolves cross-tier references as standalone AWS::EC2::SecurityGroupIngress / AWS::EC2::SecurityGroupEgress resources to avoid circular dependencies

  • Generates AWS::SSM::Parameter resources to store SG IDs at deployment time

  • Builds CloudFormation Outputs and Exports per tier

scenarios/loader.py — Scenario Management

  • Loads scenario YAML files from schemas/scenarios/

  • Builds Scenario / Tier / SecurityGroup object graphs

  • Applies customer overrides: port substitutions, additional ingress/egress rules

scenarios/validator.py — Security Validation

  • Validates scenario rules before template generation

  • Blocks dangerous patterns as ERRORs: database ports open to 0.0.0.0/0 or ::/0, missing rule descriptions, references to non-existent tiers

  • Warns on risky patterns: SSH (22) or RDP (3389) open to the world

models/ — Data Models

  • Scenario, Tier — represent the scenario structure

  • SecurityGroup, SecurityGroupRule — represent individual SG rules with port/port_range, source/source_tier, destination/destination_tier fields

license/validator.py — License Validation

  • Validates AWS Marketplace product subscription before any action executes

  • Calls AWS Marketplace Metering API to verify entitlement

utils/html_generator.py — Deployment Report

  • Generates post-deployment HTML report with real SG IDs, stack outputs, and deployment metadata

utils/review_report.py — Pre-Deployment Report

  • Generates pre-deployment review YAML (templates/) and HTML (reports/) with override highlighting

Key Architecture Decisions

ADR-001: CloudFormation over Direct Boto3 Resource Creation

Decision: Use AWS CloudFormation for Security Group provisioning.

Alternatives Considered: Direct boto3 API calls for each resource.

Rationale:

  • Atomic Operations — CloudFormation treats all Security Groups as a single unit, ensuring all-or-nothing deployment

  • Automatic Rollback — Failed deployments automatically roll back to the previous state

  • Dependency Management — CloudFormation handles resource dependencies automatically

  • State Management — CloudFormation maintains resource state, enabling updates, change preview, and drift detection

  • Change Sets — Preview changes before applying them via show-changes action

Consequences:

  • ✅ Simplified error handling and recovery

  • ✅ Built-in drift detection via check-drift action

  • ✅ Change preview via CloudFormation ChangeSets

  • ✅ Async operations handled via boto3 waiter pattern — provides reliable completion detection with configurable polling interval and timeout

ADR-002: Scenario-Based Architecture

Decision: All Security Group topologies defined as pre-built YAML scenario files.

Rationale:

  • Separation of Concerns — Network topology (data) separated from provisioning logic (code)

  • Reusability — Common architectures templated and reused across clients

  • Override System — Clients customise scenarios without modifying core files

  • Validation — Scenarios validated for security issues before deployment

  • Extensibility — New scenarios added by dropping a YAML file into schemas/scenarios/

Consequences:

  • ✅ Consistent security posture across deployments

  • ✅ Easy to add new architecture patterns

  • ✅ Overrides keep customisations minimal and auditable

  • ✅ Fundamentally different architectures are captured as new named scenarios — promoting reuse and standardisation

ADR-003: Standalone Cross-Tier Rules to Avoid Circular Dependencies

Decision: Cross-tier Security Group references are generated as standalone AWS::EC2::SecurityGroupIngress / AWS::EC2::SecurityGroupEgress resources rather than inline rules.

Context: In a 3-tier scenario, the web SG references the app SG and vice versa. If both are defined as inline rules within their respective AWS::EC2::SecurityGroup resources, CloudFormation detects a circular dependency and fails.

Rationale:

  • Standalone ingress/egress resources break the circular dependency by decoupling the rule from the SG resource definition

  • CloudFormation can then resolve the dependency graph correctly

Consequences:

  • ✅ No circular dependency errors regardless of scenario complexity

  • ✅ Transparent to the client — handled automatically by CfnGenerator

  • ✅ Additional standalone resources per cross-tier rule keep the template clean and explicit

ADR-004: Cython Compilation for Code Protection

Decision: Compile core Python modules to .so binary files using Cython.

Modules Compiled:

  • config/loader.py, core/sg_manager.py, generators/cfn_generator.py

  • scenarios/loader.py, scenarios/validator.py, license/validator.py

  • utils/html_generator.py, utils/review_report.py

Rationale:

  • IP Protection — Core business logic not exposed as plain text

  • Tamper Resistance — Binary files harder to modify

  • AWS Marketplace Standard — Common practice for commercial containerised products

Consequences:

  • ✅ Protected intellectual property

  • ✅ cli.py and __init__.py remain as plain Python for entry point compatibility

  • ✅ Platform-specific binaries optimised for Linux x86_64 — the standard deployment environment

Security Architecture

Code Protection

Core modules are compiled to .so binary files via Cython, protecting intellectual property and preventing reverse engineering. Only cli.py and __init__.py are distributed as plain Python — these are entry points with no business logic.

License Validation

Every action — including local-only operations like validate-config — requires a valid AWS Marketplace subscription. License validation runs before any business logic executes. If validation fails, the tool exits immediately with a clear error message.

Container Security

Control

Implementation

Non-root execution

Container runs as sguser (UID 1000)

Read-only credentials

~/.aws mounted as :ro

Read-only config

/app/configs mounted as :ro

No exposed ports

Container exposes no network services

No privileged mode

Standard Docker execution

Minimal base image

python:3.13-slim (Debian)

Multi-stage build

Build dependencies excluded from runtime image

Credential Management

  • No credentials hardcoded in code or container image

  • AWS credentials provided at runtime via volume mount or environment variables

  • IAM roles (EC2/ECS instance metadata) supported — no credentials needed

  • Temporary credentials (STS AssumeRole, SSO) fully supported

Input Validation

  • All configuration files validated against JSON schema before any AWS operation

  • Config filenames cannot contain path separators (path traversal prevention)

  • Scenario validator blocks dangerous security group rules before template generation

  • Port values validated to be within 1-65535 range

IAM Least Privilege

The generated IAM policy (create-policy action) follows least privilege principles:

  • EC2 permissions scoped to the deployment region and account

  • SSM permissions split into two statements:

    • Read-only on /vpc/ path — to resolve VPC ID

    • Full CRUD on /sg/ path — to store and delete SG IDs

  • CloudFormation permissions scoped to the specific stack name pattern

Known Vulnerabilities

See SECURITY.md for the current vulnerability status of the base Docker image.

Deployment Architecture

Docker Container

SG Provisioner is distributed as a Docker container via AWS Marketplace. The container is built using a multi-stage build to keep the runtime image minimal and secure.

Multi-Stage Build:

Stage 1: Builder
  - Base: python:3.13-slim
  - Installs uv package manager
  - Resolves and installs all Python dependencies into .venv

Stage 2: Runtime
  - Base: python:3.13-slim (clean image)
  - Copies only the installed packages from Stage 1
  - Copies Cython-compiled sg_provisioner package (.so files)
  - Removes source .py files for compiled modules (IP protection)
  - Copies common library, schemas, templates, and HTML documentation
  - Runs as non-root user (sguser, UID 1000)

Container Contents

Path

Contents

/app/sg_provisioner/

Compiled application modules (.so files)

/app/common/

Shared library (plain Python)

/app/schemas/

Validation schema and scenario YAML files

/app/templates/

CloudFormation template placeholders

/app/docs/

Built HTML documentation (Sphinx)

/app/configs/

Mount point for customer configuration files

/app/policies/

Mount point for generated IAM policies

/app/reports/

Mount point for logs and HTML reports

Volume Mounts

Host Path

Container Path

Mode

Purpose

~/.aws

/home/sguser/.aws

:ro

AWS credentials

$(pwd)/sg/configs

/app/configs

:ro

Customer configuration files

$(pwd)/sg/policies

/app/policies

rw

Generated IAM policies

$(pwd)/sg/templates

/app/templates

rw

Generated CloudFormation templates

$(pwd)/sg/reports

/app/reports

rw

Execution logs and HTML reports

Entrypoint

The container entrypoint (entrypoint.sh) invokes the SG Provisioner CLI, which:

  1. Validates the AWS Marketplace license

  2. Parses CLI arguments (-con, -act, --force, --verbose)

  3. Instantiates SgManager and executes the requested action

Health Check

HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD python -c "import sys; sys.exit(0)" || exit 1

Deployment Models

Interactive (Developer):

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 my-config.yaml -act validate-config

CI/CD Pipeline:

- name: Deploy security groups
  run: |
    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 my-config.yaml -act create-security-groups --force

EC2/ECS with IAM Role:

docker run --rm \
  -v $(pwd)/sg/configs:/app/configs:ro \
  -v $(pwd)/sg/reports:/app/reports \
  sg-provisioner:latest \
  -con my-config.yaml -act create-security-groups --force

Copyright © 2025 Axon Tech Labs. All rights reserved.

See LICENSE.txt for terms and conditions.