Best practice considerations when using AWS Systems Manager document sharing

An AWS Systems Manager (SSM) document is a resource that defines actions to perform on your managed instances. Each type—command documents, Automation documents, and session documents—serves a purpose. Depending on your use cases, you might use them to automate backup procedures for your applications, install packages, or use them across your fleet of instances for other DevOps scenarios. You can share SSM documents across your accounts or publicly to the AWS community. In this blog post, we will review best practices and guardrail considerations for SSM documents as they relate to sharing documents publicly.

The ability to share documents publicly is controlled through the Block public sharing setting. If this setting is enabled, your SSM documents cannot be shared publicly. The setting is per account and it is regional, so if you’re operating multiple accounts across more than one AWS Region, you’ll need to manage this setting in each account and operating Region.

Block public sharing of SSM documents

Unless you have a use case that requires public sharing of SSM documents, we recommend that you enable the Block public sharing setting. By default, this setting is disabled. You must set it for each account and Region. If you’re operating a multi-account landing zone, this setting should be centrally governed as new accounts are created.

You can use the console or the AWS CLI to enable it.

To block public sharing of SSM documents (console)

1. Open the AWS Systems Manager console.
2. In the navigation pane, under Shared Resources, choose Documents.
3. Choose Preferences.

Figure 1: Documents page in Systems Manager console

4. On the Preferences page, choose Edit.

Figure 2: Preferences page

5. Under Public sharing setting, select Block public sharing and then choose Save.

Figure 3: Block public sharing

The setting is now enabled for the account and Region.

Figure 4: Block public sharing is now set

To block public sharing of SSM documents (AWS CLI)

1. Open a command line configured with the AWS CLI and your AWS account credentials.
2. Run the following command to disable public sharing of SSM documents. Replace 'us-east-1' with your AWS Region.

aws ssm update-service-setting  \
    --setting-id /ssm/documents/console/public-sharing-permission \
    --setting-value Disable \
    --region 'us-east-1'

3. Run the following command to confirm that the block public sharing setting has been disabled. Replace 'us-east-1' with your AWS Region.

aws ssm get-service-setting   \
    --setting-id /ssm/documents/console/public-sharing-permission \
    --region 'us-east-1'

4. Compare your output to the following sample output to confirm the setting is disabled for your account and Region.

{
    "ServiceSetting": {
        "SettingId": "/ssm/documents/console/public-sharing-permission",
        "SettingValue": "Disable",
        "LastModifiedDate": "2021-06-02T15:59:15.862000-04:00",
        "LastModifiedUser": "arn:aws:sts::111122223333:assumed-role/devops-admin",
        "ARN": "arn:aws:ssm:us-east-1: 111122223333:servicesetting/ssm/documents/console/public-sharing-permission",
        "Status": "Customized"
    }
}

Remove shared documents

The Block public sharing setting prevents any new documents from being shared publicly. If you’re blocking the public sharing of SSM documents on an existing account, check the existing documents in the account to find any that are currently publicly shared and decide if they should still be shared publicly or should become private.

To remove public sharing of an SSM document (console)

1. Open the AWS Systems Manager console.
2. In the navigation pane, under Shared Resources, choose Documents.
3. Choose the Owned by me tab and execute the following for each document:
   • Choose the document.
   • In the document details, review the Permissions section to determine where the document is shared.
   • Remove public sharing from the document where appropriate.

To remove public sharing of an SSM document (AWS CLI)

1. Open a command line configured with the AWS CLI and your AWS account credentials for your AWS Region.
2. Run the list-documents command for documents owned by your account in the AWS Region.

aws ssm list-documents \
    --filters Key=Owner,Values=Self

3. For each document, run the following command to determine where it is shared. Replace YourDocumentNameHere with each document returned from list-documents.

aws ssm describe-document-permission \
    --name YourDocumentNameHere \
    --permission-type Share

4. Run the following command to modify document permissions where public sharing is configured. Replace YourDocumentNameHere with your document name.

aws ssm modify-document-permission \
    --name YourDocumentNameHere \
    --permission-type Share \
    --account-ids-to-remove All

Governance considerations

Your organization should use governance and guardrails to control which IAM principals can change the Block public sharing setting and monitor the setting for any unauthorized changes. The following service control policy (SCP) is an example of a guardrail. Your organization can use it to implement a deny upon changes to the setting. You can extend the policy to exclude automation service roles from the deny while preventing other unauthorized principals from changing the setting.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DenySSMDocPublicSharingSetting",
      "Effect": "Deny",
      "Action": [ "ssm:UpdateServiceSetting", "ssm:ResetServiceSetting" ],
      "Resource": "arn:aws:ssm:*:*:servicesetting/ssm/documents/console/public-sharing-permission"
    }
  ]
}

While the SCP described earlier are a preventive guardrail and prevents any changes to the “Block public sharing” setting, you can use AWS Config as a detective guardrail. AWS Config can be used to detect and then optionally remediate any changes to the “Block public sharing” setting. In order to detect changes to this setting you need to implement a custom AWS Config rule. You can optionally implement a remediation action for the “Block public sharing” setting.

Best practices for sharing SSM documents

If your use case requires the public sharing of SSM documents, here are best practices you should follow:

Control how documents are shared

With the Block public sharing setting disabled, users can share documents publicly. Implement guardrails to allow only an agreed-upon set of documents to be shared publicly and only by authorized principals. You can implement these guardrails through IAM policies that grant permission through the ModifyDocumentPermission setting.

Remove identifying and sensitive information

Always ensure that sensitive information such as keys, passwords, and user names are properly handled, fetched dynamically, or parameterized. Do not include sensitive information in your documents.

You should not store identifiers to your resources in your documents. Instead, use parameters for those types of values. This includes things such as resource ARNs or other identifiers that may disclose information about your environment.

If you find a document that is shared and has information that needs to be removed, remember that SSM documents are versioned, so any earlier versions are still in your history. In that case, delete the document and create one in its place.

Keep internal process documents private

If you’re operating multiple accounts, it might be appropriate to share some types of documents (for example, an SSM document used for internal processes such as backup and deployment) with your trusted set of accounts. These documents might disclose sensitive or confidential information about internal processes and infrastructure. As a best practice, avoid sharing documents related to your internal processes such as backup and deployment publicly or with untrusted accounts.

Conclusion

In this post, we shared procedures, best practices, and some ideas for tuning your organization’s security posture by applying governance and guardrails for the public sharing of SSM documents.

As a next step, make time to review your AWS accounts to ensure the public sharing of SSM documents complies with your organization’s security posture. Apply the best practices discussed here. For more information, see Best practices for shared SSM documents in the AWS Systems Manager User Guide.

About the authors