AWS systems-manager medium security documentation change
Summary
Added documentation about secure parameter handling including environment variable interpolation to prevent command injections, added security best practices section, and provided multiple examples of secure parameter usage
Security assessment
The changes explicitly address command injection prevention through environment variable interpolation (interpolationType: ENV_VAR) and input validation (allowedPattern). The added 'Parameter security best practices' section provides specific security guidance. The examples demonstrate secure handling of parameters in command execution contexts.
Diff
diff --git a/systems-manager/latest/userguide/documents-schemas-features.md b/systems-manager/latest/userguide/documents-schemas-features.md index a00174c53..6bdf4f173 100644 --- a//systems-manager/latest/userguide/documents-schemas-features.md +++ b//systems-manager/latest/userguide/documents-schemas-features.md @@ -5 +5 @@ -Schema version 2.2Schema version 1.2Schema version 0.3 +Schema version 2.2Schema version 1.2Schema version 0.3Secure parameter handling examplesParameter security best practices @@ -34,0 +35 @@ Cross-platform support | Cross-platform support allows you to specify different +Parameter interpolation | Allows string parameters to be interpolated into environment variables before command execution, providing better security against command injections. When set to `ENV_VAR`, the agent creates an environment variable named `SSM_`parameter-name`` that contains the parameter's value. @@ -335,0 +337,37 @@ JSON +###### Schema version 2.2 interpolation example with SSM Agent versions before 3.3.2746.0 + +On SSM Agent versions prior to 3.3.2746.0, the agent ignores the `interpolationType` parameter and instead performs a raw string substitution. If you are referencing `SSM_`parameter-name`` explicitly, you must set this explicitly. In the following example for Linux, the `SSM_Message` environment variable is referenced explicitly. + + + { + "schemaVersion": "2.2", + "description": "An example document", + "parameters": { + "Message": { + "type": "String", + "description": "Message to be printed", + "default": "Hello", + "interpolationType" : "ENV_VAR", + "allowedPattern: "^[^"]*$" + + } + }, + "mainSteps": [{ + "action": "aws:runShellScript", + "name": "printMessage", + "inputs": { + "runCommand": [ + "if [ -z "${SSM_Message+x}" ]; then", + " export SSM_Message=\"{{Message}}\"", + "fi", + "", + "echo $SSM_Message" + ] + } + } + } + +###### Note + +`allowedPattern` isn’t technically required if an SSM document doesn’t use double braces: `{{ }}` + @@ -856,0 +895,161 @@ The following sample shows the contents of an Automation runbook, in YAML format +## Secure parameter handling examples + +The following examples demonstrate secure parameter handling using environment variable `interpolationType`. + +### Basic secure command execution + +This example shows how to securely handle a command parameter: + +###### Note + +`allowedPattern` isn’t technically required in SSM documents that don’t use double braces: `{{ }}` + +YAML + + + + --- + + schemaVersion: '2.2' + description: An example document. + parameters: + Message: + type: String + description: "Message to be printed" + default: Hello + interpolationType: ENV_VAR + allowedPattern: "^[^"]*$" + mainSteps: + - action: aws:runShellScript + name: printMessage + precondition: + StringEquals: + - platformType + - Linux + inputs: + runCommand: + - echo {{Message}} + + +JSON + + + + { + "schemaVersion": "2.2", + "description": "An example document.", + "parameters": { + "Message": { + "type": "String", + "description": "Message to be printed", + "default": "Hello", + "interpolationType": "ENV_VAR", + "allowedPattern": "^[^"]*$" + } + }, + "mainSteps": [{ + "action": "aws:runShellScript", + "name": "printMessage", + "precondition": { + "StringEquals": ["platformType", "Linux"] + }, + "inputs": { + "runCommand": [ + "echo {{Message}}" + ] + } + }] + } + + +### Using parameters in interpreted languages + +This example demonstrates secure parameter handling in Python: + +YAML + + + + --- + schemaVersion: '2.2' + description: 'Secure Python script execution' + parameters: + inputData: + type: String + description: 'Input data for processing' + interpolationType: 'ENV_VAR' + mainSteps: + - action: aws:runPowerShellScript + name: runPython + inputs: + runCommand: + - | + python3 -c ' + import os + import json + + # Safely access parameter through environment variable + input_data = os.environ.get("SSM_inputData", "") + + # Process the data + try: + processed_data = json.loads(input_data) + print(f"Successfully processed: {processed_data}") + except json.JSONDecodeError: + print("Invalid JSON input") + ' + +### Backwards compatibility example + +This example shows how to handle parameters securely while maintaining backwards compatibility: + +YAML + + + + --- + schemaVersion: '2.2' + description: 'Backwards compatible secure parameter handling' + parameters: + userInput: + type: String + description: 'User input to process' + interpolationType: 'ENV_VAR' + allowedPattern: '^[^"]*$' + + mainSteps: + - action: aws:runShellScript + name: processInput + inputs: + runCommand: + - | + # Handle both modern and legacy agent versions + if [ -z "${SSM_userInput+x}" ]; then + # Legacy agent - fall back to direct parameter reference + export SSM_userInput="{{userInput}}" + fi + + # Process the input securely + echo "Processing input: $SSM_userInput" + +###### Note + +`allowedPattern` isn’t technically required in SSM documents that don’t use double braces: `{{ }}` + +## Parameter security best practices + +Follow these best practices when handling parameters in SSM documents: + + * **Use environment variable interpolation** \- Always use `interpolationType: "ENV_VAR"` for string parameters that will be used in command execution. + + * **Implement input validation** \- Use `allowedPattern` to restrict parameter values to safe patterns. +