AWS SSM Automation aws:executeScript Guide: Python 3.12, InputPayload, Outputs & Limits

📅 Created: 2025/01/04, Updated: 2026/11/01 ⏱️ Estimated reading time ~5 mins (1,046 words)

Complete engineering guide to AWS Systems Manager (SSM) Automation aws:executeScript action, including Python 3.12 runtime usage, InputPayload/Output passing, sandbox limits, and IAM roles.

Table of Contents

Revision History
Three Pitfalls I Hit When Migrating Operational Scripts to aws:executeScript
1. Internal Architecture of aws:executeScript and How It Compares to Lambda & Run Command
2. Passing InputPayload and Extracting outputs ( $.Payload )
1. 1) Writing the Python Handler ( runbook.py )
2. 2) Packaging External Libraries into modules.zip Without Path Errors
3. Complete CloudFormation & Terraform Runbook Templates
1. 1) CloudFormation ( AWS::SSM::Document ) Template
2. 2) Terraform ( aws_ssm_document ) Template with Automated Checksums
4. Least-Privilege IAM Design: Separating Operator and AssumeRole
5. Five Production Best Practices for Cost and Reliability
Summary

Revision History

Date	Update Summary
2026/10/31	- Updated deprecated Python 3.8 references to currently supported runtimes ( `python3.12` / `python3.11` / `PowerShell 7.4` ) - Corrected `InputPayload` handling ( `def handler(events, context):` dictionary input instead of `sys.argv` ) and added `outputs` ( `$.Payload.*` JSONPath) examples - Added internal Falcon Sandbox architecture diagram, VPC isolation constraints, complete CloudFormation / Terraform templates, and per-second billing ( `$0.00003/sec` ) optimization patterns
2024/04/06	- Added Terraform runbook definition examples and operational best practices
2023/11/14	- Initial publication

Three Pitfalls I Hit When Migrating Operational Scripts to `aws:executeScript`

While standardizing multi-account operations, I wanted operators to run Python maintenance scripts safely from the AWS Management Console with approval workflows—without granting them broad IAM permissions. That led me to adopt the aws:executeScript action in AWS Systems Manager (SSM) Automation.

Expecting it to behave exactly like a standard AWS Lambda deployment, I wrote my CloudFormation template and Python script, deployed them, and immediately ran into three frustrating roadblocks on day one:

InputPayload Parameters Were Missing : I initially assumed parameters passed via InputPayload could be read from command-line arguments ( sys.argv ). After dumping the runtime environment variables and inspecting the internal wrapper ( FalconPythonWrapper.lambda_handler ), I realized aws:executeScript invokes def script_handler(events, context): and passes InputPayload as a Python dict in the first argument ( events ).
S3 Attachment sha256 Mismatches and ModuleNotFoundError : When bundling external packages into modules.zip on S3, I accidentally zipped the parent directory rather than its contents, causing ModuleNotFoundError . Worse, every time I updated a single line of code and overwrote the ZIP in S3, the runbook failed to start unless I also updated the exact 64-character files.checksums.sha256 hash in the SSM Document.
Hitting the 600-Second Timeout and Per-Second Charges with time.sleep() : I wrote a while loop with time.sleep(30) inside Python to wait for an RDS snapshot to finish. The step abruptly failed at the hard 10-minute (600-second) ceiling. Because aws:executeScript bills by execution duration ( $0.00003 / second after the free tier), sleeping inside Python wastes both execution time and money compared to splitting waits into a native aws:waitForAwsResourceProperty step.

Based on those hands-on troubleshooting sessions, this guide covers the internal execution architecture of aws:executeScript , accurate payload and output wiring, production-ready CloudFormation and Terraform templates, least-privilege IAM policies, and cost optimization practices.

▲ Internal execution architecture (Falcon Sandbox) and data flow for aws:executeScript in AWS Systems Manager Automation

1. Internal Architecture of `aws:executeScript` and How It Compares to Lambda & Run Command

The aws:executeScript action lets you execute custom Python or PowerShell scripts serverlessly as part of an SSM Automation runbook.

1) The AWS-Managed Isolated Lambda Environment (Falcon Sandbox)

Dumping os.environ inside aws:executeScript reveals that your script actually runs inside an AWS-managed AWS Lambda environment (internally prefixed Falcon- ) hosted in an AWS service account:

{
    "_HANDLER": "FalconPythonWrapper.lambda_handler",
    "AWS_EXECUTION_ENV": "AWS_Lambda_python3.12",
    "AWS_LAMBDA_FUNCTION_MEMORY_SIZE": "512",
    "AWS_LAMBDA_FUNCTION_NAME": "Falcon-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "AWS_LAMBDA_LOG_GROUP_NAME": "/aws/lambda/Falcon-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "LAMBDA_TASK_ROOT": "/var/task",
    "PYTHONPATH": "/var/runtime:/tmp/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "TZ": ":UTC"
}

Understanding this underlying sandbox clarifies the exact architectural limits you must design around:

Specification	`aws:executeScript` Limit / Behavior	Design Implication
Max Execution Duration	600 seconds (10 minutes) (configurable via `TimeoutSeconds` )	Shorter than standard Lambda (15 min). Offload polling waits to dedicated steps.
Memory Allocation	512 MB fixed (cannot be increased)	Stream large datasets instead of loading huge objects into memory.
Ephemeral Storage	`/tmp` directory (512 MB)	The working directory is read-only; write all temporary files to `/tmp` .
Network Connectivity	No VPC attachment (Public AWS network only)	Cannot connect directly to private RDS databases or internal VPC endpoints.
Pricing Model	`$0.00003 / second` + step count charge (beyond free tier)	Free tier includes 100,000 basic steps and 5,000 script seconds per account/month.

2) Choosing Between `aws:executeScript` , Standalone Lambda, and `aws:runCommand`

Dimension	SSM `aws:executeScript`	Standalone AWS Lambda ( `aws:invokeLambdaFunction` )	SSM `aws:runCommand`
Primary Use Case	Multi-step operational runbooks orchestrating public AWS APIs with approvals	High-frequency event processing, >512 MB memory tasks, or private VPC access	OS-level configuration or private DB maintenance executed inside EC2 instances
Function Lifecycle	None (embedded inline in YAML/JSON or attached via S3 ZIP)	Must manage Lambda function, Log Group, and IAM execution role separately	None (executed by SSM Agent on target EC2 instances)
Approval & Input UI	Built-in (native parameter validation & `aws:approve` integration)	Requires Step Functions or custom frontend	Can be invoked as a step inside Automation runbooks
Private VPC Access	No (public AWS API endpoints only)	Yes (with VPC configuration)	Yes (uses the target EC2 instance’s subnet routing)

3) Supported Runtimes (Python 3.8 and Earlier Are Deprecated)

Older runtimes such as python3.7 and python3.8 have reached End of Support. Always specify python3.12 or python3.11 for Python, or PowerShell 7.4 for PowerShell:

Supported Python Runtime values : python3.12 (recommended), python3.11 , python3.10 , python3.9
Supported PowerShell Runtime values : PowerShell 7.4 (recommended), PowerShell 7.2 , PowerShell Core 6.0
Official Reference: Systems Manager Automation actions reference - aws:executeScript

2. Passing `InputPayload` and Extracting `outputs` ( `$.Payload` )

        sequenceDiagram
    autonumber
    actor Ops as Operator / EventBridge
    participant SSM as SSM Automation<br/>(Runbook Controller)
    participant S3 as Amazon S3<br/>(modules.zip)
    participant Falcon as Falcon Sandbox<br/>(aws:executeScript)
    participant API as AWS Public API<br/>(EC2 / RDS / S3)

    Ops->>SSM: StartAutomationExecution (Parameters)
    SSM->>S3: Download Attachment & verify SHA-256
    S3-->>Falcon: Extract to /tmp & append to PYTHONPATH
    SSM->>Falcon: Invoke handler(events, context)<br/>(InputPayload passed as 'events' dict)
    Falcon->>API: Query/mutate resources via boto3 Paginator
    API-->>Falcon: API Response
    Falcon-->>SSM: return {"InstanceIds": [...], "MatchedCount": 3}
    Note over SSM: Automatically wrapped under $.Payload<br/>Extracted via Selector: "$.Payload.InstanceIds"
    SSM->>SSM: Pass output to subsequent steps ({{ ScanInstancesStep.InstanceIds }})
       

1) Writing the Python Handler ( `runbook.py` )

For Python steps, set inputs.Handler to <filename_without_ext>.<function_name> (or just <function_name> for inline scripts). Define your entry point as def main(events, context): and read parameters from the events dictionary:

# src/runbook.py
import logging
from typing import Any, Dict, List
import boto3
from botocore.exceptions import ClientError

logger = logging.getLogger()
logger.setLevel(logging.INFO)


def main(events: Dict[str, Any], context: Any) -> Dict[str, Any]:
    """
    Entry point for SSM Automation aws:executeScript.
    InputPayload is passed as the first argument `events` (dict).
    """
    target_tag_key = events.get("TagKey", "Environment")
    target_tag_value = events.get("TagValue", "Staging")
    dry_run = str(events.get("DryRun", "true")).lower() == "true"

    print(f"[INFO] Starting scan: Tag {target_tag_key}={target_tag_value}, DryRun={dry_run}")

    ec2 = boto3.client("ec2")
    matched_instance_ids: List[str] = []

    try:
        paginator = ec2.get_paginator("describe_instances")
        page_iterator = paginator.paginate(
            Filters=[
                {"Name": f"tag:{target_tag_key}", "Values": [target_tag_value]},
                {"Name": "instance-state-name", "Values": ["running"]},
            ]
        )

        for page in page_iterator:
            for reservation in page.get("Reservations", []):
                for instance in reservation.get("Instances", []):
                    matched_instance_ids.append(instance["InstanceId"])

        print(f"[INFO] Found {len(matched_instance_ids)} running instances: {matched_instance_ids}")

        # Returned dictionary is automatically wrapped under $.Payload.<Key>
        return {
            "MatchedCount": len(matched_instance_ids),
            "InstanceIds": matched_instance_ids,
            "DryRun": dry_run,
            "ExecutionStatus": "SUCCESS",
        }

    except ClientError as err:
        print(f"[ERROR] AWS API Error: {err}")
        raise

Note

PowerShell Difference : PowerShell scripts do not require the Handler property. InputPayload is injected into the environment variable $env:InputPayload as a JSON string, which you can parse via $payload = $env:InputPayload | ConvertFrom-Json .

2) Packaging External Libraries into `modules.zip` Without Path Errors

To bundle third-party libraries (or a newer version of boto3 ), install packages directly into the root of your build folder alongside runbook.py before zipping:

mkdir -p build_pkg
cp src/runbook.py build_pkg/
pip install -r src/requirements.txt -t build_pkg/ --upgrade

# Zip the contents of build_pkg at the root level (do not include the parent folder)
(cd build_pkg && zip -rq ../modules.zip .)

# Compute the SHA-256 hash required for the SSM Document 'files' section
shasum -a 256 modules.zip

3. Complete CloudFormation & Terraform Runbook Templates

1) CloudFormation ( `AWS::SSM::Document` ) Template

AWSTemplateFormatVersion: "2010-09-09"
Description: SSM Automation Runbook with aws:executeScript (Python 3.12)

Parameters:
  ArtifactBucketName:
    Type: String
  ModuleZipSha256:
    Type: String
  AutomationAssumeRoleArn:
    Type: String

Resources:
  InstanceScanRunbook:
    Type: AWS::SSM::Document
    Properties:
      DocumentType: Automation
      DocumentFormat: YAML
      UpdateMethod: NewVersion
      Attachments:
        - Key: S3FileUrl
          Name: modules.zip
          Values:
            - !Sub "https://${ArtifactBucketName}.s3.${AWS::Region}.amazonaws.com/runbooks/modules.zip"
      Content:
        schemaVersion: "0.3"
        description: "Scan running EC2 instances by tag using Python 3.12"
        assumeRole: "{{ AutomationAssumeRole }}"
        parameters:
          AutomationAssumeRole:
            type: String
            default: !Ref AutomationAssumeRoleArn
          TagKey:
            type: String
            default: "Environment"
          TagValue:
            type: String
            default: "Staging"
          DryRun:
            type: String
            allowedValues: ["true", "false"]
            default: "true"
        mainSteps:
          - name: ScanInstancesStep
            action: "aws:executeScript"
            timeoutSeconds: 300
            inputs:
              Runtime: "python3.12"
              Handler: "runbook.main"
              Attachment: "modules.zip"
              InputPayload:
                TagKey: "{{ TagKey }}"
                TagValue: "{{ TagValue }}"
                DryRun: "{{ DryRun }}"
            outputs:
              - Name: InstanceIds
                Selector: "$.Payload.InstanceIds"
                Type: StringList
              - Name: MatchedCount
                Selector: "$.Payload.MatchedCount"
                Type: Integer
        files:
          modules.zip:
            checksums:
              sha256: !Ref ModuleZipSha256

2) Terraform ( `aws_ssm_document` ) Template with Automated Checksums

Using data.archive_file in Terraform eliminates manual SHA-256 calculations and prevents S3 object caching issues by embedding the SHA-256 hash into the S3 key:

resource "terraform_data" "pip_install" {
  triggers_replace = [
    filesha256("${path.module}/src/requirements.txt"),
    filesha256("${path.module}/src/runbook.py"),
  ]

  provisioner "local-exec" {
    command = <<-EOT
      rm -rf "${path.module}/build_pkg"
      mkdir -p "${path.module}/build_pkg"
      cp "${path.module}/src/runbook.py" "${path.module}/build_pkg/"
      pip install -r "${path.module}/src/requirements.txt" -t "${path.module}/build_pkg" --upgrade
    EOT
  }
}

data "archive_file" "modules_zip" {
  depends_on  = [terraform_data.pip_install]
  type        = "zip"
  source_dir  = "${path.module}/build_pkg"
  output_path = "${path.module}/dist/modules.zip"
}

resource "aws_s3_object" "modules_zip" {
  bucket = var.artifact_bucket_name
  key    = "runbooks/modules-${data.archive_file.modules_zip.output_sha256}.zip"
  source = data.archive_file.modules_zip.output_path
  etag   = data.archive_file.modules_zip.output_md5
}

resource "aws_ssm_document" "instance_scan_runbook" {
  name            = "InstanceScanRunbook"
  document_type   = "Automation"
  document_format = "JSON"

  attachments_source {
    key    = "S3FileUrl"
    name   = "modules.zip"
    values = ["https://${var.artifact_bucket_name}.s3.${data.aws_region.current.name}.amazonaws.com/${aws_s3_object.modules_zip.key}"]
  }

  content = jsonencode({
    schemaVersion = "0.3"
    description   = "Scan running EC2 instances by tag using Python 3.12"
    assumeRole    = var.automation_assume_role_arn
    parameters = {
      TagKey   = { type = "String", default = "Environment" }
      TagValue = { type = "String", default = "Staging" }
      DryRun   = { type = "String", default = "true" }
    }
    mainSteps = [
      {
        name           = "ScanInstancesStep"
        action         = "aws:executeScript"
        timeoutSeconds = 300
        inputs = {
          Runtime    = "python3.12"
          Handler    = "runbook.main"
          Attachment = "modules.zip"
          InputPayload = {
            TagKey   = "{{ TagKey }}"
            TagValue = "{{ TagValue }}"
            DryRun   = "{{ DryRun }}"
          }
        }
        outputs = [
          {
            Name     = "InstanceIds"
            Selector = "$.Payload.InstanceIds"
            Type     = "StringList"
          },
          {
            Name     = "MatchedCount"
            Selector = "$.Payload.MatchedCount"
            Type     = "Integer"
          }
        ]
      }
    ]
    files = {
      "modules.zip" = {
        checksums = {
          sha256 = data.archive_file.modules_zip.output_sha256
        }
      }
    }
  })
}

4. Least-Privilege IAM Design: Separating Operator and `AssumeRole`

No	Required Operator IAM Action	Purpose	Scoped Resource ARN
01	`ssm:StartAutomationExecution`	Start the specific runbook	`arn:aws:ssm:<region>:<account>:automation-definition/<RunbookName>:*`
02	`ssm:GetAutomationExecution`	View execution status and step outputs	`arn:aws:ssm:<region>:<account>:automation-execution/*`
03	`ssm:StopAutomationExecution`	Abort a running execution	`arn:aws:ssm:<region>:<account>:automation-execution/*`
04	`ssm:SendAutomationSignal`	Approve/reject `aws:approve` steps	`arn:aws:ssm:<region>:<account>:automation-execution/*`
05	`iam:PassRole`	Pass the execution role ( `assumeRole` ) to SSM	Dedicated role ARN (with `iam:PassedToService: ssm.amazonaws.com` condition)

5. Five Production Best Practices for Cost and Reliability

Offload Polling Waits to aws:waitForAwsResourceProperty or aws:sleep : Never run long time.sleep() loops inside aws:executeScript . Splitting waits into native SSM steps avoids the 600-second timeout and prevents unnecessary $0.00003 / second duration charges.
Parallelize API I/O with concurrent.futures.ThreadPoolExecutor : When querying or tagging dozens of resources within the 512 MB / 600-second sandbox, use thread pools combined with botocore.config.Config(retries={"max_attempts": 10, "mode": "adaptive"}) .
Combine print() Statements with Structured Return Payloads : Because the Falcon Lambda runs in an AWS-managed account, surface key diagnostic details in both stdout ( print() ) and the returned dictionary ( $.Payload ).
Check Managed Runbooks ( AWS-* ) and aws:executeAwsApi First : For single API calls, aws:executeAwsApi eliminates Python runtime upgrade maintenance entirely.
Pair with aws:runCommand or VPC Lambda for Private Resources : When an approval workflow needs to reach a private RDS instance or internal endpoint, use SSM Automation for the approval gate and invoke aws:runCommand or aws:invokeLambdaFunction for the private network action.

Summary

Once you account for the Falcon sandbox constraints (512 MB memory, 600-second max duration, no direct VPC attachment) and wire up events and $.Payload properly, aws:executeScript becomes one of the fastest ways to deliver auditable, least-privilege operational tooling in AWS. In my own projects, I keep scripts under ~300 lines in aws:executeScript and move heavier or VPC-bound workloads to Step Functions + Lambda—a boundary that continues to work well in production.

CONT-AID PRODUCTS

Production AI Applications & Official Ecosystem

AI COACH & STUDIO

CandidLens

AI Mock Calls & 5-Axis Voice Analytics

Master conversation skills with realistic AI phone training and 5-axis feedback. Includes 16-lesson interactive academy and studio AI portraits.

AI Mock Call Voice Analytics AI Studio

Explore CandidLens

SMART EXPENSE & OCR

DEALER

Zero-Friction Bill Split with Smart OCR

Effortlessly snap receipts for instant AI itemization. Integrated with LINE for seamless group expense tracking and pain-free settlement.

Smart Receipt OCR LINE Auth Smart Split

Explore DEALER

AI GAME MASTER

Mingli

Interactive AI Party Game Host

Interactive AI personas (Fortune Teller, Butler, Bartender) host real-time games, challenges, and conversation starters for unforgettable gatherings.

AI Persona Host Party Games Icebreaker

Explore Mingli

QUANT & AI NEWS

Alpha Radar

AI Financial Earnings & Market Momentum

Real-time AI quant analysis of earnings reports, corporate filings, and momentum indicators for global equities and Japanese stocks.

Quant News AI Analytics Global Equities

Explore Alpha Radar

INGREDIENT COMPARISON

成分.com

Supplement & Protein Purity & Unit Cost Analyzer

Unbiased healthcare database featuring zero-additive filters and active ingredient cost performance metrics.

Cost per Gram Ingredient Safety Supplements

Explore Seibun.com

⏳ Coming Soon

Download Production-Ready Multi-Agent Rules & Hooks

Get the complete configuration pack featured in this article: universal AGENTS.md, deterministic hooks.json, Git safety guardrails, and validation scripts tested across Antigravity, Kiro, Claude Code, and Codex.

Get Starter Kit (Coming Soon) ※ Currently in preparation on Gumroad. The download link will become active upon launch.