AWS systems-manager documentation change
Summary
Added comprehensive documentation about using attachments with aws:executeScript including package structures, S3 uploads, checksum verification, examples, and troubleshooting
Security assessment
The changes introduce security-adjacent documentation by emphasizing checksum verification for attachments ('Calculate the attachment checksum' section) and mentioning S3 permissions requirements. However, there is no evidence of addressing a specific security vulnerability. The checksum guidance and permission requirements represent security best practices rather than fixes for existing vulnerabilities.
Diff
diff --git a/systems-manager/latest/userguide/automation-action-executeScript.md b/systems-manager/latest/userguide/automation-action-executeScript.md index 9ba3637d6..584dc19ea 100644 --- a//systems-manager/latest/userguide/automation-action-executeScript.md +++ b//systems-manager/latest/userguide/automation-action-executeScript.md @@ -4,0 +5,2 @@ +Using attachments with aws:executeScriptaws:executeScript attachment examplesTroubleshooting aws:executeScript attachments + @@ -262,0 +265,330 @@ The JSON representation of the object returned by your function. Up to 100KB is +## Using attachments with aws:executeScript + +Attachments provide a powerful way to package and reuse complex scripts, multiple modules, and external dependencies with your `aws:executeScript` actions. Use attachments when you need to: + + * Package multiple Python modules or PowerShell scripts together. + + * Reuse the same script logic across multiple runbooks. + + * Include external libraries or dependencies with your scripts. + + * Keep your runbook definition clean by separating complex script logic. + + * Share script packages across teams or automation workflows. + + + + +### Attachment structure and packaging + +You can attach either single files or zip packages containing multiple files. The structure depends on your use case: + +###### Single file attachments + +For simple scripts, you can attach a single `.py` file (Python) or a `.zip` file containing a single PowerShell script. + +###### Multi-module packages + +For complex automation that requires multiple modules, create a zip package with the following recommended structure: + + + my-automation-package.zip + ├── main.py # Entry point script + ├── utils/ + │ ├── __init__.py # Required for Python module imports + │ ├── helper_functions.py # Utility functions + │ └── aws_operations.py # AWS-specific operations + ├── config/ + │ ├── __init__.py + │ └── settings.py # Configuration settings + └── requirements.txt # Optional: document dependencies + +###### Important + +For Python packages, you must include an empty `__init__.py` file in each directory that contains Python modules. This allows you to import modules using standard Python import syntax like `from utils import helper_functions`. + +###### PowerShell package structure + +PowerShell attachments must be packaged in zip files with the following structure: + + + my-powershell-package.zip + ├── Main.ps1 # Entry point script + ├── Modules/ + │ ├── HelperFunctions.ps1 # Utility functions + │ └── AWSOperations.ps1 # AWS-specific operations + └── Config/ + └── Settings.ps1 # Configuration settings + +### Creating runbooks with attachments + +Follow these steps to create runbooks that use attachments: + + 1. **Upload your attachment to Amazon S3** + +Upload your script file or zip package to an S3 bucket that your automation role can access. Note the S3 URI for use in the next step. + + aws s3 cp my-automation-package.zip s3://my-automation-bucket/scripts/ + + 2. **Calculate the attachment checksum** + +Calculate the SHA-256 checksum of your attachment file for security verification: + + # Linux/macOS + shasum -a 256 my-automation-package.zip + + # Windows PowerShell + Get-FileHash -Algorithm SHA256 my-automation-package.zip + + 3. **Define the files section in your runbook** + +Add a `files` section at the top level of your runbook to reference your attachment: + + files: + my-automation-package.zip: + sourceType: "S3" + sourceInfo: + path: "s3://my-automation-bucket/scripts/my-automation-package.zip" + checksums: + sha256: "your-calculated-checksum-here" + + 4. **Reference the attachment in your executeScript step** + +Use the `Attachment` parameter to reference your uploaded file: + + - name: runMyScript + action: aws:executeScript + inputs: + Runtime: python3.11 + Handler: main.process_data + Attachment: my-automation-package.zip + InputPayload: + inputData: "{{InputParameter}}" + + + + +## aws:executeScript attachment examples + +The following examples demonstrate different ways to use attachments with the `aws:executeScript` action. + +### Example 1: Single file attachment + +This example shows how to use a single Python file as an attachment to process EC2 instance data. + +###### Attachment file: process_instance.py + +Create a Python file with the following content: + + + import boto3 + import json + + def process_instance_data(events, context): + """Process EC2 instance data and return formatted results.""" + try: + instance_id = events.get('instanceId') + if not instance_id: + raise ValueError("instanceId is required") + + ec2 = boto3.client('ec2') + + # Get instance details + response = ec2.describe_instances(InstanceIds=[instance_id]) + instance = response['Reservations'][0]['Instances'][0] + + # Format the response + result = { + 'instanceId': instance_id, + 'instanceType': instance['InstanceType'], + 'state': instance['State']['Name'], + 'availabilityZone': instance['Placement']['AvailabilityZone'], + 'tags': {tag['Key']: tag['Value'] for tag in instance.get('Tags', [])} + } + + print(f"Successfully processed instance {instance_id}") + return result + + except Exception as e: + print(f"Error processing instance: {str(e)}") + raise + +###### Complete runbook + +Here's the complete runbook that uses the single file attachment: + + + description: Process EC2 instance data using single file attachment + schemaVersion: '0.3' + assumeRole: '{{AutomationAssumeRole}}' + parameters: + AutomationAssumeRole: + type: String + description: (Required) IAM role for automation execution + InstanceId: + type: String + description: (Required) EC2 instance ID to process + + files: + process_instance.py: + sourceType: "S3" + sourceInfo: + path: "s3://my-automation-bucket/scripts/process_instance.py" + checksums: + sha256: "abc123def456..." + + mainSteps: + - name: processInstance + action: aws:executeScript + inputs: + Runtime: python3.11 + Handler: process_instance.process_instance_data + Attachment: process_instance.py + InputPayload: + instanceId: '{{InstanceId}}' + outputs: + - Type: StringMap + Name: InstanceData + Selector: $.Payload + + outputs: + - processInstance.InstanceData +