AWS systems-manager high security documentation change

Service: systems-manager · 2025-07-16 · Security-related high

File: systems-manager/latest/userguide/documents-creating-content.md

Summary

Added new section 'Security best practices for SSM documents' with guidance on preventing command injection, secure parameter handling using environment variable interpolation, input validation patterns, and backwards compatibility considerations

Security assessment

The changes explicitly address security vulnerabilities like command injection by introducing environment variable interpolation and input validation patterns. Specific security controls include preventing double-quote injection via allowedPattern regex and guidance for secure parameter handling in scripts. This constitutes direct security documentation improvements.

Diff

diff --git a/systems-manager/latest/userguide/documents-creating-content.md b/systems-manager/latest/userguide/documents-creating-content.md
index 4bf4ea33a..0f3d05ce4 100644
--- a//systems-manager/latest/userguide/documents-creating-content.md
+++ b//systems-manager/latest/userguide/documents-creating-content.md
@@ -93,0 +94,60 @@ PowerShell
+### Security best practices for SSM documents
+
+When creating SSM documents, follow these security best practices to help prevent command injection and ensure secure parameter handling:
+
+  * Use environment variable interpolation for string parameters that will be used in commands or scripts. Add the `interpolationType` property with value `ENV_VAR` to your string parameters:
+    
+        {
+        "command": {
+            "type": "String",
+            "description": "Command to execute",
+            "interpolationType": "ENV_VAR"
+        }
+    }
+
+You can further improve the security of your SSM documents by specifying that double-quote marks aren’t accepted in values delivered by interpolation:
+    
+        {
+        "command": {
+            "type": "String",
+            "description": "Command to execute",
+            "interpolationType": "ENV_VAR",
+                "allowedPattern": "^[^"]*$"
+        }
+    }
+
+  * When using interpreted languages like Python, Ruby, or Node.js, reference parameters using the appropriate environment variable syntax:
+    
+        # Python example
+    import os
+    command = os.environ['SSM_Message']
+
+  * For backwards compatibility with older SSM Agent versions (prior to version 3.3.2746.0), include fallback logic for environment variables:
+    
+        if [ -z "${SSM_command+x}" ]; then
+        export SSM_command="{{command}}"
+    fi
+
+  * Combine environment variable interpolation with `allowedPattern` for additional input validation. In the following example, the `allowedPattern` value `^[^"]*$` specifically prevent double-quotes in the string value:
+    
+        {
+        "command": {
+            "type": "String",
+            "interpolationType": "ENV_VAR",
+            "allowedPattern": "^[a-zA-Z0-9_-]+$"
+        }
+    }
+
+  * Before implementing your SSM document, verify the following security considerations:
+
+    * All string parameters that accept user input use environment variable interpolation when appropriate.
+
+    * Input validation is implemented using `allowedPattern` where possible.
+
+    * The document includes appropriate error handling for parameter processing.
+
+    * Backwards compatibility is maintained for environments using older SSM Agent versions.
+
+
+
+